create-playcanvas 0.8.0 → 0.9.0

package/skills/assemble-scene/references/react.md

@@ -7,11 +7,11 @@ import { Entity } from '@playcanvas/react';
 import { Collision, RigidBody } from '@playcanvas/react/components';
 
 // Model is the project's calibrated component from calibrate-model, not a library export
-const Enemy = ({ id, position, heading }) => (
-    <Entity name={`Enemy_${id}`} position={position} rotation={[0, heading, 0]}>
+const SceneObject = ({ id, position, heading }) => (
+    <Entity name={`Model_${id}`} position={position} rotation={[0, heading, 0]}>
         <RigidBody type="dynamic" mass={1} />
         <Collision type="capsule" />
-        <Model id="enemy" src="/models/Enemy.glb" />
+        <Model id="model" src="/models/model.glb" />
     </Entity>
 );
 ```

package/skills/assemble-scene/references/web-components.md

@@ -3,11 +3,11 @@
 Represent the whole gameplay object below one semantic root:
 
 ```html
-<pc-entity name="Enemy_1" position="4 0 -3" rotation="0 90 0">
+<pc-entity name="Model_1" position="4 0 -3" rotation="0 90 0">
     <pc-rigid-body type="dynamic" mass="1"></pc-rigid-body>
     <pc-collision type="capsule"></pc-collision>
     <pc-entity position="0 0.8 0" rotation="0 180 0" scale="0.01 0.01 0.01">
-        <pc-model asset="enemy"></pc-model>
+        <pc-model asset="model"></pc-model>
     </pc-entity>
 </pc-entity>
 ```

package/skills/bake-lighting/SKILL.md

@@ -1,61 +1,36 @@
 ---
 name: bake-lighting
-description: Use when a PlayCanvas scene's static lighting, shadows, or ambient occlusion costs too much per frame, or lighting must ship precomputed for startup or payload budgets.
+description: Use when static PlayCanvas lighting, shadows, or ambient occlusion cost too much per frame and should be baked into lightmaps.
 ---
 
-# Precompute static lighting
+# Bake static lighting
 
-Static geometry lit by static lights can bake into lightmap textures once, removing per-frame
-shadow-map rendering and per-pixel dynamic lighting for that light entirely.
+Lightmaps remove per-frame shadow and lighting cost for static lights on static geometry.
 
-## Engine `Lightmapper` flags
+- `Application` registers `Lightmapper`; manual `AppOptions` bootstraps set
+  `lightmapper = Lightmapper`.
+- On the light, set `bake = true`; once every mesh it lights is lightmapped, set
+  `affectDynamic = false`.
+- On each mesh, set `render.lightmapped = true`, or it goes unlit once `affectDynamic` is off. Size
+  it with `lightmapSizeMultiplier`; `castShadowsLightmap` lets meshes shadow each other.
+- Set the mode on `scene.lightmapMode`: `BAKE_COLOR` for flat diffuse, or the default
+  `BAKE_COLORDIR`, which adds direction for normal- or specular-mapped materials.
+- Bake AO without lights with `scene.ambientBake`, `ambientBakeNumSamples`, and
+  `ambientBakeOcclusionBrightness` and `ambientBakeOcclusionContrast`.
+- The Engine bakes once on the first rendered frame. Call `app.lightmapper.bake(null, mode)` only
+  for nodes added later or to re-bake.
 
-- Engine-only bootstraps must register it: `AppOptions.lightmapper = Lightmapper`. `Application`
-  wires this by default; only a manual `AppOptions` assembly needs the explicit line.
-- Per light: `light.bake = true`, then `light.affectDynamic = false` once every mesh it lights is
-  lightmapped, so it stops contributing to the real-time pass.
-- Per mesh: `render.lightmapped = true` — required for the mesh to receive any light once
-  `affectDynamic` is false, a correctness requirement, not just an optimization —
-  `render.lightmapSizeMultiplier` to size its lightmap, `render.castShadowsLightmap` so lightmapped
-  meshes still shadow each other in the bake.
-- Bake mode: `BAKE_COLOR` for flat diffuse materials; `BAKE_COLORDIR` adds a dominant-light-direction
-  pass for normal- or specular-mapped materials that need one.
-- Baked ambient occlusion, independent of any light: `scene.ambientBake` plus
-  `ambientBakeNumSamples`, `ambientBakeOcclusionBrightness`/`OcclusionContrast`.
-- Run `app.lightmapper.bake(null, mode)` once the scene exists; `null` bakes every lightmapped node.
+## A second UV set is required
 
-## Verify UVs before trusting this on real assets
+A node bakes only when every mesh instance has `SEMANTIC_TEXCOORD1`. Otherwise it is skipped, with
+only a debug-build log, and stays dynamically lit. Primitives have the set; imported GLBs often do
+not. Check, then unwrap or re-export.
 
-Procedural primitives auto-generate a usable UV set; imported GLB models often do not ship a second,
-non-overlapping UV channel suitable for a lightmap atlas. Read the installed engine's source for
-what its `Lightmapper` actually requires — which UV set it samples, whether it unwraps one for you —
-before assuming a real model will bake correctly. Do not carry a primitive-only test result into
-production assets unchecked.
+## On-device or offline
 
-## Choose the rung by budget, not by default
+Time `bake()` on the target device. Move to an offline bake shipped as textures only when it misses
+the startup budget or needs detail the runtime lightmapper cannot produce, and state the added
+download size.
 
-On-device bake cost scales with baked-node count and lightmap resolution; estimate it against the
-startup budget before choosing a rung. Stay on-device unless:
-
-- the estimated bake time does not fit the startup or first-paint budget on the target device, or
-- the result needs stylized material detail beyond lighting that the runtime `Lightmapper` cannot
-  produce.
-
-Only then move to an offline bake shipped as assets, following the same shape as any other
-generated-asset pipeline: registry-keyed per-asset configs (a new asset is a config change, not new
-pipeline code), a CLI with per-target fast paths, staged size logging, worker-thread parallelism for
-build time, and a coverage self-audit that fails the bake when an expected output is missing or
-empty.
-
-## Keep dynamic objects consistent
-
-Whichever rung you use, dynamic objects moving through baked lighting must not read as ignoring it:
-sample or approximate the baked occlusion/shadow field for them and their attachments so they dim to
-the same levels as the static geometry around them, and ground them with a contact shadow. A
-dynamic object whose custom shading must meet baked maps is `override-shader-chunks` territory.
-
-## Prove it
-
-Capture `verify-pixels`-style frames both in and out of the baked shadow, before and after the
-change, and compare them. A screenshot glanced at once is not proof the bake reproduced the lighting
-it removed.
+Dynamic objects moving through baked light need approximated occlusion and a contact shadow, or
+they look pasted on. Compare `verify-pixels` captures in and out of baked shadow.

package/skills/build-app/SKILL.md

@@ -1,41 +1,42 @@
 ---
 name: build-app
-description: Use when creating or restructuring a PlayCanvas application with the direct Engine API, @playcanvas/react, or @playcanvas/web-components to choose the active authoring surface and apply its bootstrap, lifecycle, ownership, asset-loading, and Engine interop patterns.
+description: Use when creating or restructuring a PlayCanvas app with the Engine API, @playcanvas/react, or @playcanvas/web-components, covering bootstrap, input, resize, physics, update loop, UI, and lifecycle.
 ---
 
 # Build an Engine application
 
-Read `package.json` and the application entry point before changing its structure. Choose the
-authoring surface from the code being edited:
+Read `package.json` and the entry point, keep the surface that owns the lifecycle, and read only its
+reference: [direct Engine](references/direct-engine.md), [React](references/react.md), or
+[Web Components](references/web-components.md). Choose from imports and markup, not dependencies.
 
-- read [references/react.md](references/react.md) for `@playcanvas/react` imports and JSX;
-- read [references/web-components.md](references/web-components.md) for `pc-*` elements or
-  `@playcanvas/web-components` imports;
-- read [references/direct-engine.md](references/direct-engine.md) for direct `playcanvas` bootstrap
-  code without a wrapper-owned lifecycle.
+## Bootstrap
 
-Installed dependencies alone are insufficient when a project contains more than one surface.
-Preserve the surface that owns the current entry point and lifecycle.
+- Input is opt-in. `app.keyboard`, `mouse`, `touch`, `gamepads`, and `elementInput` stay `null`
+  unless passed to `new Application(canvas, { ... })`; UI buttons need `new ElementInput(canvas)`.
+- The Engine adds no window resize listener; call `app.resizeCanvas()` from your own handler.
+- `graphicsDevice.maxPixelRatio` defaults to 1. Raise it, at most to `window.devicePixelRatio`, only
+  where the target holds its frame budget, call `app.resizeCanvas()`, and confirm with
+  `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`.
 
-## Render at an intentional density
+## Update loop
 
-PlayCanvas defaults `graphicsDevice.maxPixelRatio` to 1 for predictable fill-rate cost. In a
-quality-oriented browser app, set it deliberately after the application exists and before its
-initial automatic resize; `Math.min(window.devicePixelRatio, 2)` is a practical high-DPI starting
-point. Keep 1 only as a measured performance decision, and resize the canvas again after changing
-the value.
+- `dt` is already clamped by `app.maxDeltaTime` (0.1 s); tune it instead of clamping by hand.
+  `app.timeScale` scales it, and `0` pauses scaled time.
+- Keep app state explicit and owned in one place; advance time-dependent logic from `dt`, and reset
+  through the same setup used at start.
 
-Verify the real backbuffer in a browser: for automatic resolution, `canvas.width / canvas.clientWidth`
-and the height ratio should match the chosen pixel ratio. CSS dimensions and a screenshot filepath
-do not prove rendering density.
+## UI
 
-For every surface:
+- Render UI from app state; never keep the source of truth in the DOM or UI elements.
+- Use a DOM or React overlay, or Engine `screen` and `element` components adapted from a
+  `user-interface` example.
+- Hide unused elements with `enabled = false`; an element at opacity 0 still draws.
 
-- verify version-sensitive APIs against installed declarations or source;
-- keep one owner for application creation, assets, entities, update callbacks, and teardown;
-- prefer the surface's declarative or lifecycle primitives before reaching into the Engine;
-- put per-entity and per-frame behavior in an Engine `Script` when page or view state is not its
-  natural owner;
-- clamp the per-frame delta before advancing gameplay, timers, physics, or a state clock, so a
-  backgrounded tab or a slow frame cannot inject one large integration step;
-- clean up external events and resources in the lifecycle that created them.
+## Ownership
+
+- Keep one owner for app creation, assets, entities, update callbacks, and teardown.
+- Prefer the surface's declarative primitives. Put per-entity and per-frame behaviour in an Engine
+  `Script`.
+- Remove external events and resources in the lifecycle that created them.

package/skills/build-app/references/web-components.md

@@ -20,10 +20,10 @@ Build supported application structure declaratively:
 
 ```html
 <pc-app>
-    <pc-asset id="ship" src="/models/ship.glb"></pc-asset>
+    <pc-asset id="model" src="/models/model.glb"></pc-asset>
     <pc-scene>
-        <pc-entity name="Ship" position="0 0 -4">
-            <pc-model asset="ship"></pc-model>
+        <pc-entity name="Model" position="0 0 -4">
+            <pc-model asset="model"></pc-model>
         </pc-entity>
     </pc-scene>
 </pc-app>

package/skills/calibrate-model/SKILL.md

@@ -1,65 +1,35 @@
 ---
 name: calibrate-model
-description: Use before repeatedly placing GLB models in PlayCanvas Engine, React, or Web Components to measure each asset once and record its uniform scale, grounding offset, and yaw correction in a stable nested transform.
+description: Use before repeatedly placing GLB models in PlayCanvas to record each asset's uniform scale, grounding offset, pivot compensation, and yaw once.
 ---
 
 # Model calibration
 
-Use the `inspect-glb` skill to measure every unique GLB before mass placement. Rely on `dims` and
-`groundOffset` for contact-accurate placement only when it reports `boundsSource: vertices`. Store
-one tuning record per asset:
+Measure each unique GLB once with `inspect-glb`, only trusting bounds when `boundsSource` is
+`vertices`, and keep one tuning record per asset:
 
 ```ts
 const ASSET_TUNING = {
     model: {
-        boundsSource: 'vertices',
-        aabb: { min: [-4, -1, -9], max: [4, 6, 9] },
-        dims: [8, 7, 18],
-        center: [0, 2.5, 0],
-        groundOffset: 1,
-        intended: { dimension: 'length', size: 18 },
-        scale: 0.9,
-        y: 0.9,
-        yaw: 180
+        boundsSource: 'vertices', dims: [8, 7, 18], center: [0, 2.5, 0], groundOffset: 1,
+        intended: { dimension: 'length', size: 18 }, scale: 1, y: 1, yaw: 180
     }
 } as const;
 ```
 
-## Calculate the record
+1. Pick the dimension that defines the model's real size, in metres or relative to an already
+   calibrated model.
+2. Set `scale = intendedSize / measuredDimension` and, for floor-resting models,
+   `y = groundOffset * scale`. Record a deliberate offset for models that should not rest on the
+   floor.
+3. Confirm facing once in the running app and record `yaw`.
 
-1. Pick and record the intended dimension and size: character height, building footprint, or
-   vehicle length. Base it on world units or an already calibrated reference model.
-2. Calculate `scale = intendedSize / measuredDimension`.
-3. For a floor-resting model, calculate `y = groundOffset * scale`. Record a deliberate offset for
-   waterlines, embedded objects, or airborne models.
-4. Confirm directional facing once in the running app, as the `apply-conventions` skill describes.
-   PlayCanvas entities face -Z while glTF convention is +Z, but asset packs vary.
-5. Retain `boundsSource`, `aabb`, `dims`, `center`, `groundOffset`, and the intended size with
-   `{ scale, y, yaw }`. Use the scaled footprint and centre for initial spacing; do not re-derive or
-   add per-instance nudges.
+Nest three levels so a root position means the same for every asset: the semantic root, a yaw
+wrapper, then the visual child with the scale and local position
+`(-center.x * scale, y, -center.z * scale)`. Apply calibration once, never per instance.
 
-Keep gameplay position and heading on an outer semantic root, and seat the model on one predictable
-reference point beneath it so a root position means the same thing for every asset: by default the
-footprint centre over the base. Apply the authored yaw on a wrapper, then the scale and the full
-offset on the render child inside it, so an off-centre pivot is compensated in the authored frame and
-never re-rotated by the yaw or by gameplay heading:
+Place the root on a measured support point, such as a mount point or raycast, not a global AABB
+maximum. Skinned bounds are bind-pose estimates; confirm contact in animated poses.
 
-```ts
-const yaw = new Entity('yaw');
-yaw.setLocalEulerAngles(0, t.yaw, 0);
-const visual = instantiate(asset);
-visual.setLocalScale(t.scale, t.scale, t.scale);
-visual.setLocalPosition(-t.center[0] * t.scale, t.y, -t.center[2] * t.scale);
-yaw.addChild(visual);
-root.addChild(yaw);
-```
-
-Keep `y` as the local correction that brings the measured minimum to the root plane; the X and Z
-terms bring the footprint centre onto the root axis. Place that root at a measured support point. A support name or global AABB maximum is not
-a surface measurement. Use an authored mount point or runtime support query for curved or stepped
-geometry. Treat skinned bounds as bind-pose estimates and confirm foot contact in the active poses.
-
-Read exactly one reference matching the code being edited:
-[direct Engine](references/direct-engine.md), [React](references/react.md), or
-[Web Components](references/web-components.md). Choose from imports and markup, not installed
-dependencies alone.
+Read only the reference matching the code: [direct Engine](references/direct-engine.md),
+[React](references/react.md), or [Web Components](references/web-components.md).

package/skills/calibrate-model/references/web-components.md

@@ -4,12 +4,12 @@ Keep gameplay placement on the outer entity and calibration on a visual child:
 
 ```html
 <pc-app>
-    <pc-asset id="ship" src="/models/ship.glb"></pc-asset>
+    <pc-asset id="model" src="/models/model.glb"></pc-asset>
     <pc-scene>
-        <pc-entity name="Ship" position="12 0 -4" rotation="0 90 0">
+        <pc-entity name="Model" position="12 0 -4" rotation="0 90 0">
             <pc-entity rotation="0 180 0">
                 <pc-entity position="-0.45 1.2 0.225" scale="0.9 0.9 0.9">
-                    <pc-model asset="ship"></pc-model>
+                    <pc-model asset="model"></pc-model>
                 </pc-entity>
             </pc-entity>
         </pc-entity>

package/skills/configure-animation/SKILL.md

@@ -1,50 +1,34 @@
 ---
 name: configure-animation
-description: Use before playing, blending, or retargeting GLB animation clips in PlayCanvas Engine, React, or Web Components to inspect clip and joint names, attach animation to the rendered hierarchy, keep blend inputs valid, and diagnose T-pose, frozen playback, or binding failures.
+description: Use before playing, blending, or retargeting GLB animation clips in PlayCanvas, or when diagnosing T-pose, frozen playback, or binding failures.
 ---
 
 # Animation setup
 
-Use the `inspect-glb` skill first. Never guess clip or joint names.
+Get clip and joint names from `inspect-glb`; never guess them.
 
-## Choose the smallest playback model
-
-- Use the selected authoring surface's simple playback path for a single clip.
-- Use an `AnimStateGraph` for locomotion blending, transitions, or event-driven actions.
-- Adapt the official animation examples with the `find-examples` skill instead of writing a state
-  graph from memory.
-
-## Keep blend inputs valid
-
-Clamp every 1D blend parameter to the first and last child points before updating it. PlayCanvas
-does not clamp values outside that span: every child can receive zero weight and synchronized clips
-can receive non-finite speeds, freezing the pose. Exercise the first, interior, and last blend
-points with real gameplay input.
-
-## Retarget only compatible rigs
-
-For each source `animationTargets` entry, remove its final `.translation`, `.rotation`, `.scale`, or
-`.weights` suffix and match the remaining path against the destination's `nodePaths`. The top-level
-model root may differ; the remaining parent chain must match. Equal joint counts or similar bone
-names are insufficient. Confirm the result in the running app as the `apply-conventions` skill
-describes; frozen, partial, or exploded motion means the rigs are incompatible.
+- For one clip, use the surface's simple playback path. For blending, transitions, or events, adapt
+  an `AnimStateGraph` from an official animation example with `find-examples`.
+- Put the `anim` component on or above the rendered skinned hierarchy, not on a separate pivot.
+- Clamp every 1D blend parameter to its first and last child points. The Engine does not; values
+  outside the span zero every weight and can make synced speeds non-finite, freezing the pose.
+- Retarget only when each source `animationTargets` path, minus its `.translation`, `.rotation`,
+  `.scale`, or `.weights` suffix, matches a destination `nodePaths` entry below the model root.
+  Equal joint counts or similar names are not enough.
+- Scale a wrapper, never skinned bones.
 
 ## Prove playback
 
-An assigned clip, active state, or advancing state time does not prove that the skeleton is moving.
-For clips expected to move, sample the local position or rotation of two non-root joints over
-several rendered frames. Require a finite animation speed, active-state time, and progress, and
-confirm pose changes at idle and at both ends of each blend tree. Zero joint motion indicates a
-binding, playback, or blend-weight failure even when reported state names look correct.
+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
+binding, playback, or blend-weight failure.
 
-## Diagnose failures
+## Diagnose
 
-- A T-pose usually means no clip was assigned, target paths differ, or animation is attached outside
-  the rendered hierarchy.
-- Put scale on a model wrapper, not skinned bones.
-- Match playback rate to real movement speed when visible foot sliding matters.
+- T-pose: no clip assigned, target paths differ, or the anim component sits outside the rendered
+  hierarchy.
+- Frozen pose: an unclamped blend input or a non-finite speed.
+- Partial or exploded motion: incompatible rigs.
 
-Read exactly one reference matching the code being edited:
-[direct Engine](references/direct-engine.md), [React](references/react.md), or
-[Web Components](references/web-components.md). Choose from imports and markup, not installed
-dependencies alone.
+Read only the reference matching the code: [direct Engine](references/direct-engine.md),
+[React](references/react.md), or [Web Components](references/web-components.md).

package/skills/configure-animation/references/direct-engine.md

@@ -21,10 +21,10 @@ Place the anim component on or above the complete skinned render hierarchy befor
 Attaching it to an unrelated pivot does not bind the clip.
 
 Clamp 1D state-graph parameters to their authored child range. For children at `0.5`, `3.5`, and
-`8`, do not pass an unclamped movement speed:
+`8`, do not pass an unclamped value:
 
 ```ts
-entity.anim?.setFloat('locomotion', Math.max(0.5, Math.min(8, speed)));
+entity.anim?.setFloat('blend', Math.max(0.5, Math.min(8, value)));
 ```
 
 After assignment, drive the real gameplay inputs through the range and sample expected moving

package/skills/configure-animation/references/react.md

@@ -7,13 +7,13 @@ import { Entity } from '@playcanvas/react';
 import { Anim, Render } from '@playcanvas/react/components';
 import { useModel } from '@playcanvas/react/hooks';
 
-const Character = () => {
-    const { asset, error } = useModel('/models/Character.glb');
+const Model = () => {
+    const { asset, error } = useModel('/models/model.glb');
     if (error) throw new Error(error);
     if (!asset) return null;
 
     return (
-        <Entity name="Character">
+        <Entity name="Model">
             <Render type="asset" asset={asset} />
             <Anim asset={asset} activate />
         </Entity>

package/skills/find-examples/SKILL.md

@@ -1,79 +1,43 @@
 ---
 name: find-examples
-description: Use when implementing an unfamiliar PlayCanvas feature such as animation, particles, shaders, physics, UI, splats, or XR to find the official Engine, React, or Web Components example matching the installed package version and adapt it to the project.
+description: Use when implementing a PlayCanvas feature the project does not use yet, to find and adapt the official example matching the installed version.
 ---
 
 # Official examples
 
-Use official examples as version-matched recipes. Engine and Web Components examples are standalone
-applications to adapt, not modules to import.
+Examples are version-matched recipes to adapt, not modules to import. When the Engine ships a script
+for the behaviour, use `reuse-scripts` first.
 
-Use the `reuse-scripts` skill instead when the installed Engine ships a production script for the
-required behavior.
+## Find the example
 
-## Find the matching example
-
-When `node_modules/playcanvas` is a local source checkout or linked build — a symlink, a workspace,
-or a path dependency — its `examples/src/examples/**` are already on disk. Read them directly and
-skip the GitHub fetch below. A linked engine can sit ahead of any published tag, and a pre-release
-version (`-alpha`, `-beta`) may have no matching public tree, so the on-disk source is the ground
-truth. Fall back to GitHub only when the examples are absent locally; the published npm package
-omits `examples/`.
-
-```sh
-ls node_modules/playcanvas/examples/src/examples 2>/dev/null && echo "linked engine: read local examples, skip the fetch"
-```
-
-Search the active surface's own catalog first, then the Engine catalog. Engine examples are the
-largest set and port to every surface; the per-surface catalogs are smaller but need no translation.
-
-| Surface | Repository | Package | Ref | Example paths |
-| --- | --- | --- | --- | --- |
-| direct Engine | `playcanvas/engine` | `playcanvas` | `v<version>` | `examples/src/examples/<category>/<name>.example.mjs` |
-| Web Components | `playcanvas/web-components` | `@playcanvas/web-components` | `v<version>` | `examples/<name>.html` |
-| React | `playcanvas/developer-site` | `@playcanvas/react` | `main` | `docs/user-manual/react/examples/<name>.mdx` |
-
-Resolve the installed version instead of assuming the newest API:
-
-```sh
-PKG=playcanvas # or @playcanvas/web-components
-TAG="v$(node -p "JSON.parse(require('fs').readFileSync('node_modules/$PKG/package.json')).version")" || exit 1
-gh api "repos/playcanvas/engine/git/trees/$TAG?recursive=1" \
-  | grep -o '"examples/src/examples/[^"]*\.example\.mjs"'
-```
-
-Read the resolved package rather than the dependency list; `playcanvas` is often a transitive
-dependency of `@playcanvas/react` or `@playcanvas/web-components`. Stop on a failed read instead of
-requesting an invalid tag: an unresolved version produces an empty example list, not an error. When
-the package is not below the project root's `node_modules`, run the command from the workspace that
-depends on it.
-
-List a different surface by substituting its repository and path pattern, such as
-`'"examples/[^"]*\.html"'` for Web Components. Fetch a candidate from the same ref:
+If `node_modules/playcanvas/examples/src/examples` exists, it is a linked or source checkout: read
+it locally. The npm package omits `examples/`, so otherwise fetch from the installed tag:
 
 ```sh
+TAG="v$(node -p "JSON.parse(require('fs').readFileSync('node_modules/playcanvas/package.json')).version")" || exit 1
+gh api "repos/playcanvas/engine/git/trees/$TAG?recursive=1" | grep -o '"examples/src/examples/[^"]*\.example\.mjs"'
 gh api "repos/playcanvas/engine/contents/examples/src/examples/<category>/<name>.example.mjs?ref=$TAG" \
   --jq .content | base64 --decode
 ```
 
-Use `main` only when the installed version has no tag. It may contain unsupported APIs. Example
-asset URLs refer to `examples/assets/`; fetch assets from the same ref or substitute project assets.
+Read the resolved package, not the dependency list; `playcanvas` is often transitive. An empty list
+means an invalid tag: stop rather than guess. Use `main` only when the version has no tag.
 
-The React catalog is documentation rather than a tagged release: it is small, tracks the latest
-package, and its snippets are page fragments. Verify every prop and hook it uses against the
-installed `@playcanvas/react` declarations, and port an Engine example when no React example covers
-the feature.
+| Surface | Repository | Ref | Example paths |
+| --- | --- | --- | --- |
+| direct Engine | `playcanvas/engine` | `v<version>` | `examples/src/examples/<category>/<name>.example.mjs` |
+| Web Components | `playcanvas/web-components` | `v<version>` | `examples/<name>.html` |
+| React | `playcanvas/developer-site` | `main` | `docs/user-manual/react/examples/<name>.mdx` |
 
-## Adapt the recipe
+Search the surface's catalog first, then the Engine's. React pages track the latest package; verify
+each prop against the installed declarations. Fetch example assets, including the Draco, Basis, and
+Ammo decoders under `examples/assets/wasm`, from the same ref.
 
-Keep component options, scene construction, materials, shaders, assets, and update logic. Drop the
-example browser's controls and context imports.
+## Adapt it
 
-When one example integrates several required systems, reproduce that integration as one baseline
-before splitting or customizing it. Copying one script's parameters while omitting its layers,
-depth map, camera frame, sky, or assets is not an adaptation of the example.
+Keep component options, scene setup, materials, shaders, assets, and update logic; drop the example
+browser's controls and imports. When one example joins several systems, such as layers, depth,
+camera frame, and sky, get that baseline rendering before customizing it.
 
-Read exactly one reference matching the code being edited:
-[direct Engine](references/direct-engine.md), [React](references/react.md), or
-[Web Components](references/web-components.md). Choose from imports and markup, not installed
-dependencies alone.
+Read only the reference matching the code: [direct Engine](references/direct-engine.md),
+[React](references/react.md), or [Web Components](references/web-components.md).