create-playcanvas 0.4.0 → 0.5.1

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.

package/skills/find-examples/references/react.md

@@ -0,0 +1,17 @@
+# React projects
+
+Drop graphics-device, application, component-system, and resource-handler setup because
+`<Application>` owns it.
+
+- Express entities and components with `<Entity>` and exports from `@playcanvas/react/components`.
+- Load assets with hooks such as `useModel`, `useTexture`, and `useEnvAtlas` when available in the
+  installed package.
+- Attach Engine `Script` subclasses with React's `<Script script={Type} />`.
+- Put frame callbacks in a `Script` or `useAppEvent('update', cb)` instead of updating React state
+  every frame.
+- Use `useApp()` only when no declarative component covers the Engine API. Clean up resources in the
+  effect that created them.
+- Keep hooks unconditional and asset URLs stable.
+
+Verify component and hook names against the installed `@playcanvas/react` declarations before
+translating the example.

package/skills/find-examples/references/web-components.md

@@ -0,0 +1,17 @@
+# Web Components projects
+
+A `playcanvas/web-components` example needs no translation: it is already a `pc-*` document, so copy
+its markup and adjust asset paths and attributes.
+
+Translating an Engine example instead, keep its feature options, assets, materials, shaders, and
+update logic. Drop its graphics device and application bootstrap because `<pc-app>` owns them.
+
+- Express supported entities and components with `pc-*` elements.
+- Register assets as direct children of `<pc-app>` with `<pc-asset>`.
+- Put per-entity behavior in an Engine `Script` loaded through `<pc-asset>` and attached with
+  `<pc-scripts>` and `<pc-script>`.
+- Use `whenReady` for page-level glue or Engine APIs with no declarative element.
+- Fetch example assets from the same Engine tag as the source example.
+
+Verify element and attribute names against the installed `@playcanvas/web-components` package. Do
+not translate an unsupported Engine component into a guessed custom element.

package/skills/inspect-glb/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: inspect-glb
+description: Use before loading, placing, scaling, or animating GLB assets in PlayCanvas to measure bounds, grounding offset, clips, joints, and hierarchy offline with the bundled zero-dependency inspector.
+---
+
+# Inspect GLBs
+
+Resolve `scripts/inspect.mjs` relative to this skill directory and run it before choosing entity
+transforms or animation names:
+
+```sh
+node <skill-directory>/scripts/inspect.mjs public/models/Character.glb
+node <skill-directory>/scripts/inspect.mjs public/models/{Ship,Enemy}_*.glb
+```
+
+The output provides:
+
+- `dims` for calculating a uniform scale;
+- `groundOffset` for the model wrapper's local Y position;
+- `center` for the pivot offset from the geometry centre: a non-zero X or Z means the root's
+  position is not where the model appears, and Y feeds grounding;
+- `boundsSource` for proving how precisely the bounds were measured;
+- `nodePaths`, `clips`, `joints`, and `animationTargets` for animation setup and rig comparison;
+- `skinned` to flag bind-pose bounds that need runtime confirmation.
+
+## Bounds precision
+
+`aabb`, `dims`, `center`, and `groundOffset` are decoded from actual vertex positions and transformed
+by each node's world matrix, so they are exact and can place meshes touching without a gap. Confirm
+`boundsSource` before relying on that precision:
+
+- `vertices` means every primitive was decoded and the bounds are exact.
+- `accessor-minmax` means at least one primitive could not be decoded, so its bounds fall back to the
+  node-transformed local box. That over-estimates a mesh which does not fill its own box on a node
+  rotated off-axis, by up to 41 percent for a 45-degree yaw. `boundsNotes` gives the cause.
+
+Carry `boundsSource`, `aabb`, `dims`, `center`, and `groundOffset` into the asset tuning record.
+`groundOffset` seats the base in Y; `center.x` and `center.z` are the horizontal pivot offset that
+`calibrate-model` must compensate, so a placed root sits where the mesh appears, not where the
+authored pivot happens to be. Running the inspector alone is not placement evidence. Its global AABB supports plane grounding and
+broad-phase spacing, but cannot locate a non-planar support surface or attachment point. Use an
+authored mount point or confirm the support in the running application before placing another model.
+
+## Extract from any container with gltf-transform
+
+The bundled inspector decodes plain vertex buffers only. When a primitive is draco- or
+meshopt-compressed, sparse, or in an external buffer it falls back to `accessor-minmax` or reports
+nothing, and `boundsNotes` names the cause. Use gltf-transform as the precursor that normalizes any
+container into a plain GLB the inspector can then measure exactly. Decompress a scratch copy with the
+passes that would alter geometry or hierarchy disabled, and inspect the copy rather than shipping it:
+
+```sh
+npx @gltf-transform/cli optimize in.glb scratch.glb \
+  --compress false --simplify false --flatten false --join false
+node <skill-directory>/scripts/inspect.mjs scratch.glb
+```
+
+The Engine has no `EXT_meshopt_compression` support, so a meshopt asset will not render as shipped.
+If it must appear in the scene, transcode it to an uncompressed GLB the same way — subject to the
+project's rules on modifying assets — so it both loads and measures.
+
+These exact bounds intentionally disagree with the Engine at runtime. `MeshInstance.aabb` transforms
+the mesh's declared local box, so for a node rotated off-axis it reads larger than the geometry
+really is. Treat that difference as expected and place from these bounds. A skinned mesh node's own
+transform is ignored here because glTF requires it; the Engine resolves to the same result.
+
+Shortlist files first; do not dump an entire asset pack into context. Bounds cannot prove facing.
+glTF convention is +Z forward while PlayCanvas entities face -Z, and asset packs vary. Confirm each
+directional model once in the running app as the `apply-conventions` skill describes, and store its
+yaw correction with its scale and grounding.
+
+Use `npx @gltf-transform/cli inspect` only when vertex or texture statistics justify extra tooling.