create-playcanvas 0.3.0 → 0.5.0

package/skills/assemble-scene/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: assemble-scene
+description: Use when composing PlayCanvas Engine, React, or Web Components gameplay entities, model hierarchies, colliders, or physics objects to create one semantic root per object with calibrated visuals and predictable lifecycle ownership.
+---
+
+# Scene assembly
+
+Represent one gameplay object with one named semantic root. Put gameplay position, heading,
+rigid-body, collision, and behavior on that root. Put calibrated render transforms below it.
+
+Consume the existing tuning record from `calibrate-model` exactly once. If it is missing, stop and
+calibrate the model; do not calculate or adjust asset tuning during assembly.
+
+## Assembly rules
+
+- Name roots by gameplay role and use predictable names for repeated instances.
+- Apply model calibration once inside the visual child; never reapply scale, grounding, or authored
+  yaw during placement.
+- Space neighbouring roots by their scaled footprints and pivot offsets from `calibrate-model`, not
+  by pivot position. A non-90° authored yaw rotates a footprint, so reserve its larger horizontal
+  extent as a conservative radius.
+- Put rigid-body and collision components on the same root. Size colliders from measured bounds.
+- Use local transforms below a parent and world transforms only for semantic roots.
+- Keep UI, effects, cameras, and lights outside gameplay model hierarchies.
+- Remove the root through its authoring surface's lifecycle. Unregister external events it owns.
+- Do not scale rigid-body roots or skinned bones.
+
+## Prove placement
+
+Declare intentional support, attachment, or containment relationships between roots. After a
+rendered frame, measure each relationship at the supported object's actual position. Use a mount
+point, collision ray, or geometry sample; use a support root's AABB maximum only when its top is flat
+across the full footprint. Record the signed contact gap: positive means floating and negative means
+penetration. A relationship name does not exempt the pair from this check.
+
+Union descendant world `meshInstance.aabb` values for each semantic root and compare unrelated peer
+roots. Any intersection with positive depth on X, Y, and Z beyond a small tolerance is an unresolved
+placement failure: move the root from its calibrated footprint, or prove the apparent AABB overlap
+is empty geometry from at least two materially different views. Never accept one model inside
+another from a single screenshot.
+
+Also check expected root counts, component descendants, aligned render and collider bounds, and
+role-based names. Compare final dimensions with each calibration record's intended size and reference
+object. Inspect composition and facing from images returned into your context by an image-capable
+browser tool. A saved screenshot path, screen coordinate, AABB, or visibility flag is not visual
+evidence. If you cannot inspect the image, report those claims unverified. Hierarchy and placement
+claims require runtime values logged from the application itself, as the `apply-conventions` skill
+describes.
+
+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.

package/skills/assemble-scene/references/direct-engine.md

@@ -0,0 +1,16 @@
+# Direct Engine projects
+
+Create one root and place a previously calibrated model beneath it:
+
+```ts
+import { Entity } from 'playcanvas';
+
+const root = new Entity('Enemy_1');
+root.addChild(instance('enemy'));
+root.setPosition(x, 0, z);
+root.setEulerAngles(0, heading, 0);
+app.root.addChild(root);
+```
+
+Add physics and scripts to `root`, not the calibrated child. Move, rotate, enable, disable, and
+destroy the root as one gameplay object.

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

@@ -0,0 +1,24 @@
+# React projects
+
+Represent the complete gameplay object as one component:
+
+```tsx
+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]}>
+        <RigidBody type="dynamic" mass={1} />
+        <Collision type="capsule" />
+        <Model id="enemy" src="/models/Enemy.glb" />
+    </Entity>
+);
+```
+
+Use stable React keys when mapping repeated objects. Mount and unmount the component root to own the
+whole Engine hierarchy; do not manually destroy entities created by JSX.
+
+Before using physics, set `usePhysics` on `<Application>` and install the `sync-ammo` peer
+dependency. Missing either one leaves `RigidBody` and `Collision` inert with only a console warning,
+so confirm bodies actually move rather than assuming the markup took effect.

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

@@ -0,0 +1,19 @@
+# Web Components projects
+
+Represent the whole gameplay object below one semantic root:
+
+```html
+<pc-entity name="Enemy_1" position="4 0 -3" rotation="0 90 0">
+    <pc-rigidbody type="dynamic" mass="1"></pc-rigidbody>
+    <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-entity>
+</pc-entity>
+```
+
+Keep component tags as direct children of the owning `<pc-entity>`. Register the model with a
+direct-child `<pc-asset>` under `<pc-app>`. Before using rigid bodies, load Ammo with a direct-child
+`<pc-module name="Ammo">` carrying its `glue`, `wasm`, and `fallback` attributes; `<pc-app>` awaits
+its direct-child modules before creating the graphics device, so every body in the document depends
+on that one element. Add and remove the semantic root as one DOM subtree.

package/skills/build-app/SKILL.md

@@ -0,0 +1,41 @@
+---
+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.
+---
+
+# 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 [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.
+
+Installed dependencies alone are insufficient when a project contains more than one surface.
+Preserve the surface that owns the current entry point and lifecycle.
+
+## Render at an intentional density
+
+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.
+
+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.
+
+For every surface:
+
+- 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.

package/skills/build-app/references/direct-engine.md

@@ -0,0 +1,12 @@
+# Direct Engine applications
+
+Keep the project's existing `Application` or `AppBase` bootstrap, graphics-device setup, component
+systems, resource handlers, resize behavior, and teardown. Do not introduce a wrapper lifecycle
+around an established direct Engine application.
+
+Use named imports from `playcanvas`. Let the application own the root hierarchy, asset registry,
+update loop, canvas resizing, and destruction. Register loaded assets before attaching them to
+components, and unregister external events when their owning entity or application is destroyed.
+
+Put reusable per-entity behavior in an Engine `Script`. Use application update events for small
+application-level loops, and remove each callback during teardown.

package/skills/build-app/references/react.md

@@ -0,0 +1,20 @@
+# React applications
+
+Let React own application, asset, entity, and component lifecycles. Use `<Application>`, `<Entity>`,
+exports from `@playcanvas/react/components`, and installed asset hooks instead of creating matching
+Engine objects manually.
+
+Respect the subpath split, which is the most common import error: `Application`, `Entity`, and
+`Container` come from the package root, components from `@playcanvas/react/components`, and hooks
+from `@playcanvas/react/hooks`. The package is ESM only.
+
+Keep hooks unconditional and asset URLs stable. Mount and unmount JSX to create and destroy the
+owned Engine hierarchy; do not manually destroy entities created by React. Clean up imperative
+resources in the effect that created them.
+
+Use `useApp()` or refs only when no declarative component covers the Engine API. Put per-frame work
+in an Engine `Script` or `useAppEvent('update', cb)` instead of React state. Keep `Script` classes at
+module scope so renders do not create new constructor identities.
+
+Verify components, hooks, props, and required peer dependencies against the installed
+`@playcanvas/react` declarations before using them.

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

@@ -0,0 +1,55 @@
+# Web Components applications
+
+Install `playcanvas` and `@playcanvas/web-components`, register the component module, and map both
+module specifiers when using import maps. Pin package versions in production CDN URLs; do not use
+`@latest`.
+
+```html
+<script type="importmap">
+    {
+        "imports": {
+            "playcanvas": "/node_modules/playcanvas/build/playcanvas.mjs",
+            "@playcanvas/web-components": "/node_modules/@playcanvas/web-components/dist/pwc.mjs"
+        }
+    }
+</script>
+<script type="module" src="/node_modules/@playcanvas/web-components/dist/pwc.mjs"></script>
+```
+
+Build supported application structure declaratively:
+
+```html
+<pc-app>
+    <pc-asset id="ship" src="/models/ship.glb"></pc-asset>
+    <pc-scene>
+        <pc-entity name="Ship" position="0 0 -4">
+            <pc-model asset="ship"></pc-model>
+        </pc-entity>
+    </pc-scene>
+</pc-app>
+```
+
+- Put assets directly below `<pc-app>` and component elements directly below their `<pc-entity>`.
+- Give every `pc-*` element an explicit closing tag; self-closing syntax is unsupported.
+- Write vectors as space-separated numbers, rotations in degrees, and enums by name.
+- Treat a present boolean attribute as true unless its value is `false`; remove it to restore the
+  Engine default.
+
+Load Engine `Script` modules with `<pc-asset>`, then attach them through `<pc-scripts>` and
+`<pc-script>`. Match the element's `name` to the class's static `scriptName`. Extra kebab-case
+attributes map to camelCase properties; use the `attributes` JSON attribute for nested or reserved
+values.
+
+Use `whenReady` for occasional page-level Engine access:
+
+```js
+import { whenReady } from '@playcanvas/web-components';
+
+const { app } = await whenReady('pc-app');
+```
+
+Use element properties such as `.app`, `.entity`, `.scene`, and `.component` only when no
+declarative element covers the API. Put per-entity and per-frame behavior in an Engine `Script`, not
+page glue.
+
+Verify elements and attributes against the installed `@playcanvas/web-components` declarations.

package/skills/build-hud/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: build-hud
+description: Use when building a PlayCanvas game's on-screen interface such as ready, pause, and victory overlays, menus, and live indicators like gauges, timers, or reload meters, so the interface is driven by game state, readable over the scene, and separate from the 3D hierarchy.
+---
+
+# Game interface
+
+A HUD is a view of game state, not a source of it. Render it from the current state each frame or on
+each transition; never store gameplay truth in the DOM or a UI element.
+
+## Choose the UI layer
+
+- Build the interface in the natural UI layer for the surface — a DOM or React overlay, or the
+  Engine `screen` and `element` UI — decided with the `build-app` skill. Keep it outside gameplay
+  model hierarchies, as `assemble-scene` requires.
+- For a screen-space Engine UI, adapt a user-interface example with `find-examples` rather than
+  guessing element anchoring, scaling, and font handling.
+
+## Drive from state
+
+- Map each overlay to a game state and each indicator to a snapshot field. A transition shows or
+  hides overlays; it does not duplicate the state the game already owns (see `manage-game-state`).
+- Anchor and scale elements to the viewport so the layout holds at the target resolution and on
+  resize. Verify at the acceptance resolution, not the default window size.
+- Keep copy minimal and legible over the scene: back text with a plate or shadow where the frame is
+  bright, and unify interface colour with the scene's grade from `light-scene`.
+
+## Prove it reflects state
+
+Drive real input through every transition and confirm with screenshots that the correct overlay
+shows and each indicator tracks the snapshot — a reload meter empties and refills, a timer advances,
+a menu appears only in its state. A saved filepath or a visibility flag is not visual evidence;
+inspect the returned pixels as the local agent guide requires.
+
+Choose the authoring surface with the `build-app` skill and build the interface through its own UI
+primitives before reaching into the Engine.

package/skills/calibrate-model/SKILL.md

@@ -0,0 +1,65 @@
+---
+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.
+---
+
+# 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:
+
+```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
+    }
+} as const;
+```
+
+## Calculate the record
+
+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.
+
+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:
+
+```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.

package/skills/calibrate-model/references/direct-engine.md

@@ -0,0 +1,22 @@
+# Direct Engine projects
+
+Return a calibrated pivot whose parent can be placed without knowing how the asset was authored:
+
+```ts
+import { Entity } from 'playcanvas';
+
+const instance = (name: keyof typeof ASSET_TUNING) => {
+    const t = ASSET_TUNING[name];
+    const model = containers[name].resource.instantiateRenderEntity({
+        castShadows: true
+    });
+    model.setLocalScale(t.scale, t.scale, t.scale);
+    model.setLocalPosition(0, t.y, 0);
+    model.setLocalEulerAngles(0, t.yaw, 0);
+    const root = new Entity(name);
+    root.addChild(model);
+    return root;
+};
+```
+
+Only position and rotate the returned root. Keep the calibration inside `instance()`.

package/skills/calibrate-model/references/react.md

@@ -0,0 +1,27 @@
+# React projects
+
+Keep semantic transforms on the outer entity and calibration on the rendered child:
+
+```tsx
+import { Entity } from '@playcanvas/react';
+import { Render } from '@playcanvas/react/components';
+import { useModel } from '@playcanvas/react/hooks';
+
+const Model = ({ id, src, heading = 0, position = [0, 0, 0] }) => {
+    const { asset, error } = useModel(src);
+    const t = ASSET_TUNING[id];
+    if (error) throw new Error(error);
+    if (!asset) return null;
+
+    return (
+        <Entity name={id} position={position} rotation={[0, heading, 0]}>
+            <Entity position={[0, t.y, 0]} rotation={[0, t.yaw, 0]} scale={[t.scale, t.scale, t.scale]}>
+                <Render type="asset" asset={asset} />
+            </Entity>
+        </Entity>
+    );
+};
+```
+
+Add project-specific prop types without changing the two-level transform structure. Keep hooks
+unconditional and asset URLs stable.

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

@@ -0,0 +1,19 @@
+# Web Components projects
+
+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-scene>
+        <pc-entity name="Ship" position="12 0 -4" rotation="0 90 0">
+            <pc-entity position="0 1.2 0" rotation="0 180 0" scale="0.9 0.9 0.9">
+                <pc-model asset="ship"></pc-model>
+            </pc-entity>
+        </pc-entity>
+    </pc-scene>
+</pc-app>
+```
+
+Generate repeated markup from one `{ scale, y, yaw }` record per asset. Keep all vector attributes
+space-separated and use degrees for rotations.

package/skills/configure-animation/SKILL.md

@@ -0,0 +1,50 @@
+---
+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.
+---
+
+# Animation setup
+
+Use the `inspect-glb` skill first. Never guess clip or joint names.
+
+## 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.
+
+## 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.
+
+## Diagnose failures
+
+- 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.
+
+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.

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

@@ -0,0 +1,32 @@
+# Direct Engine projects
+
+Use clips exposed by the loaded container resource and attach animation to the entity owning the
+render hierarchy:
+
+```ts
+import type { Asset, ContainerResource } from 'playcanvas';
+
+const res = container.resource as ContainerResource;
+const entity = res.instantiateRenderEntity();
+entity.addComponent('anim', { activate: true });
+const clip = (res.animations as Asset[]).find((asset) => asset.name.includes('Idle'));
+if (!clip) throw new Error(`no Idle clip; have ${res.animations.map((asset) => asset.name).join(', ')}`);
+entity.anim?.assignAnimation('Idle', clip.resource);
+```
+
+Fail at the missing clip instead of optional-chaining past it. A silent missing assignment appears
+later as a T-pose with little diagnostic context.
+
+Place the anim component on or above the complete skinned render hierarchy before it initializes.
+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:
+
+```ts
+entity.anim?.setFloat('locomotion', Math.max(0.5, Math.min(8, speed)));
+```
+
+After assignment, drive the real gameplay inputs through the range and sample expected moving
+joints across multiple update frames. Treat non-finite `activeStateCurrentTime`,
+`activeStateProgress`, or component speed as a playback failure.

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

@@ -0,0 +1,32 @@
+# React projects
+
+Let React own the asset and component lifecycle for simple playback:
+
+```tsx
+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');
+    if (error) throw new Error(error);
+    if (!asset) return null;
+
+    return (
+        <Entity name="Character">
+            <Render type="asset" asset={asset} />
+            <Anim asset={asset} activate />
+        </Entity>
+    );
+};
+```
+
+Use `Anim` only when inspection confirms the asset has one clip. It takes `asset` plus
+`AnimComponent` properties such as `speed`, `activate`, `playing`, `stateGraph`, and `targets`, and
+it has no way to name a clip. Published React examples show `clip="Walk" loop`; those props do not
+exist, so the component drops them with a development warning and plays the assigned track anyway.
+Verify props against the installed `@playcanvas/react` declarations rather than an example.
+
+Use a module-scoped Engine `Script` attached with `<Script>` for multiple clips, explicit selection,
+state graphs, transitions, or retargeting. Keep per-frame animation state in the Engine component or
+script rather than React state.

package/skills/configure-animation/references/web-components.md

@@ -0,0 +1,13 @@
+# Web Components projects
+
+`<pc-model>` already covers the simplest case without any script: when the loaded container has
+animations it adds an `anim` component and assigns `animations[0]` under the state name `animation`.
+It always takes the first clip and has no attribute for choosing another.
+
+There is no animation component beyond that. Put explicit clip selection, multiple clips, state
+graphs, and retargeting in a module-scoped Engine `Script`, load it with `<pc-asset>`, and attach it
+to the same `<pc-entity>` hierarchy as the rendered model using `<pc-scripts>` and `<pc-script>`.
+
+Pass clip names and simple configuration as `<pc-script>` attributes. Use its `attributes` JSON
+attribute for nested state-graph configuration. Keep scale on a visual child `<pc-entity>`, not on
+skinned bones, and confirm playback after `pc-app` is ready.

package/skills/find-examples/SKILL.md

@@ -0,0 +1,79 @@
+---
+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.
+---
+
+# Official examples
+
+Use official examples as version-matched recipes. Engine and Web Components examples are standalone
+applications to adapt, not modules to import.
+
+Use the `reuse-scripts` skill instead when the installed Engine ships a production script for the
+required behavior.
+
+## 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:
+
+```sh
+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.
+
+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.
+
+## Adapt the recipe
+
+Keep component options, scene construction, materials, shaders, assets, and update logic. Drop the
+example browser's controls and context imports.
+
+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.
+
+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.

package/skills/find-examples/references/direct-engine.md

@@ -0,0 +1,15 @@
+# Direct Engine projects
+
+Keep the project application's existing graphics-device, application, component-system, resource
+handler, resize, and teardown setup. Do not copy the example bootstrap over it.
+
+Port the useful setup into the existing application function:
+
+- create entities with named imports from `playcanvas`;
+- add only the component systems or resource handlers the feature requires;
+- register loaded assets with the existing asset registry;
+- attach per-frame work to the application update event or an Engine `Script`;
+- unregister external events when the application or owning entity is destroyed.
+
+Examples may use `Application`, `AppBase`, or helpers specific to the examples browser. Match the
+application class already used by the project.