create-playcanvas 0.10.1 → 0.11.1

package/templates/_shared/web-lens/src/lens.ts

@@ -0,0 +1,91 @@
+import snapchat from '@snap/web-lens-api';
+
+// Everything the game asks of Snapchat goes through here. Outside Snapchat, the Web Lens API
+// answers from a built-in stub with canned data, so the game runs in any browser. Inside it, any
+// call can still fail, so each one falls back to playing on without the feature
+
+const BEST_KEY = 'best';
+
+let ready: Promise<void> | undefined;
+let best: Promise<number> | undefined;
+let avatar: Promise<string | undefined> | undefined;
+let saving = Promise.resolve();
+let submitting = Promise.resolve();
+
+// set once the first read succeeds. If it fails, saving stays off for the session rather than
+// writing over a best score it couldn't read
+let loaded = false;
+
+const warn = (feature: string) => (err: Error) => console.warn(`Web Lens ${feature} unavailable:`, err.message);
+
+// phone browsers report only their own notch, so in development reserve the room Snapchat's own
+// controls take at the top of the Lens (see lens.css)
+if (import.meta.env.DEV) document.documentElement.classList.add('simulate-insets');
+
+/** Discovers what this host serves. Every other call here waits for it. */
+export const initLens = () => (ready ??= snapchat.init().then(() => undefined, warn('API')));
+
+/** Whether Snapchat can show this Lens's leaderboard. Valid once {@link initLens} resolves. */
+export const hasLeaderboard = () => snapchat.isSupported('leaderboards');
+
+/**
+ * Resolves the player's best score. Snapchat storage keeps it between launches, where
+ * `localStorage` starts empty every time the Lens opens.
+ */
+export const loadBest = () =>
+    (best ??= initLens().then(async () => {
+        if (!snapchat.isSupported('storage')) return 0;
+
+        try {
+            // the first read opens the store, which can take seconds on a cold start
+            const result = await snapchat.storage.get(BEST_KEY);
+            loaded = true;
+            return result.found && typeof result.value === 'number' ? result.value : 0;
+        } catch (err) {
+            warn('storage')(err as Error);
+            return 0;
+        }
+    }));
+
+/** Submits a finished run to the leaderboard and keeps the player's best. Resolves the best score. */
+export const recordScore = (score: number) => {
+    submitting = initLens().then(() => {
+        if (!snapchat.isSupported('leaderboards')) return;
+        return snapchat.leaderboards
+            .submitScore({ score: Math.round(score) })
+            .then(() => undefined, warn('leaderboard'));
+    });
+
+    // each run waits for the first read and for the runs before it, so two runs that end while the
+    // read is still loading can't both compare against the same old best
+    best = loadBest().then((previous) => {
+        if (score <= previous) return previous;
+
+        // keep one write in flight at a time, and the chain going after a failed save
+        if (loaded) saving = saving.then(() => snapchat.storage.set(BEST_KEY, score)).catch(warn('storage'));
+        return score;
+    });
+    return best;
+};
+
+/** Opens Snapchat's leaderboard panel, once the latest score has reached it. */
+export const showLeaderboard = async () => {
+    await submitting;
+    await snapchat.leaderboards.show().catch(warn('leaderboard'));
+};
+
+/** Resolves a URL for the player's Bitmoji portrait, or `undefined` if there is none to show. */
+export const loadAvatar = () =>
+    (avatar ??= initLens().then(async () => {
+        // the desktop stub's avatar is an empty placeholder, so show none there
+        if (!snapchat.isSupported('bitmoji') || snapchat.isStub) return undefined;
+
+        try {
+            const { hasAvatar } = await snapchat.bitmoji.getAvatarInfo();
+            // the URL expires after about five minutes, so show it as soon as it resolves
+            return hasAvatar ? (await snapchat.bitmoji.get2DAvatar()).url : undefined;
+        } catch (err) {
+            warn('Bitmoji')(err as Error);
+            return undefined;
+        }
+    }));

package/templates/engine/base/README.md

@@ -32,7 +32,7 @@ Open <http://localhost:5173>. Edit the files under `src/` and save to see the sc
 | `npm run fmt`       | Check formatting                  |
 | `npm run typecheck` | Run TypeScript checks             |
 
-Run `npm run build` to generate a deployable static site in `dist/`.
+Run `npm run build` to generate a deployable static site in `dist/`. Its paths are relative, so it runs from any folder, such as a GitHub Pages project site or an itch.io upload.
 
 ## Agent skills
 

package/templates/engine/base/package.json

@@ -15,15 +15,15 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "playcanvas": "^2.23.1"
+        "playcanvas": "^2.23.3"
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
-        "@playcanvas/inspector": "^0.2.0",
+        "@playcanvas/inspector": "^0.3.0",
         "eslint": "^9.39.5",
-        "prettier": "^3.9.9",
+        "prettier": "^3.9.10",
         "typescript": "~6.0.3",
-        "vite": "^8.3.4"
+        "vite": "^8.3.5"
     },
     "engines": {
         "node": ">=22.23.2"

package/templates/engine/base/vite.config.ts

@@ -2,6 +2,9 @@ import { defineConfig } from 'vite';
 
 // https://vite.dev/config/
 export default defineConfig({
+    // Relative URLs, so the build runs wherever it's served from: a domain root, a subpath such as
+    // GitHub Pages or itch.io, or a Snapchat Web Lens
+    base: './',
     plugins: [
         {
             // Dev only: install the PlayCanvas Inspector before the app starts (press ` to toggle)

package/templates/engine/first-person-controller/src/main.ts

@@ -21,9 +21,8 @@ import { addFirstPersonController } from './controller';
 import './starter.css';
 
 WasmModule.setConfig('Ammo', {
-    glueUrl: '/ammo/ammo.wasm.js',
-    wasmUrl: '/ammo/ammo.wasm.wasm',
-    fallbackUrl: '/ammo/ammo.js'
+    glueUrl: './ammo/ammo.wasm.js',
+    wasmUrl: './ammo/ammo.wasm.wasm'
 });
 await new Promise<void>((resolve) => {
     WasmModule.getInstance('Ammo', () => resolve());

package/templates/engine/interactive-sphere/src/App.ts

@@ -36,7 +36,7 @@ const assets = {
     envAtlas: new Asset(
         'env-atlas',
         'texture',
-        { url: '/environment-map.png' },
+        { url: './environment-map.png' },
         {
             type: TEXTURETYPE_RGBP,
             mipmaps: false

package/templates/engine/interactive-sphere/src/main.ts

@@ -1,12 +1,10 @@
-import './style.css';
 import { setupApp } from './App';
+import './counter.css';
+import './starter.css';
 
 let count = 0;
 
-document.querySelector<HTMLDivElement>('#root')!.innerHTML = `
-    <canvas id="application-canvas"></canvas>
-    <p id="counter" class="counter">Click count: ${count}</p>
-`;
+document.body.insertAdjacentHTML('beforeend', `<p id="counter" class="counter">Click count: ${count}</p>`);
 
 const counterElement = document.getElementById('counter')!;
 

package/templates/engine/model-viewer/src/main.ts

@@ -17,10 +17,10 @@ import {
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
 
-import './style.css';
+import './starter.css';
 
-// Swap this for your own model - anything you drop in public/ is served from the site root
-const MODEL_URL = '/playcanvas-cube.glb';
+// Swap this for your own model - files in public/ are served next to index.html, so use a ./ path
+const MODEL_URL = './playcanvas-cube.glb';
 
 const canvas = document.getElementById('application-canvas') as HTMLCanvasElement;
 

package/templates/engine/physics-playground/src/main.ts

@@ -30,9 +30,8 @@ const SCALES: [number, number, number][] = [
 ];
 
 WasmModule.setConfig('Ammo', {
-    glueUrl: '/ammo/ammo.wasm.js',
-    wasmUrl: '/ammo/ammo.wasm.wasm',
-    fallbackUrl: '/ammo/ammo.js'
+    glueUrl: './ammo/ammo.wasm.js',
+    wasmUrl: './ammo/ammo.wasm.wasm'
 });
 await new Promise<void>((resolve) => {
     WasmModule.getInstance('Ammo', () => resolve());

package/templates/engine/spinning-cube/src/main.ts

@@ -13,7 +13,7 @@ import {
     createGraphicsDevice
 } from 'playcanvas';
 
-import './style.css';
+import './starter.css';
 
 const canvas = document.getElementById('application-canvas') as HTMLCanvasElement;
 

package/templates/engine/splat-viewer/src/main.ts

@@ -16,7 +16,7 @@ import {
 } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 
-import './style.css';
+import './starter.css';
 
 // Hosted so the template stays small. Capture or edit your own splat at https://superspl.at, then
 // drop the .sog or .ply in public/ and point this at it instead

package/templates/engine/third-person-controller/src/main.ts

@@ -42,9 +42,8 @@ const PINE_LAYERS: [number, number, number][] = [
 ];
 
 WasmModule.setConfig('Ammo', {
-    glueUrl: '/ammo/ammo.wasm.js',
-    wasmUrl: '/ammo/ammo.wasm.wasm',
-    fallbackUrl: '/ammo/ammo.js'
+    glueUrl: './ammo/ammo.wasm.js',
+    wasmUrl: './ammo/ammo.wasm.wasm'
 });
 await new Promise<void>((resolve) => {
     WasmModule.getInstance('Ammo', () => resolve());

package/templates/engine/web-lens/index.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+        <title>Dodge</title>
+    </head>
+    <body>
+        <main class="lens">
+            <canvas id="application-canvas"></canvas>
+            <div class="lens-hud">
+                <header class="lens-bar">
+                    <img class="lens-avatar" alt="Your Bitmoji" hidden />
+                    <span class="lens-score">0</span>
+                    <span class="lens-best">Best 0</span>
+                </header>
+                <section class="lens-card">
+                    <h1 class="lens-title">Dodge</h1>
+                    <button class="lens-leaderboard" hidden>Leaderboard</button>
+                    <p class="lens-hint">Drag to steer. Tap to play</p>
+                </section>
+            </div>
+        </main>
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>

package/templates/engine/web-lens/src/main.ts

@@ -0,0 +1,89 @@
+import {
+    AppBase,
+    AppOptions,
+    CameraComponentSystem,
+    Color,
+    Entity,
+    FILLMODE_NONE,
+    LightComponentSystem,
+    RESOLUTION_AUTO,
+    RenderComponentSystem,
+    ScriptComponentSystem,
+    createGraphicsDevice
+} from 'playcanvas';
+
+import { CARDS, DodgeGame } from './dodge-game';
+import type { GameState } from './dodge-game';
+import { hasLeaderboard, loadAvatar, loadBest, recordScore, showLeaderboard } from './lens';
+import './lens.css';
+
+const canvas = document.getElementById('application-canvas') as HTMLCanvasElement;
+const device = await createGraphicsDevice(canvas);
+device.maxPixelRatio = Math.min(window.devicePixelRatio, 2);
+
+const options = new AppOptions();
+options.graphicsDevice = device;
+options.componentSystems = [RenderComponentSystem, CameraComponentSystem, LightComponentSystem, ScriptComponentSystem];
+
+const app = new AppBase(canvas);
+app.init(options);
+app.start();
+
+// lens.css sizes the canvas, filling a phone screen and centering a 9:16 column anywhere wider,
+// and the drawing buffer follows its size every frame
+app.setCanvasFillMode(FILLMODE_NONE);
+app.setCanvasResolution(RESOLUTION_AUTO);
+
+const camera = new Entity('camera');
+camera.addComponent('camera', {
+    clearColor: new Color().fromString('#0b1020'),
+    fov: 45,
+    // fix the field's width, so a taller phone shows more of the falling blocks
+    horizontalFov: true
+});
+camera.setPosition(0, 0, 7);
+app.root.addChild(camera);
+
+const light = new Entity('light');
+light.addComponent('light', { type: 'directional', intensity: 1.5 });
+light.setEulerAngles(40, 30, 0);
+app.root.addChild(light);
+
+// the HUD follows the game's state, and the Lens records each finished run
+const hud = {
+    avatar: document.querySelector<HTMLImageElement>('.lens-avatar')!,
+    score: document.querySelector('.lens-score')!,
+    best: document.querySelector('.lens-best')!,
+    card: document.querySelector<HTMLElement>('.lens-card')!,
+    title: document.querySelector('.lens-title')!,
+    hint: document.querySelector('.lens-hint')!,
+    leaderboard: document.querySelector<HTMLButtonElement>('.lens-leaderboard')!
+};
+const showBest = (best: number) => {
+    hud.best.textContent = `Best ${best}`;
+};
+
+app.on('game:state', (state: GameState, score: number) => {
+    const card = CARDS[state];
+    hud.score.textContent = String(score);
+    hud.card.hidden = !card;
+    if (card) {
+        hud.title.textContent = card.title;
+        hud.hint.textContent = card.hint;
+    }
+    hud.leaderboard.hidden = state !== 'over' || !hasLeaderboard();
+    if (state === 'over') recordScore(score).then(showBest);
+});
+hud.leaderboard.addEventListener('click', showLeaderboard);
+
+loadBest().then(showBest);
+loadAvatar().then((url) => {
+    if (!url) return;
+    hud.avatar.src = url;
+    hud.avatar.hidden = false;
+});
+
+const game = new Entity('game');
+game.addComponent('script');
+game.script!.create(DodgeGame);
+app.root.addChild(game);

package/templates/engine/web-lens/vite.config.ts

@@ -0,0 +1,44 @@
+import { defineConfig } from 'vite';
+
+// Approximates the Web Lens sandbox, which allows resources from the Lens itself and nothing else
+const LENS_SANDBOX = [
+    "default-src 'self' data: blob:",
+    "script-src 'self' 'unsafe-inline' 'unsafe-eval' 'wasm-unsafe-eval' blob:",
+    "style-src 'self' 'unsafe-inline'",
+    "frame-src 'none'",
+    "object-src 'none'",
+    "base-uri 'none'",
+    "form-action 'none'"
+].join('; ');
+
+// https://vite.dev/config/
+export default defineConfig({
+    // Snapchat serves a Lens from its own origin, so every URL in the build must be relative
+    base: './',
+    build: {
+        // npm run package zips this folder and writes the zip beside it, inside the ignored dist/
+        outDir: 'dist/lens',
+        // source maps only add to the 8 MB upload
+        sourcemap: false
+    },
+    preview: {
+        // npm run start serves the build under the Lens rules, so a request for anything outside
+        // the zip fails in the browser console as it would in Snapchat
+        headers: {
+            'Content-Security-Policy': LENS_SANDBOX,
+            'Cross-Origin-Opener-Policy': 'same-origin',
+            'Cross-Origin-Embedder-Policy': 'require-corp'
+        }
+    },
+    plugins: [
+        {
+            // Dev only: install the PlayCanvas Inspector before the app starts (press ` to toggle)
+            name: 'playcanvas-inspector',
+            apply: 'serve',
+            config: () => ({ optimizeDeps: { include: ['@playcanvas/inspector'] } }),
+            transformIndexHtml: () => [
+                { tag: 'script', attrs: { type: 'module', src: '/src/inspector.ts' }, injectTo: 'head-prepend' }
+            ]
+        }
+    ]
+});

package/templates/index.ts

@@ -90,6 +90,12 @@ export const STARTERS = [
         category: 'Games',
         description: 'an orthographic camera, sprite animation and input'
     },
+    {
+        name: 'web-lens',
+        display: 'Snapchat Web Lens',
+        category: 'Games',
+        description: 'a portrait game with Snapchat leaderboards, packaged for upload'
+    },
     {
         name: 'scene-editor',
         display: 'Scene Editor',

package/templates/react/base/README.md

@@ -32,7 +32,7 @@ Open <http://localhost:5173>. Edit the files under `src/` and save to see the sc
 | `npm run fmt`       | Check formatting                  |
 | `npm run typecheck` | Run TypeScript checks             |
 
-Run `npm run build` to generate a deployable static site in `dist/`.
+Run `npm run build` to generate a deployable static site in `dist/`. Its paths are relative, so it runs from any folder, such as a GitHub Pages project site or an itch.io upload.
 
 ## Agent skills
 

package/templates/react/base/package.json

@@ -16,20 +16,20 @@
     },
     "dependencies": {
         "@playcanvas/react": "^0.11.7",
-        "playcanvas": "^2.23.1",
-        "react": "^19.3.0",
-        "react-dom": "^19.3.0"
+        "playcanvas": "^2.23.3",
+        "react": "^19.3.1",
+        "react-dom": "^19.3.1"
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
-        "@playcanvas/inspector": "^0.2.0",
+        "@playcanvas/inspector": "^0.3.0",
         "@types/react": "^19.3.0",
         "@types/react-dom": "^19.3.0",
         "@vitejs/plugin-react": "^6.1.2",
         "eslint": "^9.39.5",
-        "prettier": "^3.9.9",
+        "prettier": "^3.9.10",
         "typescript": "~6.0.3",
-        "vite": "^8.3.4"
+        "vite": "^8.3.5"
     },
     "engines": {
         "node": ">=22.23.2"

package/templates/react/base/vite.config.ts

@@ -3,6 +3,9 @@ import { defineConfig } from 'vite';
 
 // https://vite.dev/config/
 export default defineConfig({
+    // Relative URLs, so the build runs wherever it's served from: a domain root, a subpath such as
+    // GitHub Pages or itch.io, or a Snapchat Web Lens
+    base: './',
     plugins: [
         react(),
         {

package/templates/react/interactive-sphere/src/App.tsx

@@ -1,19 +1,18 @@
 import { Application } from '@playcanvas/react';
 import { useState } from 'react';
 
-import './App.css';
+import './counter.css';
 import Scene from './Scene';
+import './starter.css';
 
 function App() {
     const [count, setCount] = useState(0);
 
     return (
         <>
-            <div className="full-bleed">
-                <Application className="playcanvas-app">
-                    <Scene onClick={() => setCount((count) => count + 1)} />
-                </Application>
-            </div>
+            <Application className="playcanvas-app">
+                <Scene onClick={() => setCount((count) => count + 1)} />
+            </Application>
             <p className="counter">Click count: {count}</p>
         </>
     );

package/templates/react/interactive-sphere/src/Scene.tsx

@@ -18,7 +18,7 @@ function Scene({ onClick }: SceneProps) {
     const material = useMaterial({ diffuse });
 
     // Load the environment map
-    const { asset: envMap } = useEnvAtlas('/environment-map.png');
+    const { asset: envMap } = useEnvAtlas('./environment-map.png');
 
     // Change the mouse cursor based on the hover state
     useEffect(() => {

package/templates/react/model-viewer/src/App.tsx

@@ -5,8 +5,10 @@ import { TONEMAP_ACES2 } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
 
-// Swap this for your own model - anything you drop in public/ is served from the site root
-const MODEL_URL = '/playcanvas-cube.glb';
+import './starter.css';
+
+// Swap this for your own model - files in public/ are served next to index.html, so use a ./ path
+const MODEL_URL = './playcanvas-cube.glb';
 
 function Model() {
     const { asset } = useModel(MODEL_URL);

package/templates/react/spinning-cube/src/App.tsx

@@ -4,6 +4,8 @@ import { useAppEvent } from '@playcanvas/react/hooks';
 import type { Entity as PcEntity } from 'playcanvas';
 import { useRef } from 'react';
 
+import './starter.css';
+
 function Scene() {
     const cube = useRef<PcEntity>(null);
 

package/templates/react/splat-viewer/src/App.tsx

@@ -3,6 +3,8 @@ import { Camera, GSplat, Script } from '@playcanvas/react/components';
 import { useSplat } from '@playcanvas/react/hooks';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 
+import './starter.css';
+
 // Hosted so the template stays small. Capture or edit your own splat at https://superspl.at, then
 // drop the .sog or .ply in public/ and point this at it instead
 const SPLAT_URL = 'https://developer.playcanvas.com/assets/toy-cat.sog';

package/templates/react/{splat-viewer → web-lens}/index.html

@@ -2,9 +2,8 @@
 <html lang="en">
     <head>
         <meta charset="UTF-8" />
-        <link rel="icon" type="image/png" href="/src/assets/playcanvas.png" />
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        <title>PlayCanvas + React</title>
+        <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+        <title>Dodge</title>
     </head>
     <body>
         <div id="root"></div>

package/templates/react/web-lens/src/App.tsx

@@ -0,0 +1,85 @@
+import { Application, Entity } from '@playcanvas/react';
+import { Camera, Light, Script } from '@playcanvas/react/components';
+import { useApp, useAppEvent } from '@playcanvas/react/hooks';
+import { useCallback, useEffect, useState } from 'react';
+
+import { CARDS, DodgeGame } from './dodge-game';
+import type { GameEvents, GameState } from './dodge-game';
+import { hasLeaderboard, loadAvatar, loadBest, recordScore, showLeaderboard } from './lens';
+import './lens.css';
+
+function Scene({ onState }: { onState: GameEvents['game:state'] }) {
+    const app = useApp();
+    useAppEvent<GameEvents>('game:state', onState);
+
+    useEffect(() => {
+        // render at up to twice the CSS resolution: sharp on a phone, without the cost of 3x
+        // eslint-disable-next-line react-hooks/immutability -- the device belongs to the engine, not React
+        app.graphicsDevice.maxPixelRatio = Math.min(window.devicePixelRatio, 2);
+    }, [app]);
+
+    return (
+        <>
+            {/* fix the field's width, so a taller phone shows more of the falling blocks */}
+            <Entity name="camera" position={[0, 0, 7]}>
+                <Camera clearColor="#0b1020" fov={45} horizontalFov />
+            </Entity>
+            <Entity name="light" rotation={[40, 30, 0]}>
+                <Light type="directional" intensity={1.5} />
+            </Entity>
+            <Entity name="game">
+                <Script script={DodgeGame} />
+            </Entity>
+        </>
+    );
+}
+
+function App() {
+    const [state, setState] = useState<GameState>('ready');
+    const [score, setScore] = useState(0);
+    const [best, setBest] = useState(0);
+    const [avatar, setAvatar] = useState<string>();
+
+    useEffect(() => {
+        loadBest().then(setBest);
+        loadAvatar().then(setAvatar);
+    }, []);
+
+    // the HUD follows the game's state, and the Lens records each finished run
+    const onState = useCallback((next: GameState, value: number) => {
+        setState(next);
+        setScore(value);
+        if (next === 'over') recordScore(value).then(setBest);
+    }, []);
+
+    const card = CARDS[state];
+
+    return (
+        <main className="lens">
+            {/* lens.css sizes the canvas, filling a phone screen and centering a 9:16 column anywhere wider */}
+            <Application>
+                <Scene onState={onState} />
+            </Application>
+            <div className="lens-hud">
+                <header className="lens-bar">
+                    {avatar && <img className="lens-avatar" src={avatar} alt="Your Bitmoji" />}
+                    <span className="lens-score">{score}</span>
+                    <span className="lens-best">Best {best}</span>
+                </header>
+                {card && (
+                    <section className="lens-card">
+                        <h1 className="lens-title">{card.title}</h1>
+                        {state === 'over' && hasLeaderboard() && (
+                            <button className="lens-leaderboard" onClick={showLeaderboard}>
+                                Leaderboard
+                            </button>
+                        )}
+                        <p className="lens-hint">{card.hint}</p>
+                    </section>
+                )}
+            </div>
+        </main>
+    );
+}
+
+export default App;