create-playcanvas 0.5.1 → 0.6.1

package/templates/_features/physics/react/package.json

@@ -0,0 +1,5 @@
+{
+    "dependencies": {
+        "sync-ammo": "^0.1.2"
+    }
+}

package/templates/_features/physics/react/src/sync-ammo.d.ts

@@ -0,0 +1,4 @@
+declare module 'sync-ammo' {
+    const Ammo: unknown;
+    export default Ammo;
+}

package/templates/_shared/ar-placement/README.md

@@ -0,0 +1,7 @@
+## AR Placement
+
+An AR scene that detects tracked planes and points, then shows a placement reticle.
+
+### Controls
+
+Use **Start AR** on a compatible mobile device in a secure context. Select a tracked surface to place a box.

package/templates/_shared/ar-placement/src/ar-placement.ts

@@ -0,0 +1,123 @@
+import type { Entity, Quat, Vec3, XrHitTestSource } from 'playcanvas';
+import {
+    Color,
+    Entity as PcEntity,
+    Script,
+    StandardMaterial,
+    XRSPACE_LOCALFLOOR,
+    XRTRACKABLE_PLANE,
+    XRTRACKABLE_POINT,
+    XRTYPE_AR
+} from 'playcanvas';
+
+class ArPlacement extends Script {
+    static scriptName = 'arPlacement';
+
+    camera!: Entity;
+    preview?: Entity;
+    reticle!: Entity;
+    material!: StandardMaterial;
+    position?: Vec3;
+    rotation?: Quat;
+    source?: XrHitTestSource;
+
+    initialize() {
+        const reticleMaterial = new StandardMaterial();
+        reticleMaterial.diffuse = new Color(1, 0.35, 0.15);
+        reticleMaterial.update();
+        this.material = new StandardMaterial();
+        this.material.diffuse = new Color(0.1, 0.7, 0.9);
+        this.material.update();
+
+        this.reticle = new PcEntity('reticle');
+        this.reticle.addComponent('render', { type: 'cylinder', material: reticleMaterial });
+        this.reticle.setLocalScale(0.15, 0.01, 0.15);
+        this.reticle.enabled = false;
+        this.app.root.addChild(this.reticle);
+
+        // xr UI and lifecycle events
+        const button = document.getElementById('xr-button') as HTMLButtonElement;
+        button.onclick = () => this.start();
+        this.app.xr?.hitTest.on('available', this.startHitTest, this);
+        this.app.xr?.input.on('select', this.place, this);
+        this.app.xr?.on('start', this.onStart, this);
+        this.app.xr?.on('end', this.onEnd, this);
+        this.app.xr?.on(`available:${XRTYPE_AR}`, this.updateStatus, this);
+        this.updateStatus(this.app.xr?.isAvailable(XRTYPE_AR) ?? false);
+
+        this.on('destroy', () => {
+            button.onclick = null;
+            this.reticle.destroy();
+            this.material.destroy();
+            reticleMaterial.destroy();
+            this.app.xr?.hitTest.off('available', this.startHitTest, this);
+            this.app.xr?.input.off('select', this.place, this);
+            this.app.xr?.off('start', this.onStart, this);
+            this.app.xr?.off('end', this.onEnd, this);
+            this.app.xr?.off(`available:${XRTYPE_AR}`, this.updateStatus, this);
+        });
+    }
+
+    start() {
+        if (!this.app.xr?.isAvailable(XRTYPE_AR)) return;
+        this.camera.camera?.startXr(XRTYPE_AR, XRSPACE_LOCALFLOOR, {
+            callback: (error) => {
+                if (error) this.setStatus(error.message);
+            }
+        });
+    }
+
+    startHitTest() {
+        this.app.xr?.hitTest.start({
+            entityTypes: [XRTRACKABLE_POINT, XRTRACKABLE_PLANE],
+            callback: (error, source) => {
+                if (error || !source) {
+                    this.setStatus('Unable to start hit testing');
+                    return;
+                }
+                this.source = source;
+                source.on('result', (position, rotation) => this.updateReticle(position, rotation));
+            }
+        });
+    }
+
+    // retain the latest hit so a select event can place the object
+    updateReticle(position: Vec3, rotation: Quat) {
+        this.position = position.clone();
+        this.rotation = rotation.clone();
+        this.reticle.enabled = true;
+        this.reticle.setPosition(position);
+        this.reticle.setRotation(rotation);
+        this.setStatus('Select to place a box');
+    }
+
+    place() {
+        if (!this.position || !this.rotation) return;
+        const box = new PcEntity('placed-box');
+        box.addComponent('render', { type: 'box', material: this.material });
+        box.setLocalScale(0.2, 0.2, 0.2);
+        box.setPosition(this.position.x, this.position.y + 0.1, this.position.z);
+        box.setRotation(this.rotation);
+        this.app.root.addChild(box);
+    }
+
+    onStart() {
+        if (this.preview) this.preview.enabled = false;
+    }
+
+    onEnd() {
+        if (this.preview) this.preview.enabled = true;
+    }
+
+    updateStatus(available: boolean) {
+        const button = document.getElementById('xr-button') as HTMLButtonElement;
+        button.disabled = !available;
+        this.setStatus(available ? 'AR is available' : 'AR requires a compatible mobile device and secure context');
+    }
+
+    setStatus(message: string) {
+        document.getElementById('xr-status')!.textContent = message;
+    }
+}
+
+export { ArPlacement };

package/templates/_shared/first-person-controller/README.md

@@ -0,0 +1,7 @@
+## First-Person Controller
+
+A physics-backed player controller, camera and simple obstacle course.
+
+### Controls
+
+Click the scene, use WASD to move, move the mouse to look and press Space to jump.

package/templates/_shared/first-person-controller/src/controller.ts

@@ -0,0 +1,18 @@
+import type { Entity, RigidBodyComponentSystem } from 'playcanvas';
+import { FirstPersonController } from 'playcanvas/scripts/esm/first-person-controller.mjs';
+
+export const addFirstPersonController = (player: Entity, camera: Entity) => {
+    (player.rigidbody!.system as RigidBodyComponentSystem).gravity.set(0, -18, 0);
+    if (!player.script) player.addComponent('script');
+    player.script!.create(FirstPersonController, {
+        properties: {
+            camera,
+            jumpForce: 650,
+            speedGround: 55
+        }
+    });
+
+    return () => {
+        player.script?.destroy('firstPersonController');
+    };
+};

package/templates/_shared/first-person-controller/src/scripts.d.ts

@@ -0,0 +1,5 @@
+declare module 'playcanvas/scripts/esm/first-person-controller.mjs' {
+    import { Script } from 'playcanvas';
+
+    export class FirstPersonController extends Script {}
+}

package/templates/_shared/interactive-sphere/README.md

@@ -0,0 +1,7 @@
+## Interactive Sphere
+
+A lit sphere, an environment map, grid and orbit camera controls.
+
+### Controls
+
+Drag to orbit the camera. Click the sphere to increment the counter.

package/templates/_shared/model-viewer/README.md

@@ -0,0 +1,7 @@
+## Model Viewer
+
+A glTF model with a procedural sky, image-based lighting and orbit camera controls.
+
+### Controls
+
+Drag to orbit the camera. Replace the model asset to view your own model.

package/templates/_shared/physics-playground/README.md

@@ -0,0 +1,7 @@
+## Physics Playground
+
+A rigid-body scene with a static floor, orbit camera and dynamic primitive shapes.
+
+### Controls
+
+Use **Spawn object** to add a body and **Reset** to recreate the starting set. Drag to orbit the camera.

package/templates/_shared/product-configurator/ASSET_LICENSES.md

@@ -0,0 +1,3 @@
+# Asset licences
+
+"Lamborghini V12 Vision GT [REALISTIC FREE]" by [ALEX MILOS](https://sketchfab.com/TEDIORE), sourced from [Sketchfab](https://sketchfab.com/3d-models/lamborghini-v12-vision-gt-realistic-free-18b9f7e2826d437f8593c40b784cd915), is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).

package/templates/_shared/product-configurator/README.md

@@ -0,0 +1,7 @@
+## Product Configurator
+
+A glTF product model, procedural studio lighting and selectable paint finishes.
+
+### Controls
+
+Choose a paint finish, then drag to orbit the camera.

package/templates/_shared/product-configurator/src/product.css

@@ -0,0 +1,14 @@
+.variants button {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+}
+
+.finish {
+    width: 14px;
+    height: 14px;
+    border: 1px solid #ffffff66;
+    border-radius: 50%;
+    background: var(--color);
+    box-shadow: 0 1px 4px #0008;
+}

package/templates/_shared/scene-editor/README.md

@@ -0,0 +1,7 @@
+## Scene Editor
+
+A small editable scene with selectable entities and translate, rotate and scale gizmos.
+
+### Controls
+
+Select the cube or sphere, then choose Move, Rotate or Scale to change the active gizmo.

package/templates/_shared/scene-editor/src/scene-editor.ts

@@ -0,0 +1,57 @@
+import type { Entity, Layer } from 'playcanvas';
+import { Gizmo, RotateGizmo, ScaleGizmo, Script, TranslateGizmo } from 'playcanvas';
+
+type Mode = 'translate' | 'rotate' | 'scale';
+
+class SceneEditor extends Script {
+    static scriptName = 'sceneEditor';
+
+    camera!: Entity;
+    targets: Entity[] = [];
+    layer!: Layer;
+    selected = 0;
+    gizmo?: TranslateGizmo | RotateGizmo | ScaleGizmo;
+
+    initialize() {
+        this.layer = Gizmo.createLayer(this.app);
+        this.setMode('translate');
+
+        // wire the scene and gizmo controls
+        document.querySelectorAll<HTMLButtonElement>('[data-mode]').forEach((button) => {
+            button.onclick = () => this.setMode(button.dataset.mode as Mode);
+        });
+        document.querySelectorAll<HTMLButtonElement>('[data-target]').forEach((button) => {
+            button.onclick = () => {
+                this.selected = Number(button.dataset.target);
+                this.gizmo?.attach([this.targets[this.selected]]);
+                this.updateButtons();
+            };
+        });
+        this.on('destroy', () => this.gizmo?.destroy());
+        this.updateButtons();
+    }
+
+    // replace the active gizmo for the selected entity
+    setMode(mode: Mode) {
+        this.gizmo?.destroy();
+        const camera = this.camera.camera!;
+        this.gizmo =
+            mode === 'rotate'
+                ? new RotateGizmo(camera, this.layer)
+                : mode === 'scale'
+                  ? new ScaleGizmo(camera, this.layer)
+                  : new TranslateGizmo(camera, this.layer);
+        this.gizmo.attach([this.targets[this.selected]]);
+        document.querySelectorAll<HTMLButtonElement>('[data-mode]').forEach((button) => {
+            button.ariaPressed = String(button.dataset.mode === mode);
+        });
+    }
+
+    updateButtons() {
+        document.querySelectorAll<HTMLButtonElement>('[data-target]').forEach((button) => {
+            button.ariaPressed = String(Number(button.dataset.target) === this.selected);
+        });
+    }
+}
+
+export { SceneEditor };

package/templates/_shared/spinning-cube/README.md

@@ -0,0 +1,7 @@
+## Spinning Cube
+
+A rotating cube, a camera and a directional light. It is the smallest PlayCanvas scene in the catalog.
+
+### Controls
+
+The scene runs automatically; no input is required.

package/templates/_shared/splat-viewer/README.md

@@ -0,0 +1,7 @@
+## Splat Viewer
+
+A Gaussian splat with an orbit camera and a hosted sample asset.
+
+### Controls
+
+Drag to orbit the camera. Replace the splat URL with your own capture.

package/templates/_shared/sprite-game/README.md

@@ -0,0 +1,7 @@
+## Sprite Game
+
+A small procedural sprite animation, platforms and a simple side-scrolling controller.
+
+### Controls
+
+Use A/D or the arrow keys to move, and press Space to jump.

package/templates/_shared/sprite-game/src/sprite-game.ts

@@ -0,0 +1,197 @@
+import type { SpriteComponent } from 'playcanvas';
+import {
+    ADDRESS_CLAMP_TO_EDGE,
+    Asset,
+    Color,
+    Entity,
+    FILTER_NEAREST,
+    PIXELFORMAT_RGBA8,
+    Script,
+    SPRITE_RENDERMODE_SIMPLE,
+    SPRITETYPE_ANIMATED,
+    Sprite,
+    StandardMaterial,
+    Texture,
+    TextureAtlas,
+    Vec2,
+    Vec4
+} from 'playcanvas';
+
+const CELL = 24;
+const FRAMES = 4;
+const SCALE = 2.5;
+const FEET = (2 / CELL) * SCALE;
+const SPEED = 3;
+const PLATFORMS = [
+    { x: -3.2, y: 1, width: 2.6 },
+    { x: 0, y: 1.9, width: 2.4 },
+    { x: 3.6, y: 1.1, width: 2.8 }
+];
+
+class SpriteGame extends Script {
+    static scriptName = 'spriteGame';
+
+    keys = new Set<string>();
+    player!: Entity;
+    velocity = 0;
+    grounded = true;
+
+    initialize() {
+        // build a small procedural runner sheet
+        const canvas = document.createElement('canvas');
+        canvas.width = CELL * FRAMES;
+        canvas.height = CELL;
+        const ctx = canvas.getContext('2d')!;
+
+        for (let i = 0; i < FRAMES; i++) {
+            const x = i * CELL;
+            ctx.fillStyle = '#ff5f45';
+            ctx.fillRect(x + 7, 4 + (i % 2), 10, 11);
+            ctx.fillStyle = '#ffd166';
+            ctx.fillRect(x + 9, 1 + (i % 2), 6, 5);
+            ctx.fillStyle = '#222';
+            ctx.fillRect(x + 8 + (i % 2) * 5, 15, 3, 7);
+            ctx.fillRect(x + 13 - (i % 2) * 5, 15, 3, 7);
+        }
+
+        // turn the canvas into an in-memory animated sprite asset
+        const texture = new Texture(this.app.graphicsDevice, {
+            width: canvas.width,
+            height: canvas.height,
+            format: PIXELFORMAT_RGBA8,
+            mipmaps: false
+        });
+        texture.addressU = ADDRESS_CLAMP_TO_EDGE;
+        texture.addressV = ADDRESS_CLAMP_TO_EDGE;
+        texture.minFilter = FILTER_NEAREST;
+        texture.magFilter = FILTER_NEAREST;
+        texture.setSource(canvas);
+
+        const atlas = new TextureAtlas();
+        atlas.texture = texture;
+        atlas.frames = Object.fromEntries(
+            Array.from({ length: FRAMES }, (_, i) => [
+                String(i),
+                {
+                    rect: new Vec4(i * CELL, 0, CELL, CELL),
+                    pivot: new Vec2(0.5, 0),
+                    border: new Vec4()
+                }
+            ])
+        );
+
+        const sprite = new Sprite(this.app.graphicsDevice, {
+            atlas,
+            frameKeys: Array.from({ length: FRAMES }, (_, i) => String(i)),
+            pixelsPerUnit: CELL,
+            renderMode: SPRITE_RENDERMODE_SIMPLE
+        });
+        const asset = new Asset('runner', 'sprite', { url: '' });
+        asset.resource = sprite;
+        asset.loaded = true;
+        this.app.assets.add(asset);
+
+        this.player = new Entity('runner');
+        this.player.addComponent('sprite', { type: SPRITETYPE_ANIMATED });
+        this.player.sprite!.addClip({ name: 'run', fps: 10, loop: true, spriteAsset: asset.id });
+        this.player.sprite!.autoPlayClip = 'run';
+        this.player.setLocalScale(SCALE, SCALE, SCALE);
+        this.player.setLocalPosition(-5.2, 0, 0);
+        this.entity.addChild(this.player);
+
+        // build the scene decoration from primitives
+        const sky = new StandardMaterial();
+        sky.emissive = new Color(0.86, 0.95, 1);
+        sky.update();
+        const dirt = new StandardMaterial();
+        dirt.emissive = new Color(0.45, 0.28, 0.16);
+        dirt.update();
+        const grass = new StandardMaterial();
+        grass.emissive = new Color(0.28, 0.62, 0.34);
+        grass.update();
+        const decoration = (
+            name: string,
+            type: 'box' | 'sphere',
+            position: [number, number, number],
+            scale: [number, number, number],
+            material: StandardMaterial
+        ) => {
+            const entity = new Entity(name);
+            entity.addComponent('render', { type, material });
+            entity.setLocalPosition(...position);
+            entity.setLocalScale(...scale);
+            this.entity.addChild(entity);
+        };
+        decoration('cloud-left', 'sphere', [-3.8, 4, -1], [1.2, 0.5, 0.2], sky);
+        decoration('cloud-center', 'sphere', [-2.9, 4.1, -1], [1.4, 0.65, 0.2], sky);
+        decoration('cloud-right', 'sphere', [3.6, 3.6, -1], [1.7, 0.6, 0.2], sky);
+        for (const [i, { x, y, width }] of PLATFORMS.entries()) {
+            decoration(`platform-${i}`, 'box', [x, y - 0.24, -0.5], [width, 0.32, 0.4], dirt);
+            decoration(`platform-grass-${i}`, 'box', [x, y - 0.04, -0.49], [width, 0.08, 0.4], grass);
+        }
+
+        // retain input and release scene-owned resources on teardown
+        window.addEventListener('keydown', this.onKeyDown);
+        window.addEventListener('keyup', this.onKeyUp);
+        this.on('destroy', () => {
+            window.removeEventListener('keydown', this.onKeyDown);
+            window.removeEventListener('keyup', this.onKeyUp);
+            texture.destroy();
+            sky.destroy();
+            dirt.destroy();
+            grass.destroy();
+        });
+    }
+
+    onKeyDown = (event: KeyboardEvent) => {
+        this.keys.add(event.code);
+        if (event.code === 'Space' && this.grounded) {
+            this.velocity = 5;
+            this.grounded = false;
+        }
+    };
+
+    onKeyUp = (event: KeyboardEvent) => this.keys.delete(event.code);
+
+    update(dt: number) {
+        // apply movement, gravity and simple top-down platform collisions
+        const direction =
+            Number(this.keys.has('ArrowRight') || this.keys.has('KeyD')) -
+            Number(this.keys.has('ArrowLeft') || this.keys.has('KeyA'));
+        const position = this.player.getLocalPosition();
+
+        this.velocity -= 12 * dt;
+        const x = mathClamp(position.x + direction * SPEED * dt, -5.2, 5.5);
+        let y = position.y + this.velocity * dt;
+        let floor = 0;
+        if (this.velocity <= 0) {
+            for (const platform of PLATFORMS) {
+                const top = platform.y - FEET;
+                if (
+                    position.y >= top &&
+                    y <= top &&
+                    x >= platform.x - platform.width / 2 &&
+                    x <= platform.x + platform.width / 2
+                ) {
+                    floor = Math.max(floor, top);
+                }
+            }
+        }
+        if (y <= floor) {
+            y = floor;
+            this.velocity = 0;
+            this.grounded = true;
+        } else {
+            this.grounded = false;
+        }
+
+        this.player.setLocalPosition(x, y, position.z);
+        this.player.setLocalScale(direction < 0 ? -SCALE : SCALE, SCALE, SCALE);
+        const component = this.player.sprite as SpriteComponent;
+        component.speed = direction ? 1 : 0;
+    }
+}
+
+const mathClamp = (value: number, min: number, max: number) => Math.min(Math.max(value, min), max);
+
+export { SpriteGame };

package/templates/_shared/third-person-controller/README.md

@@ -0,0 +1,7 @@
+## Third-Person Controller
+
+A physics-backed third-person controller, follow camera and animated robot.
+
+### Controls
+
+Click the scene, use WASD to move, move the mouse to orbit and press Space to jump.

package/templates/_shared/third-person-controller/src/controller.ts

@@ -0,0 +1,53 @@
+import type { Entity, RigidBodyComponentSystem } from 'playcanvas';
+import { Script } from 'playcanvas';
+import { ThirdPersonController } from 'playcanvas/scripts/esm/third-person-controller.mjs';
+
+class RobotAnimation extends Script {
+    static scriptName = 'robotAnimation';
+
+    time = 0;
+    y = 0;
+
+    initialize() {
+        this.y = this.entity.getLocalPosition().y;
+    }
+
+    update(dt: number) {
+        const body = this.entity.parent as Entity | null;
+        const velocity = body?.rigidbody?.linearVelocity;
+        const speed = velocity ? Math.hypot(velocity.x, velocity.z) : 0;
+        this.time += dt * Math.min(speed * 2, 14);
+
+        const swing = Math.sin(this.time) * Math.min(speed * 5, 45);
+        this.entity.findByName('left-arm')?.setLocalEulerAngles(swing, 0, 0);
+        this.entity.findByName('right-arm')?.setLocalEulerAngles(-swing, 0, 0);
+        this.entity.findByName('left-leg')?.setLocalEulerAngles(-swing, 0, 0);
+        this.entity.findByName('right-leg')?.setLocalEulerAngles(swing, 0, 0);
+        this.entity.setLocalPosition(0, this.y + Math.abs(Math.sin(this.time)) * Math.min(speed * 0.01, 0.04), 0);
+    }
+}
+
+export const addThirdPersonController = (player: Entity, camera: Entity, model: Entity) => {
+    (player.rigidbody!.system as RigidBodyComponentSystem).gravity.set(0, -18, 0);
+    if (!player.script) player.addComponent('script');
+    player.script!.create(ThirdPersonController, {
+        properties: {
+            camera,
+            characterModel: model,
+            cameraDistance: 5,
+            cameraHeight: 0.5,
+            initialPitch: 15,
+            invertLookY: true,
+            jumpForce: 520,
+            speedGround: 60
+        }
+    });
+
+    if (!model.script) model.addComponent('script');
+    model.script!.create(RobotAnimation);
+
+    return () => {
+        player.script?.destroy('thirdPersonController');
+        model.script?.destroy('robotAnimation');
+    };
+};

package/templates/_shared/third-person-controller/src/scripts.d.ts

@@ -0,0 +1,5 @@
+declare module 'playcanvas/scripts/esm/third-person-controller.mjs' {
+    import { Script } from 'playcanvas';
+
+    export class ThirdPersonController extends Script {}
+}

package/templates/_shared/vr-starter/README.md

@@ -0,0 +1,7 @@
+## VR Starter
+
+An immersive VR room with controller models and standard snap-turn and teleport locomotion.
+
+### Controls
+
+Use **Enter VR** on a compatible headset in a secure context. Movement and teleport controls are provided by the controller scripts.

package/templates/_shared/vr-starter/src/vr.ts

@@ -0,0 +1,40 @@
+import type { AppBase, Entity } from 'playcanvas';
+import { XRSPACE_LOCALFLOOR, XRTYPE_VR } from 'playcanvas';
+import { XrControllers } from 'playcanvas/scripts/esm/xr/xr-controllers.mjs';
+import { XrNavigation } from 'playcanvas/scripts/esm/xr/xr-navigation.mjs';
+
+export const setupVr = (app: AppBase, rig: Entity, camera: Entity) => {
+    // attach the controller and locomotion scripts to the player rig
+    if (!rig.script) rig.addComponent('script');
+    rig.script!.create(XrControllers);
+    rig.script!.create(XrNavigation, {
+        properties: { enableMove: true, enableTeleport: true, turnMode: 'snap' }
+    });
+
+    const button = document.getElementById('xr-button') as HTMLButtonElement;
+    const status = document.getElementById('xr-status')!;
+    const { xr } = app;
+
+    // availability can change after the page loads
+    const update = () => {
+        const available = xr?.isAvailable(XRTYPE_VR) ?? false;
+        button.disabled = !available;
+        status.textContent = available ? 'VR is available' : 'VR requires a compatible headset and secure context';
+    };
+    button.onclick = () => {
+        camera.camera?.startXr(XRTYPE_VR, XRSPACE_LOCALFLOOR, {
+            callback: (error) => {
+                if (error) status.textContent = error.message;
+            }
+        });
+    };
+    xr?.on(`available:${XRTYPE_VR}`, update);
+    update();
+
+    return () => {
+        button.onclick = null;
+        xr?.off(`available:${XRTYPE_VR}`, update);
+        rig.script?.destroy('xrControllers');
+        rig.script?.destroy('xrNavigation');
+    };
+};

package/templates/_shared/vr-starter/src/xr.d.ts

@@ -0,0 +1,11 @@
+declare module 'playcanvas/scripts/esm/xr/xr-controllers.mjs' {
+    import { Script } from 'playcanvas';
+
+    export class XrControllers extends Script {}
+}
+
+declare module 'playcanvas/scripts/esm/xr/xr-navigation.mjs' {
+    import { Script } from 'playcanvas';
+
+    export class XrNavigation extends Script {}
+}