create-playcanvas 0.9.0 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-playcanvas",
-    "version": "0.9.0",
+    "version": "0.10.1",
     "description": "Scaffold a PlayCanvas project",
     "keywords": [
         "playcanvas",
@@ -44,7 +44,7 @@
     "devDependencies": {
         "@clack/prompts": "^1.8.1",
         "@playcanvas/eslint-config": "3.0.0-beta.8",
-        "@types/node": "22.20.4",
+        "@types/node": "22.20.5",
         "eslint": "^9.39.5",
         "mri": "^1.2.0",
         "picocolors": "^1.1.1",

package/skills/apply-conventions/SKILL.md

@@ -44,6 +44,6 @@ Check version-sensitive APIs against installed `playcanvas` declarations.
 
 ## Verify in the running app
 
-Offline values cannot prove facing, poses, or placement. Log values from a `Script` or update
-callback in the running app, and judge visuals only from screenshots you have inspected. A saved
-file path is not evidence.
+Offline values cannot prove facing, poses, or placement. Read values from the running app with
+`inspect-runtime`, and judge visuals only from screenshots you have inspected. A saved file path is
+not evidence.

package/skills/assemble-scene/SKILL.md

@@ -20,7 +20,7 @@ once; if the tuning record is missing, calibrate first.
 ## Check placement
 
 After a rendered frame, measure each support or attachment at the object's actual position, using
-a mount point, raycast, or geometry sample. A positive gap floats; a negative gap penetrates.
+a mount point, raycast, or geometry sample read through `inspect-runtime`. A positive gap floats; a negative gap penetrates.
 Overlapping world AABBs between unrelated roots are a failure unless two different views prove the
 overlap is empty space.
 

package/skills/build-app/SKILL.md

@@ -19,6 +19,8 @@ reference: [direct Engine](references/direct-engine.md), [React](references/reac
   `canvas.width / canvas.clientWidth`.
 - Rigid bodies stay inert until Ammo loads through `WasmModule`. Copy the loader from the
   `physics/falling-shapes` example with `find-examples`.
+- `devtools` defaults to `true`, so debugging tools can find the app (`inspect-runtime`). Set it to
+  `false` only to hide a production build.
 
 ## Update loop
 

package/skills/configure-animation/SKILL.md

@@ -20,7 +20,7 @@ Get clip and joint names from `inspect-glb`; never guess them.
 ## Prove playback
 
 An active state or advancing state time does not prove motion. Sample two non-root joints over
-several rendered frames at idle and at both ends of each blend tree. Zero joint motion means a
+several rendered frames (`inspect-runtime`) at idle and at both ends of each blend tree. Zero joint motion means a
 binding, playback, or blend-weight failure.
 
 ## Diagnose

package/skills/inspect-runtime/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: inspect-runtime
+description: Use when reading state from a running PlayCanvas app, to reach its live Application through the Engine devtools hook without changing app code.
+---
+
+# Inspect a running app
+
+From Engine 2.23, every app announces itself to a hook at
+`globalThis[Symbol.for('playcanvas.inspector')]`. Read live state through it instead of adding
+`window.app` or debug code to the app.
+
+## Attach
+
+- Resolve `scripts/devtools-hook.js` relative to this skill and inject it as an init script that
+  runs before any page script. A hook defined later misses existing apps; reload instead.
+- Page code then reads `globalThis.__playcanvasApps`, a `Map` from each live app to
+  `{ version, revision, protocol }`. `app.init()` adds the entry and `app.destroy()` removes it.
+- The script chains a hook defined before it, such as a devtools extension's.
+- No entry means the Engine predates 2.23, the hook loaded late, or the app set
+  `devtools: false`. The Engine swallows errors thrown by the hook.
+- In 2.23.0 only the debug build (`playcanvas/debug`, `build/playcanvas.dbg.*`) announces apps; the
+  default import never calls the hook. Later 2.23 patches fix every build.
+
+## Read state
+
+- Read after `frameend`, so values reflect a rendered frame.
+- Return plain numbers and strings to the caller, not Engine objects.
+- Useful reads: `app.root.findByName()` and `findByTag()`, world positions and
+  `meshInstance.aabb`, `app.stats.drawCallCount` and `frameTime`, and
+  `entity.anim.baseLayer.activeState`.
+- Pause with `app.timeScale = 0`; `update` still runs with a zero `dt`. Step one frame by restoring
+  the scale, then zeroing it again on the next `frameend`.
+- Revert anything you change to take a measurement.
+
+## Inspector panel
+
+`@playcanvas/inspector` adds a panel for people: `new Inspector(app)` shows the hierarchy, assets,
+materials, shaders, textures, render targets, frame graph, and physics. It must import the app's
+own `playcanvas` package, so add it only to development builds. It draws over the canvas and
+applies view overrides, so destroy it before `verify-pixels` captures. Stepping through draws
+needs the debug build.

package/skills/inspect-runtime/scripts/devtools-hook.js

@@ -0,0 +1,23 @@
+// Records every PlayCanvas app (Engine 2.23+) in globalThis.__playcanvasApps, a Map from app to
+// { version, revision, protocol }. Run it before any page script; apps created earlier are missed.
+// Plain script with no imports or exports, so it runs as an init script, a <script>, or an import.
+{
+    const key = Symbol.for('playcanvas.inspector');
+    const prev = globalThis[key];
+    const apps = (globalThis.__playcanvasApps ??= new Map());
+
+    // chain a hook defined earlier, such as a devtools extension's, and install only once
+    if (!prev?.playcanvasApps) {
+        globalThis[key] = {
+            playcanvasApps: apps,
+            register(app, info) {
+                apps.set(app, info);
+                prev?.register?.(app, info);
+            },
+            unregister(app) {
+                apps.delete(app);
+                prev?.unregister?.(app);
+            }
+        };
+    }
+}

package/skills/override-shader-chunks/SKILL.md

@@ -8,7 +8,7 @@ description: Use when a PlayCanvas StandardMaterial needs custom shading its pro
 Overriding a `StandardMaterial` chunk keeps fog, tone mapping, shadows, skinning, and instancing
 intact. Use a `ShaderMaterial` only when the look needs its own vertex and fragment pair.
 
-- Set `material.shaderChunksVersion` to the installed major.minor, such as `'2.22'`. Chunk names
+- Set `material.shaderChunksVersion` to the installed major.minor, such as `'2.23'`. Chunk names
   and contracts change between versions, so read the installed chunk source, not memory.
 - Set chunks with `material.getShaderChunks(SHADERLANGUAGE_GLSL).set(name, source)` and the WGSL
   equivalent, then call `material.update()`. For every material on a device, use

package/skills/reduce-draw-calls/SKILL.md

@@ -5,10 +5,10 @@ description: Use when a PlayCanvas app has too many draw calls or is CPU-bound,
 
 # Cut draw calls
 
-Measure first with `app.stats.drawCalls.total` or `MiniStats`; the per-pass breakdown fills only in
-profiler builds. Also halve the pixel ratio and call `app.resizeCanvas()`: if frame time drops, the
-cost is fill rate, not draw calls. Stop at the first rung that meets the budget and report
-before-and-after counts.
+Measure first with `app.stats.drawCallCount` or `MiniStats`; the per-pass `app.stats.drawCalls`
+breakdown fills only in profiler builds. Also halve the pixel ratio and call `app.resizeCanvas()`:
+if frame time drops, the cost is fill rate, not draw calls. Stop at the first rung that meets the
+budget and report before-and-after counts.
 
 ## 1. Stop drawing hidden things
 

package/skills/verify-pixels/SKILL.md

@@ -33,4 +33,4 @@ description: Use when a PlayCanvas rendering change is meant to leave the image
 - Report the count, for example "0 of 65536 pixels differ", or the count and where the differences
   are. "Looks the same" is not a result.
 
-Keep harness code out of the shipped bundle.
+Keep harness code out of the shipped bundle; attach it through `inspect-runtime`.

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

@@ -1,7 +1,10 @@
 import type { Entity, RigidBodyComponentSystem } from 'playcanvas';
-import { Script } from 'playcanvas';
+import { Script, Vec3 } from 'playcanvas';
 import { ThirdPersonController } from 'playcanvas/scripts/esm/third-person-controller.mjs';
 
+/** Ground probes under the player's box collider (half width 0.4): centre, edges and corners */
+const FEET = [-0.38, 0, 0.38].flatMap((x) => [-0.38, 0, 0.38].map((z) => [x, z]));
+
 class RobotAnimation extends Script {
     static scriptName = 'robotAnimation';
 
@@ -28,9 +31,10 @@ class RobotAnimation extends Script {
 }
 
 export const addThirdPersonController = (player: Entity, camera: Entity, model: Entity) => {
-    (player.rigidbody!.system as RigidBodyComponentSystem).gravity.set(0, -18, 0);
+    const sys = player.rigidbody!.system as RigidBodyComponentSystem;
+    sys.gravity.set(0, -18, 0);
     if (!player.script) player.addComponent('script');
-    player.script!.create(ThirdPersonController, {
+    const controller = player.script!.create(ThirdPersonController, {
         properties: {
             camera,
             characterModel: model,
@@ -41,6 +45,24 @@ export const addThirdPersonController = (player: Entity, camera: Entity, model:
             jumpForce: 520,
             speedGround: 60
         }
+    })!;
+
+    // The stock ground check is one ray from the centre, so a player standing on a ledge reads as
+    // airborne and can't jump. Count it grounded when any probe under the collider finds a solid
+    // surface; triggers (colliders without a rigid body) only stop the camera
+    const [from, to] = [new Vec3(), new Vec3()];
+    const solid = { filterCallback: (e: Entity) => !!e.rigidbody };
+    let grounded = false;
+    Object.defineProperty(controller, '_grounded', {
+        get: () => grounded,
+        set: () => {
+            const p = player.getPosition();
+            grounded = FEET.some(([x, z]) => {
+                from.set(p.x + x, p.y, p.z + z);
+                to.set(from.x, p.y - 1.1, from.z);
+                return !!sys.raycastFirst(from, to, solid);
+            });
+        }
     });
 
     if (!model.script) model.addComponent('script');

package/templates/engine/base/README.md

@@ -17,6 +17,10 @@ npm run dev
 
 Open <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
 
+## Inspector
+
+`npm run dev` loads the [PlayCanvas Inspector](https://github.com/playcanvas/inspector), a debug panel for the hierarchy, assets, materials, textures, frame graph and physics. Press the backquote key (<kbd>&#96;</kbd>) to show or hide it, <kbd>F9</kbd> to pause and <kbd>F10</kbd> to step a frame. It is wired up in `vite.config.ts` and `src/inspector.ts` and is left out of production builds.
+
 ## Scripts
 
 | Command             | Description                       |

package/templates/engine/base/package.json

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

package/templates/engine/base/src/inspector.css

@@ -0,0 +1,33 @@
+/* Inspector key hint, added on the dev server only by src/inspector.ts. Styled like the starter panels */
+.inspector-hint {
+    position: fixed;
+    bottom: 20px;
+    left: 20px;
+    z-index: 10;
+    margin: 0;
+    padding: 8px 12px;
+    border: 1px solid #ffffff24;
+    border-radius: 10px;
+    background: #0b1019d9;
+    box-shadow: 0 12px 40px #0008;
+    color: #aeb8c8;
+    font:
+        12px/1.6 Inter,
+        ui-sans-serif,
+        system-ui,
+        sans-serif;
+    backdrop-filter: blur(12px);
+    pointer-events: none;
+}
+
+.inspector-hint kbd {
+    padding: 1px 5px;
+    border-radius: 4px;
+    background: #263247;
+    color: #f8fafc;
+    font:
+        11px ui-monospace,
+        SFMono-Regular,
+        Menlo,
+        monospace;
+}

package/templates/engine/base/src/inspector.ts

@@ -0,0 +1,38 @@
+// Loaded by the dev server only (see vite.config.ts), so production builds never include it
+import { Inspector } from '@playcanvas/inspector';
+import type { AppBase } from 'playcanvas';
+
+import './inspector.css';
+
+type Hook = {
+    register?(app: AppBase, info: object): void;
+    unregister?(app: AppBase): void;
+};
+
+// Every app announces itself to this hook as it starts, whichever format created it
+const KEY = Symbol.for('playcanvas.inspector');
+const scope = globalThis as unknown as Record<symbol, Hook | undefined>;
+
+// Keep a hook installed earlier, such as a devtools extension's
+const prev = scope[KEY];
+
+scope[KEY] = {
+    register(app, info) {
+        prev?.register?.(app, info);
+
+        // Skip headless apps, such as the null apps @playcanvas/react creates for validation. Each
+        // panel destroys itself with its app
+        if (!app.graphicsDevice.isNull) new Inspector(app, { visible: false });
+    },
+    unregister(app) {
+        prev?.unregister?.(app);
+    }
+};
+
+console.info('PlayCanvas Inspector: press ` to toggle');
+
+// Key hint, a separate corner chip so the starter's own UI stays untouched
+const hint = document.createElement('p');
+hint.className = 'inspector-hint';
+hint.innerHTML = '<kbd>`</kbd> inspector · <kbd>F9</kbd> pause · <kbd>F10</kbd> step';
+document.body.append(hint);

package/templates/engine/base/tsconfig.json

@@ -21,5 +21,5 @@
         "noFallthroughCasesInSwitch": true,
         "noUncheckedSideEffectImports": true
     },
-    "include": ["src"]
+    "include": ["src", "vite.config.ts"]
 }

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

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite';
+
+// https://vite.dev/config/
+export default defineConfig({
+    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/engine/interactive-sphere/src/App.ts

@@ -1,4 +1,4 @@
-import type { Layer, Texture } from 'playcanvas';
+import type { Layer } from 'playcanvas';
 import {
     createGraphicsDevice,
     AppBase,
@@ -89,7 +89,7 @@ const setupApp = async (canvas: HTMLCanvasElement, onClick: () => void) => {
     app.start();
 
     // Set up environment lighting (no skybox, just IBL)
-    app.scene.envAtlas = assets.envAtlas.resource as Texture;
+    app.scene.envAtlas = assets.envAtlas.resource!;
     const skyboxLayer = app.scene.layers.getLayerByName('Skybox');
     if (skyboxLayer) {
         skyboxLayer.enabled = false;

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

@@ -1,4 +1,3 @@
-import type { ContainerResource } from 'playcanvas';
 import {
     AppBase,
     AppOptions,
@@ -57,7 +56,7 @@ await new Promise<void>((resolve) => {
 app.start();
 
 // A container asset holds the whole glTF scene, so instantiate it to get an entity hierarchy
-app.root.addChild((model.resource as ContainerResource).instantiateRenderEntity());
+app.root.addChild(model.resource!.instantiateRenderEntity());
 
 // The procedural sky is both the background and the image-based lighting, so no light or
 // environment map asset is needed. Its default luminance is scene-scale bright, so turn it down to

package/templates/engine/product-configurator/src/main.ts

@@ -1,4 +1,3 @@
-import type { ContainerResource, RenderComponent } from 'playcanvas';
 import {
     AppBase,
     AppOptions,
@@ -62,12 +61,12 @@ await new Promise<void>((resolve) => new AssetListLoader([product], app.assets).
 
 app.start();
 
-const car = (product.resource as ContainerResource).instantiateRenderEntity();
+const car = product.resource!.instantiateRenderEntity();
 car.setLocalEulerAngles(-90, -25, 0);
 app.root.addChild(car);
 app.root.syncHierarchy();
 
-const meshes = (car.findComponents('render') as RenderComponent[]).flatMap((render) => render.meshInstances);
+const meshes = car.findComponents('render').flatMap((render) => render.meshInstances);
 const bounds = meshes[0].aabb.clone();
 meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
 const scale = 5 / Math.max(bounds.halfExtents.x * 2, bounds.halfExtents.z * 2);
@@ -77,10 +76,10 @@ bounds.copy(meshes[0].aabb);
 meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
 car.setPosition(-bounds.center.x, 0.03 - bounds.getMin().y, -bounds.center.z);
 
-const body = meshes.filter((mesh) => mesh.material.name === 'material');
-const panels = meshes.filter((mesh) => mesh.material.name === 'material_1');
-const paint = body[0].material.clone() as StandardMaterial;
-const shade = panels[0].material.clone() as StandardMaterial;
+const body = meshes.filter((mesh) => mesh.material?.name === 'material');
+const panels = meshes.filter((mesh) => mesh.material?.name === 'material_1');
+const paint = body[0].material!.clone() as StandardMaterial;
+const shade = panels[0].material!.clone() as StandardMaterial;
 body.forEach((mesh) => (mesh.material = paint));
 panels.forEach((mesh) => (mesh.material = shade));
 paint.diffuse.fromString(PAINTS[0].color);

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

@@ -134,6 +134,9 @@ for (const [i, [x, z, size]] of TREES.entries()) {
         crown.setPosition(x, size * y, z);
         crown.setLocalScale(size * width, size * height, size * width);
         crown.addComponent('render', { type: 'cone', material: j === 1 ? tips : leaves });
+
+        // A trigger: it stops the camera's line of sight but the player walks through it
+        crown.addComponent('collision', { type: 'cone', radius: (size * width) / 2, height: size * height });
         app.root.addChild(crown);
     }
 }
@@ -142,11 +145,13 @@ prop('stump', [-1.8, 0.4, -2.2], [0.9, 0.8, 0.9], wood);
 
 const player = new Entity('player');
 player.setPosition(0, 1.1, 0);
+
+// A box rather than a capsule, so the player stands on ledges instead of sliding off them. Its
+// bottom sits 1 m below the body, inside the controller's 1.1 m ground probes
 player.addComponent('collision', {
-    type: 'capsule',
-    radius: 0.5,
-    height: 2.4,
-    linearOffset: new Vec3(0, 0.1, 0)
+    type: 'box',
+    halfExtents: new Vec3(0.4, 1.2, 0.4),
+    linearOffset: new Vec3(0, 0.2, 0)
 });
 player.addComponent('rigidbody', { type: 'dynamic', mass: 70, angularFactor: Vec3.ZERO });
 app.root.addChild(player);
@@ -162,7 +167,7 @@ pants.diffuse = new Color(0.18, 0.29, 0.52);
 pants.update();
 
 const model = new Entity('character');
-model.setLocalPosition(0, 0.2, 0);
+model.setLocalPosition(0, 0.3, 0);
 const part = (
     parent: Entity,
     name: string,

package/templates/react/base/README.md

@@ -17,6 +17,10 @@ npm run dev
 
 Open <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
 
+## Inspector
+
+`npm run dev` loads the [PlayCanvas Inspector](https://github.com/playcanvas/inspector), a debug panel for the hierarchy, assets, materials, textures, frame graph and physics. Press the backquote key (<kbd>&#96;</kbd>) to show or hide it, <kbd>F9</kbd> to pause and <kbd>F10</kbd> to step a frame. It is wired up in `vite.config.ts` and `src/inspector.ts` and is left out of production builds.
+
 ## Scripts
 
 | Command             | Description                       |

package/templates/react/base/package.json

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

package/templates/react/base/src/inspector.css

@@ -0,0 +1,33 @@
+/* Inspector key hint, added on the dev server only by src/inspector.ts. Styled like the starter panels */
+.inspector-hint {
+    position: fixed;
+    bottom: 20px;
+    left: 20px;
+    z-index: 10;
+    margin: 0;
+    padding: 8px 12px;
+    border: 1px solid #ffffff24;
+    border-radius: 10px;
+    background: #0b1019d9;
+    box-shadow: 0 12px 40px #0008;
+    color: #aeb8c8;
+    font:
+        12px/1.6 Inter,
+        ui-sans-serif,
+        system-ui,
+        sans-serif;
+    backdrop-filter: blur(12px);
+    pointer-events: none;
+}
+
+.inspector-hint kbd {
+    padding: 1px 5px;
+    border-radius: 4px;
+    background: #263247;
+    color: #f8fafc;
+    font:
+        11px ui-monospace,
+        SFMono-Regular,
+        Menlo,
+        monospace;
+}

package/templates/react/base/src/inspector.ts

@@ -0,0 +1,38 @@
+// Loaded by the dev server only (see vite.config.ts), so production builds never include it
+import { Inspector } from '@playcanvas/inspector';
+import type { AppBase } from 'playcanvas';
+
+import './inspector.css';
+
+type Hook = {
+    register?(app: AppBase, info: object): void;
+    unregister?(app: AppBase): void;
+};
+
+// Every app announces itself to this hook as it starts, whichever format created it
+const KEY = Symbol.for('playcanvas.inspector');
+const scope = globalThis as unknown as Record<symbol, Hook | undefined>;
+
+// Keep a hook installed earlier, such as a devtools extension's
+const prev = scope[KEY];
+
+scope[KEY] = {
+    register(app, info) {
+        prev?.register?.(app, info);
+
+        // Skip headless apps, such as the null apps @playcanvas/react creates for validation. Each
+        // panel destroys itself with its app
+        if (!app.graphicsDevice.isNull) new Inspector(app, { visible: false });
+    },
+    unregister(app) {
+        prev?.unregister?.(app);
+    }
+};
+
+console.info('PlayCanvas Inspector: press ` to toggle');
+
+// Key hint, a separate corner chip so the starter's own UI stays untouched
+const hint = document.createElement('p');
+hint.className = 'inspector-hint';
+hint.innerHTML = '<kbd>`</kbd> inspector · <kbd>F9</kbd> pause · <kbd>F10</kbd> step';
+document.body.append(hint);

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

@@ -3,5 +3,16 @@ import { defineConfig } from 'vite';
 
 // https://vite.dev/config/
 export default defineConfig({
-    plugins: [react()]
+    plugins: [
+        react(),
+        {
+            // 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/react/product-configurator/src/App.tsx

@@ -1,7 +1,7 @@
 import { Application, Entity } from '@playcanvas/react';
 import { Camera, Light, Script } from '@playcanvas/react/components';
 import { useApp, useModel } from '@playcanvas/react/hooks';
-import type { ContainerResource, Entity as PcEntity, RenderComponent } from 'playcanvas';
+import type { ContainerResource, Entity as PcEntity } from 'playcanvas';
 import { Color, CylinderGeometry, Mesh, MeshInstance, StandardMaterial, TONEMAP_ACES2, Vec2, Vec3 } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
@@ -32,7 +32,7 @@ function Product({ color, shade }: { color: string; shade: string }) {
         entity.setLocalEulerAngles(-90, -25, 0);
         root.current.addChild(entity);
 
-        const meshes = (entity.findComponents('render') as RenderComponent[]).flatMap((render) => render.meshInstances);
+        const meshes = entity.findComponents('render').flatMap((render) => render.meshInstances);
         const bounds = meshes[0].aabb.clone();
         meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
         const scale = 5 / Math.max(bounds.halfExtents.x * 2, bounds.halfExtents.z * 2);
@@ -42,10 +42,10 @@ function Product({ color, shade }: { color: string; shade: string }) {
         meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
         entity.setPosition(-bounds.center.x, 0.03 - bounds.getMin().y, -bounds.center.z);
 
-        const body = meshes.filter((mesh) => mesh.material.name === 'material');
-        const panels = meshes.filter((mesh) => mesh.material.name === 'material_1');
-        paint.current = body[0].material.clone() as StandardMaterial;
-        tone.current = panels[0].material.clone() as StandardMaterial;
+        const body = meshes.filter((mesh) => mesh.material?.name === 'material');
+        const panels = meshes.filter((mesh) => mesh.material?.name === 'material_1');
+        paint.current = body[0].material!.clone() as StandardMaterial;
+        tone.current = panels[0].material!.clone() as StandardMaterial;
         body.forEach((mesh) => (mesh.material = paint.current!));
         panels.forEach((mesh) => (mesh.material = tone.current!));
         return () => {

package/templates/react/third-person-controller/src/App.tsx

@@ -79,6 +79,8 @@ function Pine({
                     scale={[size * width, size * height, size * width]}
                 >
                     <Render type="cone" material={i === 1 ? tips : leaves} />
+                    {/* A trigger: it stops the camera's line of sight but the player walks through it */}
+                    <Collision type="cone" radius={(size * width) / 2} height={size * height} />
                 </Entity>
             ))}
         </>
@@ -139,9 +141,10 @@ function Scene() {
             <Block name="fallen-log" position={[0, 0.35, 6]} scale={[3.8, 0.7, 0.7]} material={wood} />
             <Block name="stump" position={[-1.8, 0.4, -2.2]} scale={[0.9, 0.8, 0.9]} material={wood} />
             <Entity name="player" ref={player} position={[0, 1.1, 0]}>
-                <Collision type="capsule" radius={0.5} height={2.4} linearOffset={[0, 0.1, 0]} />
+                {/* A box rather than a capsule, so the player stands on ledges instead of sliding off them */}
+                <Collision type="box" halfExtents={[0.4, 1.2, 0.4]} linearOffset={[0, 0.2, 0]} />
                 <RigidBody type="dynamic" mass={70} angularFactor={[0, 0, 0]} />
-                <Entity name="character" ref={model} position={[0, 0.2, 0]}>
+                <Entity name="character" ref={model} position={[0, 0.3, 0]}>
                     <Entity name="body" scale={[0.56, 0.88, 0.38]}>
                         <Render type="box" material={shirt} />
                     </Entity>

package/templates/web-components/base/README.md

@@ -18,6 +18,10 @@ npm run dev
 
 Open <http://localhost:5173>. Edit `index.html` to change the scene.
 
+## Inspector
+
+`npm run dev` loads the [PlayCanvas Inspector](https://github.com/playcanvas/inspector), a debug panel for the hierarchy, assets, materials, textures, frame graph and physics. Press the backquote key (<kbd>&#96;</kbd>) to show or hide it, <kbd>F9</kbd> to pause and <kbd>F10</kbd> to step a frame. It is wired up in `vite.config.ts` and `src/inspector.ts` and is left out of production builds.
+
 ## Scripts
 
 | Command             | Description                       |

package/templates/web-components/base/package.json

@@ -15,15 +15,16 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "@playcanvas/web-components": "^0.26.0",
-        "playcanvas": "^2.22.6"
+        "@playcanvas/web-components": "^0.28.0",
+        "playcanvas": "^2.23.1"
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
+        "@playcanvas/inspector": "^0.2.0",
         "eslint": "^9.39.5",
         "prettier": "^3.9.9",
         "typescript": "~6.0.3",
-        "vite": "^8.3.1"
+        "vite": "^8.3.4"
     },
     "engines": {
         "node": ">=22.23.2"

package/templates/web-components/base/src/inspector.css

@@ -0,0 +1,33 @@
+/* Inspector key hint, added on the dev server only by src/inspector.ts. Styled like the starter panels */
+.inspector-hint {
+    position: fixed;
+    bottom: 20px;
+    left: 20px;
+    z-index: 10;
+    margin: 0;
+    padding: 8px 12px;
+    border: 1px solid #ffffff24;
+    border-radius: 10px;
+    background: #0b1019d9;
+    box-shadow: 0 12px 40px #0008;
+    color: #aeb8c8;
+    font:
+        12px/1.6 Inter,
+        ui-sans-serif,
+        system-ui,
+        sans-serif;
+    backdrop-filter: blur(12px);
+    pointer-events: none;
+}
+
+.inspector-hint kbd {
+    padding: 1px 5px;
+    border-radius: 4px;
+    background: #263247;
+    color: #f8fafc;
+    font:
+        11px ui-monospace,
+        SFMono-Regular,
+        Menlo,
+        monospace;
+}

package/templates/web-components/base/src/inspector.ts

@@ -0,0 +1,38 @@
+// Loaded by the dev server only (see vite.config.ts), so production builds never include it
+import { Inspector } from '@playcanvas/inspector';
+import type { AppBase } from 'playcanvas';
+
+import './inspector.css';
+
+type Hook = {
+    register?(app: AppBase, info: object): void;
+    unregister?(app: AppBase): void;
+};
+
+// Every app announces itself to this hook as it starts, whichever format created it
+const KEY = Symbol.for('playcanvas.inspector');
+const scope = globalThis as unknown as Record<symbol, Hook | undefined>;
+
+// Keep a hook installed earlier, such as a devtools extension's
+const prev = scope[KEY];
+
+scope[KEY] = {
+    register(app, info) {
+        prev?.register?.(app, info);
+
+        // Skip headless apps, such as the null apps @playcanvas/react creates for validation. Each
+        // panel destroys itself with its app
+        if (!app.graphicsDevice.isNull) new Inspector(app, { visible: false });
+    },
+    unregister(app) {
+        prev?.unregister?.(app);
+    }
+};
+
+console.info('PlayCanvas Inspector: press ` to toggle');
+
+// Key hint, a separate corner chip so the starter's own UI stays untouched
+const hint = document.createElement('p');
+hint.className = 'inspector-hint';
+hint.innerHTML = '<kbd>`</kbd> inspector · <kbd>F9</kbd> pause · <kbd>F10</kbd> step';
+document.body.append(hint);

package/templates/web-components/base/tsconfig.json

@@ -21,5 +21,5 @@
         "noFallthroughCasesInSwitch": true,
         "noUncheckedSideEffectImports": true
     },
-    "include": ["src"]
+    "include": ["src", "vite.config.ts"]
 }

package/templates/web-components/base/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from 'vite';
+
+// https://vite.dev/config/
+export default defineConfig({
+    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/web-components/interactive-sphere/src/main.ts

@@ -1,6 +1,5 @@
 import type { EntityElement } from '@playcanvas/web-components';
 import { whenReady } from '@playcanvas/web-components';
-import type { Texture } from 'playcanvas';
 import { Asset, TEXTURETYPE_RGBP } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { Grid } from 'playcanvas/scripts/esm/grid.mjs';
@@ -40,7 +39,7 @@ await new Promise<void>((resolve) => {
 });
 
 // Light the scene from the environment, with the skybox itself left hidden
-app.scene.envAtlas = envAtlas.resource as Texture;
+app.scene.envAtlas = envAtlas.resource!;
 const skyboxLayer = app.scene.layers.getLayerByName('Skybox');
 if (skyboxLayer) {
     skyboxLayer.enabled = false;

package/templates/web-components/product-configurator/src/main.ts

@@ -1,6 +1,5 @@
 import type { AssetElement, EntityElement, ModelElement } from '@playcanvas/web-components';
 import { whenReady } from '@playcanvas/web-components';
-import type { RenderComponent } from 'playcanvas';
 import { Color, CylinderGeometry, Mesh, MeshInstance, StandardMaterial, Vec2, Vec3 } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
@@ -63,7 +62,7 @@ ground.addComponent('render', {
 const entity = model.entity!;
 entity.setLocalEulerAngles(0, -25, 0);
 entity.root.syncHierarchy();
-const meshes = (entity.findComponents('render') as RenderComponent[]).flatMap((render) => render.meshInstances);
+const meshes = entity.findComponents('render').flatMap((render) => render.meshInstances);
 const bounds = meshes[0].aabb.clone();
 meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
 const scale = 5 / Math.max(bounds.halfExtents.x * 2, bounds.halfExtents.z * 2);
@@ -73,10 +72,10 @@ bounds.copy(meshes[0].aabb);
 meshes.slice(1).forEach((mesh) => bounds.add(mesh.aabb));
 entity.setPosition(-bounds.center.x, 0.03 - bounds.getMin().y, -bounds.center.z);
 
-const body = meshes.filter((mesh) => mesh.material.name === 'material');
-const panels = meshes.filter((mesh) => mesh.material.name === 'material_1');
-const paint = body[0].material.clone() as StandardMaterial;
-const shade = panels[0].material.clone() as StandardMaterial;
+const body = meshes.filter((mesh) => mesh.material?.name === 'material');
+const panels = meshes.filter((mesh) => mesh.material?.name === 'material_1');
+const paint = body[0].material!.clone() as StandardMaterial;
+const shade = panels[0].material!.clone() as StandardMaterial;
 body.forEach((mesh) => (mesh.material = paint));
 panels.forEach((mesh) => (mesh.material = shade));
 paint.diffuse.fromString('#d6293e');

package/templates/web-components/third-person-controller/index.html

@@ -65,12 +65,15 @@
                 ></pc-entity>
                 <pc-entity name="tree-0-crown-0" position="-7 2.09 -6" scale="2.31 1.98 2.31"
                     ><pc-render type="cone" material="leaves-material"></pc-render
+                    ><pc-collision type="cone" radius="1.155" height="1.98"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-0-crown-1" position="-7 2.915 -6" scale="1.76 1.705 1.76"
                     ><pc-render type="cone" material="tips-material"></pc-render
+                    ><pc-collision type="cone" radius="0.88" height="1.705"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-0-crown-2" position="-7 3.63 -6" scale="1.21 1.54 1.21"
                     ><pc-render type="cone" material="leaves-material"></pc-render
+                    ><pc-collision type="cone" radius="0.605" height="1.54"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-1-trunk" position="6.5 1.125 -6.5" scale="0.475 2.25 0.475"
                     ><pc-render type="box" material="wood-material"></pc-render
@@ -79,12 +82,15 @@
                 ></pc-entity>
                 <pc-entity name="tree-1-crown-0" position="6.5 2.375 -6.5" scale="2.625 2.25 2.625"
                     ><pc-render type="cone" material="leaves-material"></pc-render
+                    ><pc-collision type="cone" radius="1.3125" height="2.25"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-1-crown-1" position="6.5 3.3125 -6.5" scale="2 1.9375 2"
                     ><pc-render type="cone" material="tips-material"></pc-render
+                    ><pc-collision type="cone" radius="1" height="1.9375"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-1-crown-2" position="6.5 4.125 -6.5" scale="1.375 1.75 1.375"
                     ><pc-render type="cone" material="leaves-material"></pc-render
+                    ><pc-collision type="cone" radius="0.6875" height="1.75"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-2-trunk" position="-7.5 0.81 5" scale="0.342 1.62 0.342"
                     ><pc-render type="box" material="wood-material"></pc-render
@@ -93,12 +99,15 @@
                 ></pc-entity>
                 <pc-entity name="tree-2-crown-0" position="-7.5 1.71 5" scale="1.89 1.62 1.89"
                     ><pc-render type="cone" material="leaves-material"></pc-render
+                    ><pc-collision type="cone" radius="0.945" height="1.62"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-2-crown-1" position="-7.5 2.385 5" scale="1.44 1.395 1.44"
                     ><pc-render type="cone" material="tips-material"></pc-render
+                    ><pc-collision type="cone" radius="0.72" height="1.395"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-2-crown-2" position="-7.5 2.97 5" scale="0.99 1.26 0.99"
                     ><pc-render type="cone" material="leaves-material"></pc-render
+                    ><pc-collision type="cone" radius="0.495" height="1.26"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-3-trunk" position="7 1.035 5.5" scale="0.437 2.07 0.437"
                     ><pc-render type="box" material="wood-material"></pc-render
@@ -107,12 +116,15 @@
                 ></pc-entity>
                 <pc-entity name="tree-3-crown-0" position="7 2.185 5.5" scale="2.415 2.07 2.415"
                     ><pc-render type="cone" material="leaves-material"></pc-render
+                    ><pc-collision type="cone" radius="1.2075" height="2.07"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-3-crown-1" position="7 3.0475 5.5" scale="1.84 1.7825 1.84"
                     ><pc-render type="cone" material="tips-material"></pc-render
+                    ><pc-collision type="cone" radius="0.92" height="1.7825"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-3-crown-2" position="7 3.795 5.5" scale="1.265 1.61 1.265"
                     ><pc-render type="cone" material="leaves-material"></pc-render
+                    ><pc-collision type="cone" radius="0.6325" height="1.61"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-4-trunk" position="-2.2 0.765 -8" scale="0.323 1.53 0.323"
                     ><pc-render type="box" material="wood-material"></pc-render
@@ -121,12 +133,15 @@
                 ></pc-entity>
                 <pc-entity name="tree-4-crown-0" position="-2.2 1.615 -8" scale="1.785 1.53 1.785"
                     ><pc-render type="cone" material="leaves-material"></pc-render
+                    ><pc-collision type="cone" radius="0.8925" height="1.53"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-4-crown-1" position="-2.2 2.2525 -8" scale="1.36 1.3175 1.36"
                     ><pc-render type="cone" material="tips-material"></pc-render
+                    ><pc-collision type="cone" radius="0.68" height="1.3175"></pc-collision
                 ></pc-entity>
                 <pc-entity name="tree-4-crown-2" position="-2.2 2.805 -8" scale="0.935 1.19 0.935"
                     ><pc-render type="cone" material="leaves-material"></pc-render
+                    ><pc-collision type="cone" radius="0.4675" height="1.19"></pc-collision
                 ></pc-entity>
                 <pc-entity name="fallen-log" position="0 0.35 6" scale="3.8 0.7 0.7"
                     ><pc-render type="box" material="wood-material"></pc-render
@@ -139,9 +154,9 @@
                     ><pc-rigid-body type="static"></pc-rigid-body
                 ></pc-entity>
                 <pc-entity name="player" position="0 1.1 0">
-                    <pc-collision type="capsule" radius="0.5" height="2.4" linear-offset="0 0.1 0"></pc-collision>
+                    <pc-collision type="box" half-extents="0.4 1.2 0.4" linear-offset="0 0.2 0"></pc-collision>
                     <pc-rigid-body type="dynamic" mass="70" angular-factor="0 0 0"></pc-rigid-body>
-                    <pc-entity name="character" position="0 0.2 0">
+                    <pc-entity name="character" position="0 0.3 0">
                         <pc-entity name="body" scale="0.56 0.88 0.38"
                             ><pc-render type="box" material="shirt-material"></pc-render
                         ></pc-entity>