create-playcanvas 0.8.1 → 0.9.0

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).

package/skills/inspect-glb/SKILL.md

@@ -1,81 +1,40 @@
 ---
 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.
+description: Use before loading, placing, scaling, or animating GLB models in PlayCanvas to measure bounds, grounding, clips, joints, and hierarchy with the bundled offline inspector.
 ---
 
 # Inspect GLBs
 
-Resolve `scripts/inspect.mjs` relative to this skill directory and run it before choosing entity
-transforms or animation names:
+Resolve `scripts/inspect.mjs` relative to this skill and run it before choosing transforms or
+animation names. Shortlist files; do not dump a whole asset pack into context.
 
 ```sh
-node <skill-directory>/scripts/inspect.mjs public/models/Character.glb
-node <skill-directory>/scripts/inspect.mjs public/models/{Ship,Enemy}_*.glb
+node <skill-directory>/scripts/inspect.mjs public/models/*.glb
 ```
 
-The output provides:
+## Read the output
 
-- `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` and `boundsPose` for proving how and at which pose the bounds were measured;
-- `requiresRuntimeCheck` for animated morphs, skins, and incomplete decoding;
-- `nodePaths`, `clips`, `joints`, and `animationTargets` for animation setup and rig comparison;
-- `morphed`, `morphAnimated`, and `skinned` for pose-sensitive assets.
+- `dims`, `center`, and `groundOffset` give the uniform scale input, the pivot offset, and the Y
+  seat. Non-zero `center.x` or `center.z` means the model does not sit on its root.
+- `boundsSource`: trust bounds for placement only when it is `vertices`. `accessor-minmax` can
+  over-estimate rotated nodes by up to 41 percent; `incomplete` or `null` means do not calibrate.
+  `boundsNotes` gives the cause.
+- `boundsPose`: `static` and `default-morph` are the authored pose; `bind` is the skinned rest pose.
+- `requiresRuntimeCheck` flags morphs, skins, or partial decoding; confirm extents in the app.
+- `nodePaths`, `clips`, `joints`, and `animationTargets` feed `configure-animation`.
 
-## Bounds precision
+Bounds cannot prove facing. Confirm it in the running app and record the yaw with
+`calibrate-model`. Runtime `meshInstance.aabb` expands conservatively for morphs, so place static
+models from inspected bounds.
 
-`aabb`, `dims`, `center`, and `groundOffset` are decoded from actual vertex positions, default morph
-weights, and each node's world matrix. Confirm both source and pose before relying on them:
+## Compressed files
 
-- `vertices` means every primitive was decoded and the bounds are exact for `boundsPose`.
-- `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.
-- `incomplete` means some visible default-pose geometry could not be measured; do not calibrate from
-  the reported bounds.
-- `null` means no usable bounds could be recovered.
-
-`static` and `default-morph` bounds describe visible geometry at its authored default pose. `bind`
-describes skinned vertices before animation. When `requiresRuntimeCheck` is true, confirm grounding
-and maximum animated extent in the running application even if `boundsSource` is `vertices`.
-
-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 compressed containers
-
-The bundled inspector decodes plain, interleaved, quantized, and sparse vertex buffers. For Draco,
-Meshopt, or external buffers, `boundsNotes` names the cause. Parse and rewrite a scratch copy with
-glTF Transform's lossless `copy` command, then inspect that copy rather than shipping it:
+The inspector decodes plain, interleaved, quantized, and sparse buffers. For Draco, Meshopt, or
+external buffers, inspect a lossless scratch copy; do not use `optimize`, which applies extra
+transforms:
 
 ```sh
 npx --yes @gltf-transform/cli@4.4.2 copy in.glb scratch.glb
-node <skill-directory>/scripts/inspect.mjs scratch.glb
 ```
 
-`copy` preserves decoded vertex values, scenes, nodes, and materials while removing Draco and
-Meshopt compression. Existing lossy compression may already have quantized the source. Do not
-substitute `optimize`: it enables additional transforms unless each one is understood and disabled.
-
-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 geometry-fit bounds can intentionally disagree with the Engine's runtime culling AABB.
-`MeshInstance.aabb` transforms the declared local box and expands it conservatively for morph
-targets, so it can be larger than visible geometry. Place static models from exact inspected bounds;
-confirm morph and skin extremes at runtime. 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.
+The Engine cannot load `EXT_meshopt_compression`; see `load-assets` before shipping such files.

package/skills/light-scene/SKILL.md

@@ -1,109 +1,41 @@
 ---
 name: light-scene
-description: Use when a PlayCanvas scene must read as a deliberate image rather than a flat asset preview — photoreal and cinematic, or stylized, low-poly, and palette-driven — to set key and ambient lighting, sky and image-based lighting, shadows, tone mapping and exposure, water, and a restrained post-process grade of bloom, fog, and colour.
+description: Use when lighting or rendering a PlayCanvas scene, covering lights, ambient and environment lighting, sky, shadows, tone mapping, exposure, fog, and post-processing.
 ---
 
-# Cinematic rendering
+# Light and render a scene
 
-A polished frame is lit and graded, not just populated. Treat lighting, sky, shadows, tone mapping,
-and post as one pass over the assembled scene, and tune every value against a real screenshot rather
-than from memory.
+Engine defaults give a flat, dark image; change them deliberately. Tune against inspected
+screenshots, one class of value at a time.
 
-## Confirm art direction before implementation
+## Defaults to change
 
-Follow the user's specified or approved direction. When it is unresolved, present concrete options
-using references, mockups, or inexpensive rendered variants and get approval before substantial
-implementation. Prefer a side-by-side variant sheet when cheap to produce. Work within the approved
-direction and confirm significant departures before implementing them.
+- `scene.ambientLight` is black, so unlit sides render pure black. Light ambient and reflections
+  from an environment atlas or skybox, or set an ambient colour.
+- Cameras default to `TONEMAP_LINEAR`. Choose `TONEMAP_NEUTRAL`, `TONEMAP_ACES2`, or
+  `TONEMAP_FILMIC` (on `cameraFrame.rendering.toneMapping` when using `CameraFrame`), set exposure,
+  then balance light intensities to it.
+- Shadows are off. Enable `castShadows` on the key light. Directional `shadowDistance` is 40 m, so
+  use cascades for large scenes, and `SHADOWUPDATE_THISFRAME` for static shadows. Size resolution to
+  the framed subject.
+- Lights shine along local -Y (`apply-conventions`).
 
-## Choose the path from the brief
+## Use what ships
 
-Read the reference before wiring any pipeline. A photoreal or cinematic brief takes the runtime HDR
-path below. A brief whose reference is low-poly, flat-shaded, toon, or palette-driven — or whose
-startup, frame, or payload budget rules out the runtime pipeline — takes the stylized path: banded
-or flat shading through `override-shader-chunks`, a solid or gradient sky, static lighting through
-`bake-lighting`, and no `Water` or `CameraFrame`. A remark such as "look at the water script" is a
-pointer to inspect it; confirm any resulting change of art direction before integration. On either
-path, dynamic objects and their attachments must sample or approximate the baked or ambient occlusion
-so they dim to the same levels as the surfaces around them, grounded with contact shadows.
+- `CameraFrame` handles tone mapping, bloom, SSAO, DOF, vignette, and grading. Call `update()` after
+  changes and destroy it with the app. Keep bloom intensity within the documented 0 to 0.1.
+- `scene.sky.type` (`SKYTYPE_DOME`, `SKYTYPE_BOX`, `SKYTYPE_INFINITE`) grounds an environment sky.
+- The `ProceduralSky` script owns a linked sun light: set the light's base intensity, then tune
+  elevation and azimuth on the sky, not the light.
+- The `ShadowCatcher` script grounds subjects that have no lit floor.
+- Clustered lighting is on by default, so many point and spot lights are cheap.
+- Bake static lights with `bake-lighting`; stylize shading with `override-shader-chunks`.
 
-## Runtime HDR path
+Find each integration's example with `find-examples`.
 
-Prefer shipped building blocks over hand-written shaders and passes. Discover them with the
-`reuse-scripts` skill and adapt the closest official example with `find-examples`:
+## Warning signs
 
-- the core `CameraFrame` helper for tone mapping, ambient occlusion, bloom, vignette, and grade;
-- a procedural sky and image-based light for ambient colour and reflections;
-- a shadow catcher for grounding subjects that have no lit floor.
-
-For an outdoor scene whose brief asks for reflective, photoreal water, stop before authoring the
-scene and read both `reuse-scripts` and `find-examples`. Use `graphics/water.example.mjs` as the
-initial composition recipe: it already joins the production `Water` script, sky, sun, `CameraFrame`,
-water layer, scene depth, and reflection pipeline. Get that complete frame rendering before
-replacing its assets or tuning its look; a custom normal-mapped material or tessellated plane is not
-that baseline.
-
-For that water scene, keep both production integrations visible in the implementation:
-
-- import and create `Water` from `playcanvas/scripts/esm/water.mjs` on the water entity, preserving
-  the example's required render component, camera reference, water layer, depth map, and textures;
-- construct `CameraFrame` from `playcanvas` for the gameplay camera, set a deliberate tone map and
-  restrained grade, call `update()`, and destroy it with the application.
-
-Do not continue to cosmetic tuning while a required integration is missing or diagnostics report
-a shader, texture, or framebuffer error.
-
-## Light and expose
-
-- Establish one dominant key light with a clear direction and warm or cool intent, then add soft
-  fill or ambient so shadows are not crushed to black. A single flat ambient with no key reads as an
-  asset gallery.
-- Choose a physically based tone mapping and a deliberate exposure, then balance light intensities to
-  that exposure, not the reverse.
-- Drive ambient and reflections from the sky or an environment map, not a constant colour, so
-  materials pick up their surroundings.
-- Tune the HDR stack in isolation before styling it. Begin with neutral tone mapping, scene exposure
-  `1`, procedural-sky luminance near its official-example value, bloom off, grading neutral, fog off,
-  and reflection/specular strengths at their defaults. Capture a screenshot, then change one class of
-  value at a time. Do not simultaneously raise key intensity, sky luminance, exposure, reflection,
-  saturation, fog brightness, and bloom.
-- Treat linked procedural skies as the owner of the sun light's direction, colour, and intensity.
-  Set the light's base intensity before assigning it to the sky and tune the sky elevation/azimuth;
-  do not also hand-author the light transform or colour as though they remained independent.
-- Preserve the source assets' albedo colours. If diffuse texture colours collapse toward white or a
-  single warm tint, reduce the HDR stack before compensating with darker material colours.
-
-## Shadow and ground
-
-- Enable shadows on the key light and size the shadow area and resolution to the framed subject, not
-  the whole world. Soften the penumbra rather than only raising resolution.
-- Ground subjects with a contact or catcher shadow when the surface beneath them is not itself lit.
-
-## Grade with restraint
-
-- Bloom, fog, vignette, and colour grade unify a frame; overdone bloom and heavy fog destroy
-  silhouette and depth. Start subtle and increase only against the screenshot. `CameraFrame` bloom
-  intensity is documented for the `0` to `0.1` range; stay inside it.
-- Match fog colour and density to the sky so the horizon stays coherent.
-- Preserve surface detail through the brightest reflection path. If glare clips a large part of the
-  frame to white or a reflection becomes an opaque black blob, rebalance exposure, light intensity,
-  reflection strength, and shadow bias before adding more post-processing.
-- Compare both the brightest surface and the shadow-facing side of the hero subject in the same
-  screenshot. Reject the grade if either broad highlight clipping or crushed-black silhouette hides
-  texture detail. A mechanically valid frame is not visually complete while either failure remains.
-
-## Prove the look
-
-For changes to an existing look, show old and new at the same pose in one image. If the difference
-is not visible, report that before spending more time tuning.
-
-Tune against pixels, not numbers. Capture the intended framing with an image-returning browser
-screenshot tool and inspect the returned image, as `apply-conventions` and the local agent guide
-require; a saved filepath is not evidence. Use two fixed poses, capture with a headless browser, and
-return images at accept-or-reject points only, not after every edit. Confirm the subject is exposed
-and readable, shadows are present but not crushed, and the grade is restrained, from the real
-gameplay camera at the target resolution. Confirm the post-process camera keeps rendering as it
-orbits and pitches.
-
-Choose the authoring surface with the `build-app` skill and set lights, camera, and scene settings
-through its own primitives before reaching into the Engine.
+- Albedo washing toward white: reduce exposure, sky, and light intensity before darkening
+  materials.
+- Large areas clipped white or crushed black: rebalance exposure and lights before adding post.
+- A fog colour that differs from the sky horizon breaks the horizon line.

package/skills/load-assets/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: load-assets
+description: Use when loading glTF/GLB models or textures in PlayCanvas, choosing Draco or Basis/KTX2 compression, or setting up decoders and preloading.
+---
+
+# Load assets
+
+## glTF is fully supported
+
+Load `.glb` files as `container` assets and call `asset.resource.instantiateRenderEntity()`, not
+`instantiateModelEntity`. The importer already handles `KHR_lights_punctual`, `KHR_materials_*`
+(clearcoat, sheen, transmission, volume, iridescence, variants, and more), `KHR_texture_transform`,
+and `EXT_mesh_gpu_instancing`; do not rebuild these by hand. Preload asset sets with
+`AssetListLoader`.
+
+## Compress for size
+
+- Geometry: Draco (`KHR_draco_mesh_compression`). Meshopt is not supported, so decode such files
+  before shipping.
+- Textures: KTX2 with Basis (`KHR_texture_basisu`) transcodes to a GPU format, cutting both
+  download size and VRAM. ETC1S is smallest and lossy. UASTC is larger and keeps
+  detail, which matters most for normal maps. Weigh size against visible detail.
+
+## Set up decoders
+
+The npm package ships no Draco or Basis wasm. Copy `draco/` and `basis/` from the Engine's
+`examples/assets/wasm` at the installed tag (`find-examples`), and configure them before loading:
+
+```js
+import { WasmModule, basisInitialize } from 'playcanvas';
+
+WasmModule.setConfig('DracoDecoderModule', {
+    glueUrl: '/wasm/draco/draco.wasm.js',
+    wasmUrl: '/wasm/draco/draco.wasm.wasm',
+    fallbackUrl: '/wasm/draco/draco.js'
+});
+await new Promise((resolve) => WasmModule.getInstance('DracoDecoderModule', resolve));
+basisInitialize({
+    glueUrl: '/wasm/basis/basis.wasm.js',
+    wasmUrl: '/wasm/basis/basis.wasm.wasm',
+    fallbackUrl: '/wasm/basis/basis.js'
+});
+```
+
+In Web Components, a `<pc-wasm name="DracoDecoderModule">` element under `<pc-app>` sets the Draco
+config with `glue`, `wasm`, and `fallback` attributes.
+
+## Other assets
+
+- Raise `texture.anisotropy`, which defaults to 1, for surfaces viewed at grazing angles.
+- Gaussian splats load as `gsplat` assets onto a `gsplat` component; start from a
+  `gaussian-splatting` example.