create-playcanvas 0.8.1 → 0.10.0

package/package.json

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

package/skills/add-effects/SKILL.md

@@ -1,92 +1,30 @@
 ---
 name: add-effects
-description: Use when adding transient visual effects or trails to a PlayCanvas app to select an Engine-native implementation, place and layer it correctly, manage its lifecycle, and verify the rendered result.
+description: Use when adding visual effects to a PlayCanvas app, to choose between particle systems, shader chunks, runtime meshes, and post-processing.
 ---
 
-# Effects and game feel
+# Effects
 
-Trigger transient effects through application events and reuse their resources.
+Pick the Engine building block first, then adapt its closest official example with
+`find-examples`:
 
-Reuse before authoring. Adapt the closest official particle example with `find-examples`, prefer the
-Engine's built-in particle component over a hand-written system, and discover any shipped trail or
-effect script with `reuse-scripts`.
+- Particle systems: the `particlesystem` component (`graphics/particles-*` examples).
+- Custom shading on existing surfaces: `StandardMaterial` chunk overrides
+  (`override-shader-chunks`), or a `ShaderMaterial` when the effect needs its own shader pair.
+- Procedural or per-frame geometry: a runtime-updated `Mesh` on a `render` component
+  (`graphics/mesh-*` examples), or `WideLineRenderer` for lines with width.
+- Full-screen effects: `CameraFrame` (`light-scene`).
+- Gaussian splat effects: the shipped gsplat scripts (`reuse-scripts`).
 
-Copy particle curve construction from the installed example exactly. `CurveSet` takes one key array
-per channel, such as `new CurveSet([0, x0, 1, x1], [0, y0, 1, y1], [0, z0, 1,
-z1])`; do not flatten three channels into one array. A malformed curve can type-check and then fail
-inside the particle texture upload. Create one emitter, render a frame, and require empty runtime
-and console diagnostics before reusing the helper for smoke, spray, or splashes.
+## Engine gotchas
 
-For a polished wake, smoke, or spray requirement, do not stop at scaled planes, crossed billboards,
-or generic render primitives. Use the built-in particle component for smoke and spray; reserve a
-custom mesh and material for a continuously sampled wake ribbon. Verify tint and blending against
-the actual scene lighting and surface.
+- `CurveSet` takes one key array per channel. A flattened array type-checks, then fails at texture
+  upload.
+- Create emitters and meshes at load and reuse them. Fire an emitter with `reset()` then `play()`;
+  one-shots use `loop: false`.
+- The first use of a shader stalls a frame. Render each effect once behind a loading screen.
+- Animate values with `setParameter`, not a per-frame `material.update()`.
+- A lit material on a custom mesh needs normals; otherwise use an unlit material.
 
-## Place and layer
-
-- Place an effect at the emitter's world mount point; parent it there or copy the world transform once.
-- Keep additive or transparent effects above the surface they sit on and biased toward the camera so
-  they do not z-fight. Inspect soft transparency at grazing angles for hard edges, black quads, or
-  dropout.
-- Size and orient effects from the emitter's calibrated bounds, not a guessed constant.
-
-## Pool and prewarm
-
-- Create emitters, ribbons, flashes, materials, and meshes at load. Events check out an effect, set
-  its transform, and call `particlesystem.reset()` then `play()`; after its particles finish, call
-  `stop()` and return it to the pool.
-- First-use shader compilation can stall a frame. Before gameplay, render every material and particle
-  variant through the relevant passes, on an offscreen rig or behind the ready overlay.
-- Pulse or tint uniforms with `meshInstance.setParameter` or `material.setParameter`.
-  `material.update()` marks the whole material dirty and clears variants when defines or chunks
-  change; reserve it for material changes that require it.
-
-## Moving trails
-
-- Treat built-in render primitives as blocking geometry for soft effects. Follow the closest
-  official example to choose particles, a custom mesh, textures, materials, and blending for the
-  intended visual behavior.
-- Match every custom mesh's vertex streams to its material. A lit `StandardMaterial` needs normals;
-  calculate and set them before `mesh.update()`, or deliberately use an unlit material. Treat a
-  missing vertex-attribute diagnostic as a rendering failure even when some frames still appear.
-  For a dynamic horizontal ribbon created with `setVertexStream`, allocate a normal array alongside
-  positions, fill every vertex with `(0, 1, 0)`, and upload it as `SEMANTIC_NORMAL` before the first
-  `update()`. Recheck this whenever changing the ribbon's material type.
-- Never attach an empty dynamic mesh to an enabled render component. Upload a valid initial vertex
-  and index set before creating its `MeshInstance`, or keep the render entity disabled until the
-  first complete update. On reset, disable it or restore valid seed geometry; do not call
-  `mesh.clear()` while an enabled renderer still references it. Reflection and refraction cameras
-  render the same mesh and can expose this lifecycle bug before the gameplay camera does.
-- Judge a trail from its intended cameras. If it reads as a flat decal, use the reference example to
-  add the minimum depth cue needed rather than stacking arbitrary geometry.
-- Sample the trail continuously. Append segments on a small time- or distance-step and interpolate
-  between them; coarse per-distance chunks make the trail stutter and break into visible dashes as
-  the object speeds up.
-- Anchor it to the mover's contact or exhaust point, scale emission rate and length with speed, and
-  fade the tail so it dissolves instead of cutting off with a hard edge.
-
-## Camera shake and hit feedback
-
-- Drive camera shake as a decaying offset on a camera parent or an additive layer; never write it
-  into the smoothed chase position, or it fights the follow. Keep shake and follow separate, as the
-  orbit-camera rule in `apply-conventions` requires.
-- Stagger the parts of a compound effect over a few frames — flash, then smoke, then splash — so an
-  event reads as a sequence rather than a single pop.
-- Keep the readable peak long enough for the gameplay camera to see the layers together. A flash can
-  be brief, but the longer-lived layers should overlap for several frames rather than leaving the
-  primary action frame visually identical to the idle state.
-- For side-mounted emitters, derive every spawn point and direction from calibrated world-space
-  mounts on the mover. Confirm the effect starts outside the source geometry from both sides; an
-  active cooldown with only a tiny flash elsewhere in the frame is failed feedback.
-
-## Prove it fires
-
-Trigger each effect through real gameplay input and confirm with a screenshot captured at its peak,
-not a saved filepath. Confirm the effect is visible from the gameplay camera and from a grazing
-angle, that repeated events leave entity counts stable, and that nothing leaves a black quad or a
-hard edge over the surface. Compare `graphicsDevice.shaders.length` after prewarming and after the
-first real event; growth indicates a missed variant. Use two fixed poses and return screenshots at
-accept-or-reject points only, not after every edit.
-
-Choose the authoring surface with the `build-app` skill; create effects through its entity and
-component primitives and own their lifecycle in the surface that spawned them.
+Trigger each effect through the app's real inputs, and confirm repeated triggers keep entity counts
+stable.

package/skills/apply-conventions/SKILL.md

@@ -1,75 +1,49 @@
 ---
 name: apply-conventions
-description: Use when writing or reviewing PlayCanvas Engine code involving entity transforms, cameras, physics, materials, model orientation, bounds, or imports to apply the Engine's coordinate and API conventions.
+description: Use when writing PlayCanvas Engine code touching transforms, cameras, lights, materials, meshes, bounds, or imports, to apply Engine conventions and avoid legacy APIs.
 ---
 
 # Engine conventions
 
-Read `package.json` and the installed `playcanvas` source before relying on version-sensitive API
-details. Apply these stable conventions throughout the project.
+Check version-sensitive APIs against installed `playcanvas` declarations.
 
-## Coordinates and angles
+## Coordinates
 
-- Use the right-handed coordinate system: +Y is up and the gameplay ground plane is XZ.
-- Treat `entity.forward` and the camera viewing direction as -Z; `entity.right` is +X and
-  `entity.up` is +Y. `lookAt` points -Z at the target.
-- Expect glTF models authored toward +Z to need a yaw correction. Inspect and calibrate each
-  directional model instead of applying one global correction.
-- Pass degrees in XYZ order to high-level angle APIs.
-- Keep pitch, yaw, and roll as application state. Do not repeatedly read `getEulerAngles()` and
-  feed its decomposition back into `setEulerAngles()`.
-- Interpolate periodic angles with `math.lerpAngle()` or rotations with `Quat.slerp()`, not scalar
-  lerp across the 0/360 seam.
+- Right-handed, +Y up, metres. `entity.forward`, cameras, and `lookAt` use -Z.
+- Directional and spot lights shine along local -Y, straight down by default. Aim them with
+  `setEulerAngles`, not `lookAt`.
+- glTF models usually face +Z; record per-model yaw with `calibrate-model`.
+- Angle APIs take degrees in XYZ order. Keep pitch, yaw, and roll as app state; never feed
+  `getEulerAngles()` back into `setEulerAngles()`. Interpolate with `math.lerpAngle` or
+  `Quat.slerp`.
+- Use world setters on semantic roots and `setLocal*` below a parent. Never scale rigid-body roots
+  or skinned bones.
 
-## Transforms and units
+## Current APIs
 
-- Use `setPosition`, `setRotation`, and `setEulerAngles` for world transforms.
-- Use the `setLocal*` variants below a parent.
-- Treat units as metres. Physics gravity defaults to `(0, -9.81, 0)`.
-- Keep gameplay transforms on a semantic root and asset-authoring corrections on a child.
-- Do not scale rigid-body roots or skinned bones.
+- `render` and `anim` components, not `model` and `animation`.
+- ESM `class X extends Script` with `static scriptName`, not `createScript`.
+- `Mesh.fromGeometry(device, new BoxGeometry())`, not `createBox` and the other `create*` helpers.
+- Named imports from `playcanvas`; shipped scripts only from `playcanvas/scripts/esm/**`.
 
-## Cameras, materials, and bounds
+## Cameras
 
-- Perspective camera FOV is vertical and defaults to 45 degrees.
-- Smooth an orbit camera's focus, yaw, pitch, and distance, then derive its position. Do not
-  `Vec3.lerp()` between orbit positions on opposite sides of the focus; the chord crosses the subject.
-- Before writing custom camera input, inspect the installed controller script and its matching
-  Engine example. Preserve their gesture mapping and damping unless the product explicitly asks
-  for different behavior; do not derive signs from memory.
-- Define the input contract in screen space, then verify positive and negative movement on both axes
-  with real input after a rendered frame. Judge the camera basis or a projected fixed landmark, not
-  world-space camera coordinates or internal angle signs; both can approve inverted behavior.
-- Materials cull back faces by default; counter-clockwise winding defines the front face.
-- Clone and reassign a shared material before editing it for only some meshes, including default
-  and asset-imported materials. Per-mesh uniforms use `meshInstance.setParameter()` without cloning.
-- `setParameter` uploads raw values; author colours in sRGB and convert with `Color#linear()`
-  before upload — do not hand-roll gamma.
-- Entities do not have an `aabb`. Union descendant `meshInstance.aabb` values after transforms have
-  synchronized.
-- Let `Mesh.update()` calculate local bounds. If passing `false` for `updateBoundingBox`, assign an
-  explicit `mesh.aabb` before the mesh can be culled.
-- Expand custom-mesh bounds by the maximum vertex-shader displacement; CPU bounds do not observe
-  shader deformation.
-- Treat offline skinned-mesh bounds as bind-pose estimates and confirm animated poses at runtime.
+- FOV is vertical, 45° by default. Check shipped camera scripts before writing controls
+  (`reuse-scripts`).
 
-## Imports
+## Materials and bounds
 
-Use named ESM imports from `playcanvas`. Import production scripts only from
-`playcanvas/scripts/esm/**`; legacy sibling script directories depend on a global Engine namespace.
+- `StandardMaterial.useMetalness` defaults to `false`; enable it before using `metalness`.
+- Call `material.update()` after property edits. Per-mesh values use `meshInstance.setParameter()`
+  with no update or clone.
+- Clone shared materials, including imported ones, before editing them for some meshes.
+- `setParameter` uploads raw values; convert sRGB colours with `Color#linear()`.
+- Back faces cull by default; counter-clockwise winding is the front face.
+- Entities have no `aabb`; union descendant `meshInstance.aabb`. If `mesh.update()` skips bounds,
+  set `mesh.aabb` yourself, and expand it by any vertex-shader displacement.
 
-## Runtime confirmation
+## Verify in the running app
 
-Offline measurements cannot prove facing, animated poses, or final placement. Confirm each one in the
-running application:
-
-- Start the project's own dev server or build; do not construct a separate harness.
-- Log the value from inside the Engine, using `getPosition()`, `getEulerAngles()`, a
-  `meshInstance.aabb`, or an anim component's active state, from a `Script` or an update callback.
-- For large or vertex-displaced meshes, inspect their runtime AABB and `visibleThisFrame` after a
-  rendered frame from at least two representative camera angles.
-- Confirm a directional model's visible front aligns with its semantic root's `forward`; a stored
-  yaw or runtime transform alone cannot prove mesh facing.
-- Read that logged value from the browser console. Screenshots judge composition and orientation;
-  numeric claims require logged values.
-- Record the confirmed value in application state or an asset tuning record, then remove the logging.
+Offline values cannot prove facing, poses, or placement. Read values from the running app with
+`inspect-runtime`, and judge visuals only from screenshots you have inspected. A saved file path is
+not evidence.

package/skills/assemble-scene/SKILL.md

@@ -1,53 +1,28 @@
 ---
 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.
+description: Use when composing PlayCanvas entity hierarchies from models, colliders, rigid bodies, and scripts, so each object has one semantic root and clear lifecycle.
 ---
 
 # 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.
+Each scene object has one named root. Put position, heading, `rigidbody`, `collision`, and
+scripts on the root, and the calibrated visual from `calibrate-model` below it. Apply calibration
+once; if the tuning record is missing, calibrate first.
 
-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.
+- Name roots by role, with predictable names for repeated instances.
+- Size colliders from measured bounds and keep them aligned with render bounds.
+- Space roots by the scaled footprint in the tuning record, not by pivot position. A non-90° yaw
+  rotates the footprint, so reserve its larger horizontal extent.
+- Keep UI, effects, cameras, and lights outside model hierarchies.
+- Remove the root through its surface's lifecycle and unregister events it owns.
+- Rigid bodies need Ammo loaded first (`build-app`).
 
-## Assembly rules
+## Check placement
 
-- 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.
+After a rendered frame, measure each support or attachment at the object's actual position, using
+a mount point, raycast, or geometry sample read through `inspect-runtime`. A positive gap floats; a negative gap penetrates.
+Overlapping world AABBs between unrelated roots are a failure unless two different views prove the
+overlap is empty space.
 
-## 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.
+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/assemble-scene/references/direct-engine.md

@@ -5,8 +5,8 @@ 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'));
+const root = new Entity('Model_1');
+root.addChild(instance('model'));
 root.setPosition(x, 0, z);
 root.setEulerAngles(0, heading, 0);
 app.root.addChild(root);

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

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

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

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

package/skills/bake-lighting/SKILL.md

@@ -1,67 +1,36 @@
 ---
 name: bake-lighting
-description: Use when a PlayCanvas scene's static lighting, shadows, or ambient occlusion costs too much per frame, or lighting must ship precomputed for startup or payload budgets.
+description: Use when static PlayCanvas lighting, shadows, or ambient occlusion cost too much per frame and should be baked into lightmaps.
 ---
 
-# Precompute static lighting
+# Bake static lighting
 
-Static geometry lit by static lights can bake into lightmap textures once, removing per-frame
-shadow-map rendering and per-pixel dynamic lighting for that light entirely.
+Lightmaps remove per-frame shadow and lighting cost for static lights on static geometry.
 
-## Engine `Lightmapper` flags
+- `Application` registers `Lightmapper`; manual `AppOptions` bootstraps set
+  `lightmapper = Lightmapper`.
+- On the light, set `bake = true`; once every mesh it lights is lightmapped, set
+  `affectDynamic = false`.
+- On each mesh, set `render.lightmapped = true`, or it goes unlit once `affectDynamic` is off. Size
+  it with `lightmapSizeMultiplier`; `castShadowsLightmap` lets meshes shadow each other.
+- Set the mode on `scene.lightmapMode`: `BAKE_COLOR` for flat diffuse, or the default
+  `BAKE_COLORDIR`, which adds direction for normal- or specular-mapped materials.
+- Bake AO without lights with `scene.ambientBake`, `ambientBakeNumSamples`, and
+  `ambientBakeOcclusionBrightness` and `ambientBakeOcclusionContrast`.
+- The Engine bakes once on the first rendered frame. Call `app.lightmapper.bake(null, mode)` only
+  for nodes added later or to re-bake.
 
-- Engine-only bootstraps must register it: `AppOptions.lightmapper = Lightmapper`. `Application`
-  wires this by default; only a manual `AppOptions` assembly needs the explicit line.
-- Per light: `light.bake = true`, then `light.affectDynamic = false` once every mesh it lights is
-  lightmapped, so it stops contributing to the real-time pass.
-- Per mesh: `render.lightmapped = true` — required for the mesh to receive any light once
-  `affectDynamic` is false, a correctness requirement, not just an optimization —
-  `render.lightmapSizeMultiplier` to size its lightmap, `render.castShadowsLightmap` so lightmapped
-  meshes still shadow each other in the bake.
-- Bake mode: `BAKE_COLOR` for flat diffuse materials; `BAKE_COLORDIR` adds a dominant-light-direction
-  pass for normal- or specular-mapped materials that need one.
-- Baked ambient occlusion, independent of any light: `scene.ambientBake` plus
-  `ambientBakeNumSamples`, `ambientBakeOcclusionBrightness`/`OcclusionContrast`.
-- Run `app.lightmapper.bake(null, mode)` once the scene exists; `null` bakes every lightmapped node.
+## A second UV set is required
 
-## Verify UVs before trusting this on real assets
+A node bakes only when every mesh instance has `SEMANTIC_TEXCOORD1`. Otherwise it is skipped, with
+only a debug-build log, and stays dynamically lit. Primitives have the set; imported GLBs often do
+not. Check, then unwrap or re-export.
 
-The installed `Lightmapper` bakes a node only when every mesh instance on it has a second UV set
-(`mesh.vertexBuffer.format.hasUv1`). A node missing one is skipped silently — no warning, no
-lightmap — and its mesh simply stays dynamically lit, which a glance at a screenshot will not catch.
-Procedural primitives generate that set; imported GLB models often do not. Check `hasUv1` on every
-mesh you expect to bake, and unwrap or re-export the ones without it before the bake. Do not carry a
-primitive-only test result into production assets unchecked.
+## On-device or offline
 
-## Choose the rung by budget, not by default
+Time `bake()` on the target device. Move to an offline bake shipped as textures only when it misses
+the startup budget or needs detail the runtime lightmapper cannot produce, and state the added
+download size.
 
-On-device bake cost scales with baked-node count and lightmap resolution; measure it once on the
-target device (`performance.now()` around `bake()`) and compare it with the startup budget before
-choosing a rung. Stay on-device unless:
-
-- the measured bake time does not fit the startup or first-paint budget on the target device, or
-- the result needs stylized material detail beyond lighting that the runtime `Lightmapper` cannot
-  produce.
-
-Only then move to an offline bake shipped as assets, and size the pipeline to the scene count. For
-one deterministic scene the whole pipeline is a build script that computes or renders the maps and
-writes them next to the other static assets, plus a loader; that is sufficient. Registry-keyed
-per-asset configs, worker-thread parallelism and a coverage audit that fails the bake on a missing
-output belong to multi-asset pipelines — add them when the second scene arrives, not before.
-
-Offline maps are payload. State the compressed size delta in the change description and compare it
-with the download or package budget; a modest lightmap set can double the archive of a small web
-app.
-
-## Keep dynamic objects consistent
-
-Whichever rung you use, dynamic objects moving through baked lighting must not read as ignoring it:
-sample or approximate the baked occlusion/shadow field for them and their attachments so they dim to
-the same levels as the static geometry around them, and ground them with a contact shadow. A
-dynamic object whose custom shading must meet baked maps is `override-shader-chunks` territory.
-
-## Prove it
-
-Capture `verify-pixels`-style frames both in and out of the baked shadow, before and after the
-change, and compare them. A screenshot glanced at once is not proof the bake reproduced the lighting
-it removed.
+Dynamic objects moving through baked light need approximated occlusion and a contact shadow, or
+they look pasted on. Compare `verify-pixels` captures in and out of baked shadow.

package/skills/build-app/SKILL.md

@@ -1,43 +1,44 @@
 ---
 name: build-app
-description: Use when creating or restructuring a PlayCanvas application with the direct Engine API, @playcanvas/react, or @playcanvas/web-components to choose the active authoring surface and apply its bootstrap, lifecycle, ownership, asset-loading, and Engine interop patterns.
+description: Use when creating or restructuring a PlayCanvas app with the Engine API, @playcanvas/react, or @playcanvas/web-components, covering bootstrap, input, resize, physics, update loop, UI, and lifecycle.
 ---
 
 # Build an Engine application
 
-Read `package.json` and the application entry point before changing its structure. Choose the
-authoring surface from the code being edited:
-
-- read [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. Set it
-deliberately after the application exists and before its initial automatic resize, and call
-`app.resizeCanvas()` after changing it. Fragment work scales with the square of the ratio, so
-choose the value from a measured frame time on the target display, not from the display alone:
-`Math.min(window.devicePixelRatio, 2)` suits a quality-first viewer on hardware that holds its
-frame budget there, and 1 is the right value wherever it does not. Never cap above
-`window.devicePixelRatio`; a larger value renders identically.
-
-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.
+Read `package.json` and the entry point, keep the surface that owns the lifecycle, and read only its
+reference: [direct Engine](references/direct-engine.md), [React](references/react.md), or
+[Web Components](references/web-components.md). Choose from imports and markup, not dependencies.
+
+## Bootstrap
+
+- Input is opt-in. `app.keyboard`, `mouse`, `touch`, `gamepads`, and `elementInput` stay `null`
+  unless passed to `new Application(canvas, { ... })`; UI buttons need `new ElementInput(canvas)`.
+- The Engine adds no window resize listener; call `app.resizeCanvas()` from your own handler.
+- `graphicsDevice.maxPixelRatio` defaults to 1. Raise it, at most to `window.devicePixelRatio`, only
+  where the target holds its frame budget, call `app.resizeCanvas()`, and confirm with
+  `canvas.width / canvas.clientWidth`.
+- Rigid bodies stay inert until Ammo loads through `WasmModule`. Copy the loader from the
+  `physics/falling-shapes` example with `find-examples`.
+- `devtools` defaults to `true`, so debugging tools can find the app (`inspect-runtime`). Set it to
+  `false` only to hide a production build.
+
+## Update loop
+
+- `dt` is already clamped by `app.maxDeltaTime` (0.1 s); tune it instead of clamping by hand.
+  `app.timeScale` scales it, and `0` pauses scaled time.
+- Keep app state explicit and owned in one place; advance time-dependent logic from `dt`, and reset
+  through the same setup used at start.
+
+## UI
+
+- Render UI from app state; never keep the source of truth in the DOM or UI elements.
+- Use a DOM or React overlay, or Engine `screen` and `element` components adapted from a
+  `user-interface` example.
+- Hide unused elements with `enabled = false`; an element at opacity 0 still draws.
+
+## Ownership
+
+- Keep one owner for app creation, assets, entities, update callbacks, and teardown.
+- Prefer the surface's declarative primitives. Put per-entity and per-frame behaviour in an Engine
+  `Script`.
+- Remove external events and resources in the lifecycle that created them.

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

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