diff --git a/docs/user-manual/editor/publishing/index.md b/docs/user-manual/editor/publishing/index.md index 788aab2f793..e2ec2edc51d 100644 --- a/docs/user-manual/editor/publishing/index.md +++ b/docs/user-manual/editor/publishing/index.md @@ -1,6 +1,6 @@ --- title: Publishing -description: Maps PlayCanvas publishing paths across web browsers, mobile wrappers, desktop packaging, and playable ad networks. +description: Maps PlayCanvas publishing paths across web browsers, mobile wrappers, desktop packaging, playable ad networks, and Snapchat Web Lenses. --- Once you have built your game, you will no doubt want to publish it and allow people to enjoy its majesty! PlayCanvas makes things very easy for you to target just about any operating system or app store. @@ -11,3 +11,4 @@ Once you have built your game, you will no doubt want to publish it and allow pe * [Mobile](/user-manual/editor/publishing/mobile) * [Desktop](/user-manual/editor/publishing/desktop) * [Playable Ads](/user-manual/editor/publishing/playable-ads) +* [Snapchat Web Lenses](/user-manual/editor/publishing/snapchat-web-lenses) diff --git a/docs/user-manual/editor/publishing/snapchat-web-lenses.md b/docs/user-manual/editor/publishing/snapchat-web-lenses.md new file mode 100644 index 00000000000..ce8c729407e --- /dev/null +++ b/docs/user-manual/editor/publishing/snapchat-web-lenses.md @@ -0,0 +1,28 @@ +--- +title: Snapchat Web Lenses +description: Publish a PlayCanvas Editor project to Snapchat as a Web Lens, with the Web Lens API included in the build. +--- + +A [Snapchat Web Lens](https://developers.snap.com/web-lenses/home) is a web app that runs inside Snapchat as a Lens, full screen and in portrait, on iOS and Android. This page explains how to publish an Editor project as one. For a code project, start from the [Snapchat Web Lens starter](/user-manual/getting-started/start-with-create-playcanvas/#snapchat-web-lens-starter) instead. + +Before you publish, check your game against Snap's [Platform requirements](https://developers.snap.com/web-lenses/requirements) and [Capabilities and restrictions](https://developers.snap.com/web-lenses/capabilities). In particular, a Lens runs in portrait and can load files only from its own zip, so your project must not load anything from another host. + +## Add the Web Lens API + +The [Web Lens API](https://developers.snap.com/web-lenses/web-lens-api) gives your game leaderboards, the player's Bitmoji, and storage that lasts between launches. To add it to your project: + +1. Download `snap-api.js` from the `dist` folder of the [`@snap/web-lens-api`](https://www.npmjs.com/package/@snap/web-lens-api) package. +2. Upload it to your project as a script asset. +3. In the asset's Inspector, set **Loading Type** to **Before Engine**. + +The script installs the API as `window.snapchat`, so your scripts can call `snapchat.init()` at startup and check `snapchat.isSupported()` before using each capability. The API must ship inside your zip, so do not add it under **Settings > External Scripts**. Outside Snapchat, including on the Launch page, the API answers from a built-in stub with canned data. + +## Download and Zip the Build + +1. [Download a build](/user-manual/editor/publishing/web/self-hosting/) of your project from the **Publish** dialog. +2. Zip the *contents* of the build folder, so that `index.html` sits at the root of the zip rather than inside a folder. On Windows, avoid PowerShell's `Compress-Archive`, which writes backslashes into the zip that break relative paths. +3. Check the zip with `unzip -l`. It must be no more than 8 MB, and `index.html` no more than 1 MB. + +## Upload to Snapchat + +Sign in to [My Lenses](https://my-lenses.snapchat.com/), create a new Lens, choose the Web Lens option, and upload your zip. Snap's [Publishing](https://developers.snap.com/web-lenses/publishing) guide covers the details you add, such as the icon and the preview video, and the review process. diff --git a/docs/user-manual/getting-started/index.md b/docs/user-manual/getting-started/index.md index 881e81e7360..5b0ce103d70 100644 --- a/docs/user-manual/getting-started/index.md +++ b/docs/user-manual/getting-started/index.md @@ -16,7 +16,7 @@ PlayCanvas is a collection of open-source products that you can use to build int ## Start a Code Project -Use [`create-playcanvas`](start-with-create-playcanvas) to scaffold a Vite and TypeScript project for the Engine, React, or Web Components from one of 12 runnable starters. New projects include [PlayCanvas Skills](use-playcanvas-skills), which give compatible AI coding agents PlayCanvas-specific development and verification workflows. +Use [`create-playcanvas`](start-with-create-playcanvas) to scaffold a Vite and TypeScript project for the Engine, React, or Web Components from one of its runnable starters. New projects include [PlayCanvas Skills](use-playcanvas-skills), which give compatible AI coding agents PlayCanvas-specific development and verification workflows. ## Coming from Unity diff --git a/docs/user-manual/getting-started/start-with-create-playcanvas.md b/docs/user-manual/getting-started/start-with-create-playcanvas.md index 23bf1f25b91..88263113030 100644 --- a/docs/user-manual/getting-started/start-with-create-playcanvas.md +++ b/docs/user-manual/getting-started/start-with-create-playcanvas.md @@ -33,6 +33,8 @@ npm install npm run dev ``` +When you are ready to deploy, run `npm run build` to create a production build. Its URLs are relative, so it works from any folder on a server, not only from the root of a domain. + ## Choose a Format Every format uses TypeScript and includes Vite, ESLint, Prettier, and a production build. @@ -45,20 +47,42 @@ Every format uses TypeScript and includes Vite, ESLint, Prettier, and a producti ## Choose a Starter -The creator provides the same 12 runnable starters for every format: +The creator provides the same runnable starters for every format: -![The twelve create-playcanvas starter scenes](/img/user-manual/getting-started/create-playcanvas-starters.webp) +![The create-playcanvas starter scenes](/img/user-manual/getting-started/create-playcanvas-starters.webp) | Category | Starters | | --- | --- | | Basics | Spinning Cube, Interactive Sphere | | Viewers | Model Viewer, Splat Viewer, Product Configurator | -| Games | Physics Playground, First-Person Controller, Third-Person Controller, Sprite Game | +| Games | Physics Playground, First-Person Controller, Third-Person Controller, Sprite Game, Snapchat Web Lens | | Tools | Scene Editor | | XR | VR Starter, AR Placement | Choose the starter closest to the application you want to build, run it unchanged first, and then replace its assets and behavior incrementally. +## Snapchat Web Lens Starter + +The Snapchat Web Lens starter is a portrait game set up to run inside Snapchat as a [Web Lens](https://developers.snap.com/web-lenses/home): + +```sh +npm create playcanvas@latest my-lens -- --starter web-lens +``` + +It is set up for Snap's [platform requirements](https://developers.snap.com/web-lenses/requirements): a portrait layout that keeps the heads-up display (HUD) clear of Snapchat's controls, relative URLs in the build, and no requests to other hosts. Through the [Web Lens API](https://developers.snap.com/web-lenses/web-lens-api), it submits each run to the leaderboard, keeps the player's best score in Snapchat storage, and shows their Bitmoji. Outside Snapchat, the API answers from a built-in stub, so the game runs in any browser. + +To make it your own, replace the game in `src/dodge-game.ts` and keep the rest. The project's README lists which files to replace and which to keep. + +When your game is ready, package it: + +```sh +npm run package +``` + +This builds the game, checks the build against Snap's upload rules, and writes a zip to `dist/`. If a check fails, it names the file to fix and writes no zip. Upload the zip through [My Lenses](https://my-lenses.snapchat.com/), following Snap's [Publishing](https://developers.snap.com/web-lenses/publishing) guide. + +To publish an Editor project as a Web Lens instead, see [Snapchat Web Lenses](/user-manual/editor/publishing/snapchat-web-lenses/). + ## Debug with the Inspector The development server loads the [Inspector](/user-manual/scripting/debugging/inspector/) for the running application. Press the backquote key (`` ` ``) to show or hide it, F9 to pause, and F10 to step one frame. Production builds do not include the Inspector. @@ -71,6 +95,8 @@ Pass a project name, format, and starter to create a project non-interactively: npm create playcanvas@latest my-viewer -- -f react -s model-viewer ``` +When there is no terminal to answer the prompts, as when an AI coding agent or an automated build runs the command, the creator takes the defaults for any option you do not pass, as `--yes` does. It still stops with an error when a choice has no safe default, such as a non-empty target directory without `--overwrite`. + | Option | Shorthand | Purpose | | --- | --- | --- | | `--format ` | `-f` | Choose `engine`, `react`, or `web-components`. | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/editor/publishing/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/editor/publishing/index.md index 979b79c5372..1aff33377f9 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/editor/publishing/index.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/editor/publishing/index.md @@ -1,6 +1,6 @@ --- title: プロジェクトの公開方法 -description: Web ブラウザ、モバイルラッパー、デスクトップパッケージング、プレイアブル広告ネットワークにわたる PlayCanvas の公開パスを一覧します。 +description: Web ブラウザ、モバイルラッパー、デスクトップパッケージング、プレイアブル広告ネットワーク、Snapchat Web Lens にわたる PlayCanvas の公開パスを一覧します。 --- ゲームの構築が完了したら、それを公開して皆にプレイしてもらいましょう！PlayCanvasでは、如何なるOSやappストアを容易にターゲットできます。 @@ -11,3 +11,4 @@ description: Web ブラウザ、モバイルラッパー、デスクトップパ * [モバイル](/user-manual/editor/publishing/mobile) * [デスクトップ](/user-manual/editor/publishing/desktop) * [プレイアブル広告](/user-manual/editor/publishing/playable-ads) +* [Snapchat Web Lens](/user-manual/editor/publishing/snapchat-web-lenses) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/editor/publishing/snapchat-web-lenses.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/editor/publishing/snapchat-web-lenses.md new file mode 100644 index 00000000000..e8b87d4cf2a --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/editor/publishing/snapchat-web-lenses.md @@ -0,0 +1,28 @@ +--- +title: Snapchat Web Lens +description: Web Lens APIをビルドに含めて、PlayCanvas EditorのプロジェクトをSnapchatにWeb Lensとして公開します。 +--- + +[Snapchat Web Lens](https://developers.snap.com/web-lenses/home)は、Snapchatの中でLensとして動作するWebアプリです。iOSとAndroidで、全画面かつ縦向きで実行されます。このページでは、EditorのプロジェクトをWeb Lensとして公開する方法を説明します。コードプロジェクトの場合は、代わりに[Snapchat Web Lensスターター](/user-manual/getting-started/start-with-create-playcanvas/#snapchat-web-lens-starter)から始めてください。 + +公開する前に、Snapの[Platform requirements](https://developers.snap.com/web-lenses/requirements)と[Capabilities and restrictions](https://developers.snap.com/web-lenses/capabilities)に照らしてゲームを確認してください。特に、Lensは縦向きで実行され、自身のzip内のファイルしか読み込めないため、プロジェクトは別のホストから何も読み込まないようにする必要があります。 + +## Web Lens APIを追加する {#add-the-web-lens-api} + +[Web Lens API](https://developers.snap.com/web-lenses/web-lens-api)を使用すると、リーダーボード、プレイヤーのBitmoji、起動をまたいで保持されるストレージをゲームで利用できます。プロジェクトに追加するには、次の手順に従います。 + +1. [`@snap/web-lens-api`](https://www.npmjs.com/package/@snap/web-lens-api)パッケージの`dist`フォルダーから`snap-api.js`をダウンロードします。 +2. スクリプトアセットとしてプロジェクトにアップロードします。 +3. アセットのInspectorで、**Loading Type**を**Before Engine**に設定します。 + +このスクリプトはAPIを`window.snapchat`としてインストールするため、スクリプトから起動時に`snapchat.init()`を呼び出し、各機能を使用する前に`snapchat.isSupported()`で確認できます。APIはzipに同梱する必要があるため、**Settings > External Scripts**には追加しないでください。Launchページを含むSnapchatの外では、APIは組み込みのスタブが固定のデータで応答します。 + +## ビルドをダウンロードしてzipにする {#download-and-zip-the-build} + +1. **Publish**ダイアログからプロジェクトの[ビルドをダウンロード](/user-manual/editor/publishing/web/self-hosting/)します。 +2. `index.html`がフォルダーの中ではなくzipのルートに来るように、ビルドフォルダーの*中身*をzipにします。Windowsでは、相対パスを壊すバックスラッシュをzipに書き込むPowerShellの`Compress-Archive`は使用しないでください。 +3. `unzip -l`でzipを確認します。zipは8 MB以下、`index.html`は1 MB以下である必要があります。 + +## Snapchatにアップロードする {#upload-to-snapchat} + +[My Lenses](https://my-lenses.snapchat.com/)にサインインし、新しいLensを作成してWeb Lensのオプションを選び、zipをアップロードします。アイコンやプレビュー動画など追加する情報と審査の流れについては、Snapの[Publishing](https://developers.snap.com/web-lenses/publishing)ガイドを参照してください。 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/getting-started/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/getting-started/index.md index 163bd7b14bf..04647574089 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/getting-started/index.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/getting-started/index.md @@ -16,7 +16,7 @@ PlayCanvasは、インタラクティブでグラフィカルなウェブアプ ## コードプロジェクトを始める -[`create-playcanvas`](start-with-create-playcanvas)を使用すると、12個の実行可能なスターターからEngine、React、またはWeb Components用のViteとTypeScriptプロジェクトを作成できます。新しいプロジェクトには、対応するAIコーディングエージェントにPlayCanvas固有の開発と検証ワークフローを提供する[PlayCanvas Skills](use-playcanvas-skills)が含まれます。 +[`create-playcanvas`](start-with-create-playcanvas)を使用すると、実行可能なスターターからEngine、React、またはWeb Components用のViteとTypeScriptプロジェクトを作成できます。新しいプロジェクトには、対応するAIコーディングエージェントにPlayCanvas固有の開発と検証ワークフローを提供する[PlayCanvas Skills](use-playcanvas-skills)が含まれます。 ## Unityから移行する場合 {#coming-from-unity} diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/getting-started/start-with-create-playcanvas.md b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/getting-started/start-with-create-playcanvas.md index f3d1e6ec0f3..5143a33b089 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/getting-started/start-with-create-playcanvas.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/user-manual/getting-started/start-with-create-playcanvas.md @@ -33,6 +33,8 @@ npm install npm run dev ``` +デプロイの準備ができたら、`npm run build`を実行してプロダクションビルドを作成します。URLは相対パスなので、ドメインのルートだけでなく、サーバー上のどのフォルダーからでも動作します。 + ## 形式を選択する すべての形式でTypeScriptを使用し、Vite、ESLint、Prettier、プロダクションビルドが含まれます。 @@ -45,20 +47,42 @@ npm run dev ## スターターを選択する -creatorでは、すべての形式で同じ12個の実行可能なスターターを利用できます。 +creatorでは、すべての形式で同じ実行可能なスターターを利用できます。 -![create-playcanvasの12個のスターターシーン](/img/user-manual/getting-started/create-playcanvas-starters.webp) +![create-playcanvasのスターターシーン](/img/user-manual/getting-started/create-playcanvas-starters.webp) | カテゴリ | スターター | | --- | --- | | 基本 | Spinning Cube、Interactive Sphere | | ビューアー | Model Viewer、Splat Viewer、Product Configurator | -| ゲーム | Physics Playground、First-Person Controller、Third-Person Controller、Sprite Game | +| ゲーム | Physics Playground、First-Person Controller、Third-Person Controller、Sprite Game、Snapchat Web Lens | | ツール | Scene Editor | | XR | VR Starter、AR Placement | 構築するアプリケーションに最も近いスターターを選び、まず変更せずに実行してから、アセットと動作を段階的に置き換えます。 +## Snapchat Web Lensスターター {#snapchat-web-lens-starter} + +Snapchat Web Lensスターターは、Snapchatの中で[Web Lens](https://developers.snap.com/web-lenses/home)として動作するように設定された縦向きのゲームです。 + +```sh +npm create playcanvas@latest my-lens -- --starter web-lens +``` + +このスターターは、Snapの[プラットフォーム要件](https://developers.snap.com/web-lenses/requirements)に合わせて設定されています。ヘッドアップディスプレイ（HUD）をSnapchatのコントロールから離して配置する縦向きのレイアウト、ビルド内の相対URL、別のホストへのリクエストがないことです。また、[Web Lens API](https://developers.snap.com/web-lenses/web-lens-api)を通じて各プレイのスコアをリーダーボードに送信し、プレイヤーのベストスコアをSnapchatのストレージに保存し、プレイヤーのBitmojiを表示します。Snapchatの外では、APIが組み込みのスタブで応答するため、どのブラウザーでもゲームを実行できます。 + +自分のゲームにするには、`src/dodge-game.ts`のゲームを置き換え、それ以外はそのまま残します。プロジェクトのREADMEに、置き換えるファイルと残すファイルが記載されています。 + +ゲームの準備ができたら、パッケージ化します。 + +```sh +npm run package +``` + +このコマンドはゲームをビルドし、Snapのアップロードのルールに照らしてビルドを確認し、`dist/`にzipを書き出します。確認に失敗した場合は、修正するファイルを示し、zipは書き出しません。zipは、Snapの[Publishing](https://developers.snap.com/web-lenses/publishing)ガイドに従って[My Lenses](https://my-lenses.snapchat.com/)からアップロードします。 + +EditorのプロジェクトをWeb Lensとして公開する場合は、[Snapchat Web Lens](/user-manual/editor/publishing/snapchat-web-lenses/)を参照してください。 + ## Inspectorでデバッグする 開発サーバーは、実行中のアプリケーション用に[Inspector](/user-manual/scripting/debugging/inspector/)を読み込みます。バッククォートキー（`` ` ``）で表示と非表示を切り替え、F9で一時停止し、F10で1フレームずつ進めます。Inspectorはプロダクションビルドには含まれません。 @@ -71,6 +95,8 @@ creatorでは、すべての形式で同じ12個の実行可能なスタータ npm create playcanvas@latest my-viewer -- -f react -s model-viewer ``` +AIコーディングエージェントや自動ビルドがコマンドを実行する場合のように、プロンプトに答えるターミナルがないときは、`--yes`と同様に、指定しなかったオプションにはデフォルトを使用します。ただし、`--overwrite`を指定せずに空でないターゲットディレクトリを選んだ場合など、安全なデフォルトがない選択ではエラーで停止します。 + | オプション | 短縮形 | 用途 | | --- | --- | --- | | `--format ` | `-f` | `engine`、`react`、`web-components`から選択します。 | diff --git a/llms/user-manual/editor/llms.txt b/llms/user-manual/editor/llms.txt index bfe14635d3d..3f0c3db416b 100644 --- a/llms/user-manual/editor/llms.txt +++ b/llms/user-manual/editor/llms.txt @@ -130,6 +130,7 @@ Use this index for projects made in the Editor, where code lives in scripts atta - [Downloading Projects](/user-manual/editor/projects/downloading/): The static and npm package formats of downloaded projects. - [Communication with web pages](/user-manual/editor/publishing/web/communicating-webpage/): Messaging between an app and the page that hosts it. - [Playable Ads](/user-manual/editor/publishing/playable-ads/): Exporting playable ads for Facebook and Snapchat. +- [Snapchat Web Lenses](/user-manual/editor/publishing/snapchat-web-lenses/): Publishing a build on Snapchat as a Web Lens, with the Web Lens API loaded before the engine. ## API reference diff --git a/llms/user-manual/engine/llms.txt b/llms/user-manual/engine/llms.txt index 1cdc6c7345a..f42c23a1980 100644 --- a/llms/user-manual/engine/llms.txt +++ b/llms/user-manual/engine/llms.txt @@ -29,6 +29,7 @@ Use this index to write code against the engine directly. React, Web Components - [Using the Engine Standalone](/user-manual/engine/standalone/): Setting up an `AppBase` project with Vite and npm, or without a build step using an import map and the CDN build, and registering the component systems and resource handlers it uses. - [Start with create-playcanvas](/user-manual/getting-started/start-with-create-playcanvas/): `npm create playcanvas@latest my-app -- -f engine` creates a runnable Vite and TypeScript project, with PlayCanvas Skills for coding agents. +- [Snapchat Web Lens starter](/user-manual/getting-started/start-with-create-playcanvas/#snapchat-web-lens-starter): A portrait game set up for Snapchat Web Lenses, with the Web Lens API wired up and `npm run package` to check and zip the build. - [Developing with AI](/user-manual/engine/developing-with-ai/): Setting up a coding agent on an Engine project and verifying its changes in a browser. - [Engine Migrations](/user-manual/engine/migrations/): The breaking changes of each major release. Read it before using an API you remember from Engine 1. - [Supported Browsers](/user-manual/engine/supported-browsers/): Minimum browser versions for WebGL2 and WebGPU. diff --git a/sidebars.js b/sidebars.js index 1968c877828..f655aab2635 100644 --- a/sidebars.js +++ b/sidebars.js @@ -404,6 +404,7 @@ const sidebars = { 'user-manual/editor/publishing/playable-ads/snapchat-playable-ads', ], }, + 'user-manual/editor/publishing/snapchat-web-lenses', ], }, 'user-manual/editor/editor-api',