create-playcanvas 0.10.1 → 0.11.0

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

@@ -0,0 +1,271 @@
+// The game, and the file to replace to make this starter your own (see "Make it your own" in
+// README.md). Only the entry file uses it, to attach `DodgeGame` and drive the HUD from the
+// `game:state` app event and `CARDS`. lens.ts, lens.css, vite.config.ts and scripts/ don't depend
+// on the game, so keep them
+import type { CameraComponent } from 'playcanvas';
+import { Color, Entity, Script, StandardMaterial, math } from 'playcanvas';
+
+/** Where a run is: waiting for the first tap, in play, held while the Lens is hidden, or crashed. */
+export type GameState = 'ready' | 'playing' | 'paused' | 'over';
+
+/** The app event the game fires whenever its state or score changes, for the HUD to follow. */
+export type GameEvents = {
+    'game:state': (state: GameState, score: number) => void;
+};
+
+/** What the HUD card says in each state. `null` hides the card. */
+export const CARDS: Record<GameState, { title: string; hint: string } | null> = {
+    ready: { title: 'Dodge', hint: 'Drag to steer. Tap to play' },
+    playing: null,
+    paused: { title: 'Paused', hint: 'Tap to resume' },
+    over: { title: 'Game over', hint: 'Tap to play again' }
+};
+
+const PLAYER_RADIUS = 0.3;
+const BLOCK_HEIGHT = 0.45;
+const BLOCK_DEPTH = 0.6;
+const BLOCKS = 16;
+const STARS = 24;
+const STAR_DEPTH = -2;
+
+// how many field widths the player travels for a drag across the whole canvas
+const DRAG_SCALE = 1.4;
+
+// seconds after a crash before a tap starts a new run, so the drag that crashed doesn't restart
+const RESTART_DELAY = 0.8;
+
+const YELLOW = new Color(1, 0.99, 0);
+const BLOCK_COLORS = [new Color(1, 0.36, 0.42), new Color(0.2, 0.75, 1), new Color(0.62, 0.45, 1)];
+const STAR_COLOR = new Color(0.45, 0.55, 1);
+
+type Block = { entity: Entity; width: number; counted: boolean };
+
+const createMaterial = (color: Color, glow: number) => {
+    const material = new StandardMaterial();
+    material.diffuse = color;
+    material.emissive = new Color(color.r * glow, color.g * glow, color.b * glow);
+    material.update();
+    return material;
+};
+
+/**
+ * A one-thumb dodge game: drag to steer the ball around the falling blocks. It renders the field
+ * at z = 0 for a camera that looks down -Z from its z position, and talks to the page only
+ * through the `game:state` app event.
+ */
+class DodgeGame extends Script {
+    static scriptName = 'dodgeGame';
+
+    state: GameState = 'ready';
+    score = 0;
+
+    elapsed = 0;
+    spawnIn = 0;
+    overFor = 0;
+
+    // half the visible field at z = 0, refreshed every frame from the camera
+    halfWidth = 2.5;
+    halfHeight = 4.4;
+
+    playerX = 0;
+    pointerId = -1;
+    pointerX = 0;
+
+    camera: CameraComponent | null = null;
+    player!: Entity;
+    blocks: Block[] = [];
+    stars: Entity[] = [];
+
+    initialize() {
+        const blockMaterials = BLOCK_COLORS.map((color) => createMaterial(color, 0.3));
+        const playerMaterial = createMaterial(YELLOW, 0.5);
+        const starMaterial = createMaterial(STAR_COLOR, 1);
+
+        this.player = new Entity('player');
+        this.player.addComponent('render', { type: 'sphere', material: playerMaterial });
+        this.player.setLocalScale(PLAYER_RADIUS * 2, PLAYER_RADIUS * 2, PLAYER_RADIUS * 2);
+        this.entity.addChild(this.player);
+
+        // a fixed pool of blocks, recycled as they fall off the bottom
+        for (let i = 0; i < BLOCKS; i++) {
+            const entity = new Entity(`block-${i}`);
+            entity.addComponent('render', { type: 'box', material: blockMaterials[i % blockMaterials.length] });
+            entity.enabled = false;
+            this.entity.addChild(entity);
+            this.blocks.push({ entity, width: 1, counted: false });
+        }
+
+        // streaks behind the field that show the speed
+        for (let i = 0; i < STARS; i++) {
+            const star = new Entity(`star-${i}`);
+            star.addComponent('render', { type: 'box', material: starMaterial });
+            star.setLocalScale(0.03, math.random(0.2, 0.6), 0.03);
+            star.setLocalPosition(math.random(-4, 4), math.random(-7, 7), STAR_DEPTH);
+            this.entity.addChild(star);
+            this.stars.push(star);
+        }
+
+        const canvas = this.app.graphicsDevice.canvas;
+        canvas.addEventListener('pointerdown', this.onPointerDown);
+        canvas.addEventListener('pointermove', this.onPointerMove);
+        canvas.addEventListener('pointerup', this.onPointerUp);
+        canvas.addEventListener('pointercancel', this.onPointerUp);
+        canvas.addEventListener('contextmenu', this.onContextMenu);
+        document.addEventListener('visibilitychange', this.onVisibilityChange);
+
+        this.on('destroy', () => {
+            canvas.removeEventListener('pointerdown', this.onPointerDown);
+            canvas.removeEventListener('pointermove', this.onPointerMove);
+            canvas.removeEventListener('pointerup', this.onPointerUp);
+            canvas.removeEventListener('pointercancel', this.onPointerUp);
+            canvas.removeEventListener('contextmenu', this.onContextMenu);
+            document.removeEventListener('visibilitychange', this.onVisibilityChange);
+            for (const material of [...blockMaterials, playerMaterial, starMaterial]) material.destroy();
+        });
+
+        this.setState('ready');
+    }
+
+    onPointerDown = (event: PointerEvent) => {
+        this.pointerId = event.pointerId;
+        this.pointerX = event.clientX;
+        this.app.graphicsDevice.canvas.setPointerCapture(event.pointerId);
+
+        if (this.state === 'paused') {
+            this.setState('playing');
+        } else if (this.state === 'ready' || (this.state === 'over' && this.overFor > RESTART_DELAY)) {
+            this.restart();
+        }
+    };
+
+    onPointerMove = (event: PointerEvent) => {
+        if (event.pointerId !== this.pointerId) return;
+
+        // the drag is relative, so the thumb never has to cover the ball, and normalized by the
+        // canvas width, so a swipe moves the ball the same distance on every phone
+        if (this.state === 'playing') {
+            const width = this.app.graphicsDevice.canvas.clientWidth;
+            this.playerX += ((event.clientX - this.pointerX) / width) * this.halfWidth * 2 * DRAG_SCALE;
+        }
+        this.pointerX = event.clientX;
+    };
+
+    onPointerUp = (event: PointerEvent) => {
+        if (event.pointerId === this.pointerId) this.pointerId = -1;
+    };
+
+    // a long press would otherwise open the context menu over the game
+    onContextMenu = (event: Event) => event.preventDefault();
+
+    // Snapchat can hide the Lens without closing it, so hold the run until the player taps back in
+    onVisibilityChange = () => {
+        if (document.hidden && this.state === 'playing') this.setState('paused');
+    };
+
+    get playerY() {
+        return -this.halfHeight * 0.7;
+    }
+
+    restart() {
+        for (const block of this.blocks) block.entity.enabled = false;
+        this.score = 0;
+        this.elapsed = 0;
+        this.spawnIn = 0;
+        this.playerX = 0;
+        this.setState('playing');
+    }
+
+    crash() {
+        this.overFor = 0;
+        this.setState('over');
+
+        // only Android vibrates, and only once the player has interacted, which a crash always follows
+        if ('vibrate' in navigator && navigator.userActivation.hasBeenActive) navigator.vibrate(80);
+    }
+
+    setState(state: GameState) {
+        this.state = state;
+        this.app.fire('game:state', state, this.score);
+    }
+
+    // fit the field to the camera: it fixes the width, so a taller phone sees further up and down
+    fitField() {
+        this.camera ??= this.app.root.findComponent('camera') as CameraComponent | null;
+        const { width, height } = this.app.graphicsDevice;
+        if (!this.camera || !width || !height) return;
+
+        const half = this.camera.entity.getPosition().z * Math.tan(this.camera.fov * 0.5 * math.DEG_TO_RAD);
+        const aspect = width / height;
+        this.halfWidth = this.camera.horizontalFov ? half : half * aspect;
+        this.halfHeight = this.camera.horizontalFov ? half / aspect : half;
+    }
+
+    spawn() {
+        const block = this.blocks.find((b) => !b.entity.enabled);
+        if (!block) return;
+
+        block.width = math.random(0.8, Math.min(1.8, this.halfWidth));
+        block.counted = false;
+        const room = this.halfWidth - block.width / 2;
+        block.entity.setLocalScale(block.width, BLOCK_HEIGHT, BLOCK_DEPTH);
+        block.entity.setLocalPosition(math.random(-room, room), this.halfHeight + BLOCK_HEIGHT, 0);
+        block.entity.enabled = true;
+    }
+
+    update(dt: number) {
+        this.fitField();
+
+        // blocks fall faster the longer a run lasts
+        const speed = Math.min(4 + this.elapsed * 0.12, 9);
+
+        // the stars sit behind the field, where the camera sees more, so they wrap beyond its edges
+        const top = this.halfHeight * 1.5;
+        const drift = (this.state === 'playing' ? speed * 0.5 : 0.8) * dt;
+        for (const star of this.stars) {
+            const { x, y } = star.getLocalPosition();
+            star.setLocalPosition(x, y - drift < -top ? y - drift + top * 2 : y - drift, STAR_DEPTH);
+        }
+
+        const limit = this.halfWidth - PLAYER_RADIUS;
+        this.playerX = math.clamp(this.playerX, -limit, limit);
+        const playerY = this.playerY;
+        this.player.setLocalPosition(this.playerX, playerY, 0);
+
+        if (this.state === 'over') this.overFor += dt;
+        if (this.state !== 'playing') return;
+
+        // and come more often
+        this.elapsed += dt;
+        this.spawnIn -= dt;
+        if (this.spawnIn <= 0) {
+            this.spawn();
+            this.spawnIn = Math.max(0.9 - this.elapsed * 0.012, 0.38);
+        }
+
+        for (const block of this.blocks) {
+            if (!block.entity.enabled) continue;
+
+            const { x, y: from } = block.entity.getLocalPosition();
+            const y = from - speed * dt;
+            block.entity.setLocalPosition(x, y, 0);
+
+            // circle against box: the distance from the ball's center to the nearest point of the block
+            const dx = Math.max(Math.abs(this.playerX - x) - block.width / 2, 0);
+            const dy = Math.max(Math.abs(playerY - y) - BLOCK_HEIGHT / 2, 0);
+            if (dx * dx + dy * dy < PLAYER_RADIUS * PLAYER_RADIUS) {
+                this.crash();
+                return;
+            }
+
+            if (!block.counted && y < playerY - BLOCK_HEIGHT) {
+                block.counted = true;
+                this.score++;
+                this.setState('playing');
+            }
+
+            if (y < -this.halfHeight - BLOCK_HEIGHT) block.entity.enabled = false;
+        }
+    }
+}
+
+export { DodgeGame };

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

@@ -0,0 +1,155 @@
+:root {
+    color-scheme: dark;
+
+    /* Snapchat draws its own controls over the top of a Lens, so its top inset is much larger than a
+       notch. viewport-fit=cover in index.html makes these report real values */
+    --inset-top: env(safe-area-inset-top, 0px);
+    --inset-right: env(safe-area-inset-right, 0px);
+    --inset-bottom: env(safe-area-inset-bottom, 0px);
+    --inset-left: env(safe-area-inset-left, 0px);
+}
+
+/* development only (see lens.ts): reserve the room Snapchat's controls take */
+:root.simulate-insets {
+    --inset-top: max(env(safe-area-inset-top, 0px), 120px);
+}
+
+[hidden] {
+    display: none !important;
+}
+
+html,
+body {
+    height: 100%;
+    margin: 0;
+    overflow: hidden;
+    overscroll-behavior: none;
+    touch-action: none;
+    -webkit-tap-highlight-color: transparent;
+    -webkit-touch-callout: none;
+    user-select: none;
+
+    /* the scene's clear color, so nothing flashes while the game loads */
+    background: #0b1020;
+    color: #fff;
+    font-family: ui-rounded, 'SF Pro Rounded', system-ui, sans-serif;
+}
+
+/* the whole screen on a phone, and a centered 9:16 column on anything wider, such as a desktop browser */
+.lens {
+    position: relative;
+    width: min(100vw, 100dvh * 9 / 16);
+    height: 100dvh;
+    margin: 0 auto;
+    overflow: hidden;
+}
+
+.lens canvas,
+.lens pc-app {
+    display: block;
+    width: 100%;
+    height: 100%;
+}
+
+.simulate-insets .lens::before {
+    content: 'Snapchat controls';
+    position: absolute;
+    inset: 0 0 auto;
+    z-index: 2;
+    display: flex;
+    align-items: flex-end;
+    justify-content: center;
+    height: var(--inset-top);
+    padding-bottom: 6px;
+    box-sizing: border-box;
+    border-bottom: 1px dashed #ffffff40;
+    background: repeating-linear-gradient(-45deg, #ffffff0d 0 8px, transparent 8px 16px);
+    color: #ffffff59;
+    font-size: 11px;
+    pointer-events: none;
+}
+
+/* taps pass through the HUD to the canvas, apart from its buttons */
+.lens-hud {
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+    pointer-events: none;
+}
+
+/* insets go on each positioned element itself: padding on a parent wouldn't move it */
+.lens-bar {
+    position: absolute;
+    top: calc(var(--inset-top) + 12px);
+    right: calc(var(--inset-right) + 16px);
+    left: calc(var(--inset-left) + 16px);
+    display: grid;
+    grid-template-columns: 1fr auto 1fr;
+    align-items: center;
+}
+
+.lens-avatar {
+    grid-column: 1;
+    width: 44px;
+    height: 44px;
+    border-radius: 50%;
+    background: #ffffff1f;
+    object-fit: cover;
+}
+
+.lens-score {
+    grid-column: 2;
+    font-size: 48px;
+    font-variant-numeric: tabular-nums;
+    font-weight: 800;
+    text-shadow: 0 2px 12px #0008;
+}
+
+.lens-best {
+    grid-column: 3;
+    justify-self: end;
+    color: #ffffffb3;
+    font-size: 14px;
+    font-weight: 700;
+    letter-spacing: 0.06em;
+    text-transform: uppercase;
+}
+
+.lens-card {
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    width: min(300px, calc(100% - 48px));
+    box-sizing: border-box;
+    padding: 24px;
+    border-radius: 24px;
+    background: #0b1020cc;
+    backdrop-filter: blur(10px);
+    text-align: center;
+    translate: -50% -50%;
+}
+
+.lens-title {
+    margin: 0;
+    font-size: 32px;
+    font-weight: 800;
+}
+
+.lens-leaderboard {
+    margin-top: 18px;
+    padding: 12px 22px;
+    border: 0;
+    border-radius: 999px;
+    background: #fffc00;
+    color: #000;
+    font: inherit;
+    font-size: 16px;
+    font-weight: 800;
+    pointer-events: auto;
+}
+
+.lens-hint {
+    margin: 14px 0 0;
+    color: #ffffffb3;
+    font-size: 16px;
+}

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/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/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);