create-playcanvas 0.8.1 → 0.10.0

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.

package/skills/override-shader-chunks/SKILL.md

@@ -1,65 +1,25 @@
 ---
 name: override-shader-chunks
-description: Use when a PlayCanvas StandardMaterial needs custom shading its properties cannot express — procedural or stylized looks, custom vertex displacement, per-material screen effects — before writing a standalone shader from scratch.
+description: Use when a PlayCanvas StandardMaterial needs custom shading its properties cannot express, such as stylized looks or vertex displacement, before writing a ShaderMaterial.
 ---
 
-# Override shading through chunks
-
-A `StandardMaterial`'s shader is assembled from named chunks (lighting, combine, transform, and
-more). Overriding one keeps the rest of the pipeline — fog, tonemapping, shadows, skinning,
-instancing — intact. Reach for a fully custom `ShaderMaterial` only when the look needs a stage the
-chunk system does not expose at all (its own vertex/fragment pair and attribute layout); a chunk
-override is the default for everything else, since it is cheaper and stays integrated.
-
-## Pin the version, read the source
-
-Set `material.shaderChunksVersion` to the installed engine's major.minor (for example `'2.22'`)
-before shipping any override. Chunk names and their contracts — what a chunk defines, what globals
-it reads or writes — are version-keyed and change between releases. Read the installed `playcanvas`
-source for the exact chunk being touched; do not recall its contract from memory or an older
-version's documentation.
-
-## Clone before overriding a shared material
-
-Clone a material that other mesh instances share — including default and asset-imported materials —
-before changing its chunks, properties, or material-level parameters for only some meshes, and assign
-the clone. For per-mesh uniforms, use `meshInstance.setParameter()` without cloning the material.
-
-## Set chunks through the documented accessor
-
-Use `material.getShaderChunks(SHADERLANGUAGE_GLSL).set(name, source)`, and the WGSL equivalent —
-the public, documented method — not the underlying `shaderChunks` maps, which are internal. Call
-`material.update()` after any change so cached shader variants are cleared.
-
-## Emissive-only overrides
-
-An `emissivePS` override implements `void getEmission()`, writing the result into `dEmission`. When
-the override is meant to fully drive the visible color, zero the material's `diffuse`/`specular` and
-disable `useSkybox` so no other lighting term still contributes underneath it.
-
-## Uniforms are raw
-
-`setParameter` uploads exactly what it is given, with no color-space conversion. Convert any
-authored sRGB color with `Color#linear()` before calling `setParameter`; an sRGB color passed
-straight through renders visibly darker and less saturated than it was authored.
-
-## Keep vertex chunks instancing-aware
-
-A custom `transformCoreVS` (or any vertex chunk reading the model matrix) must keep the engine's
-`INSTANCING` define path — pulling the per-instance matrix under that define — with a
-non-instanced fallback that uses `matrix_model` directly, matching the stock chunk's structure.
-Dropping this path silently breaks instancing for any mesh instance using the material.
-
-## Provide GLSL and WGSL, or pin to WebGL
-
-Override both `SHADERLANGUAGE_GLSL` and `SHADERLANGUAGE_WGSL` chunks for anything touched. On a
-WebGPU device, a chunk supplied only in GLSL forces the material's entire shader — not just that
-chunk — onto a GLSL-compiled-then-transpiled path; without the optional transpiler modules loaded
-(the common case), that shader fails to compile. Supply both languages, or explicitly pin the
-graphics device to WebGL if WGSL support is not required.
-
-## Expand bounds for vertex displacement
-
-If the override displaces vertices, expand the mesh's bounds by the maximum displacement (see
-`apply-conventions`) — CPU-computed bounds never observe shader-side deformation, so culling breaks
-silently otherwise.
+# Override shader chunks
+
+Overriding a `StandardMaterial` chunk keeps fog, tone mapping, shadows, skinning, and instancing
+intact. Use a `ShaderMaterial` only when the look needs its own vertex and fragment pair.
+
+- Set `material.shaderChunksVersion` to the installed major.minor, such as `'2.23'`. Chunk names
+  and contracts change between versions, so read the installed chunk source, not memory.
+- Set chunks with `material.getShaderChunks(SHADERLANGUAGE_GLSL).set(name, source)` and the WGSL
+  equivalent, then call `material.update()`. For every material on a device, use
+  `ShaderChunks.get(device, language)`; the global `shaderChunks` object is deprecated.
+- Supply both GLSL and WGSL. On WebGPU, one GLSL-only chunk sends the whole shader through a
+  transpiler that is usually not loaded, so it fails to compile. Otherwise pin the device to WebGL.
+- Clone shared materials, including imported ones, before overriding them for only some meshes.
+  Per-mesh uniforms use `meshInstance.setParameter()`.
+- Uniforms are raw; convert sRGB colours with `Color#linear()`.
+- Vertex chunks that read the model matrix, such as `transformCoreVS`, must keep the `INSTANCING`
+  path with a `matrix_model` fallback, like the stock chunk.
+- Expand mesh bounds by the maximum displacement; CPU bounds do not see shader deformation.
+- For an emissive-only look, implement `getEmission()` writing `dEmission`, zero `diffuse` and
+  `specular`, and disable `useSkybox`.

package/skills/reduce-draw-calls/SKILL.md

@@ -1,67 +1,37 @@
 ---
 name: reduce-draw-calls
-description: Use when a PlayCanvas application submits too many draw calls or frame time is CPU-bound — repeated meshes, dense grids, always-on interface elements — before hand-writing mesh merging or custom renderers.
+description: Use when a PlayCanvas app has too many draw calls or is CPU-bound, before hand-merging meshes or writing custom renderers.
 ---
 
-# Cut draw calls, ranked by cost
+# Cut draw calls
 
-Work the ladder in order and stop at the first rung that clears the budget. Each rung trades away
-less flexibility than the next; skipping straight to a custom renderer or hand-written mesh merge
-costs more engineering time than the draw calls it saves.
+Measure first with `app.stats.drawCallCount` or `MiniStats`; the per-pass `app.stats.drawCalls`
+breakdown fills only in profiler builds. Also halve the pixel ratio and call `app.resizeCanvas()`:
+if frame time drops, the cost is fill rate, not draw calls. Stop at the first rung that meets the
+budget and report before-and-after counts.
 
-## Measure first
+## 1. Stop drawing hidden things
 
-Read `app.stats.drawCalls.total` (or the `forward`/`depth`/`shadow` breakdown) before changing
-anything, or drop in `MiniStats` for a live overlay. Every rung below is proved against this number,
-not against intuition about what "looks expensive."
+An element at opacity 0 still draws. Set `enabled = false`.
 
-Draw count alone does not identify the bottleneck. Test sensitivity to pixel cost by halving the
-effective pixel ratio (`Math.min(graphicsDevice.maxPixelRatio, window.devicePixelRatio)`) and calling
-`app.resizeCanvas()`. Verify the backbuffer shrank and compare frame times at the same scene state.
-If frame time improves materially, prioritize resolution, multisampling and per-pixel shader cost.
-Otherwise profile CPU and GPU work before choosing a rung; restore the original ratio after the test.
+## 2. BatchManager
 
-## Rung 1: stop drawing invisible things
+Call `app.batcher.addGroup(name, dynamic, maxAabbSize)`, then set `batchGroupId` on render, sprite,
+or element components. Use `dynamic: false` for geometry that never moves. Members join when
+enabled in the live tree, in any order, and groups regenerate automatically when membership
+changes. Call `markGroupDirty(id)` only after moving members of a static group. Manual `AppOptions`
+bootstraps must set `batchManager`.
 
-An element at opacity 0 still submits a draw call — its mesh instance exists and is still in a
-layer, so the GPU processes it every frame for no visible result. Toggle `enabled` on the entity to
-actually skip it. Check every element that is ever fully transparent, not only the ones on screen
-when you're profiling — this rung is easy to skip precisely because nothing looks wrong.
+## 3. Hardware instancing
 
-## Rung 2: `BatchManager` — merge without touching shaders
+Use this for many copies of one mesh and material with per-frame transforms. Build a buffer with
+`VertexFormat.getDefaultInstancingFormat(device)`, one mat4 per instance, and call
+`meshInstance.setInstancing(vb)`; `instancingCount` follows the buffer.
 
-`app.batcher.addGroup(name, dynamic, maxAabbSize)`, then set `batchGroupId` on each member's
-component (render, sprite, or UI element). Use `dynamic: false` for geometry that never moves.
+There is no per-instance culling. By default the group always draws; `setInstancing(vb, true)`
+culls it as one unit against a `RenderComponent#customAabb` covering every instance. Split large
+instance sets into spatial chunks. Custom vertex chunks need the `INSTANCING` path
+(`override-shader-chunks`). Start from the `graphics/instancing-basic` and
+`graphics/instancing-custom` examples.
 
-Contract: the `batchGroupId` setter only inserts into the batcher while `entity.enabled` is true,
-and that flag requires both the local enable state and hierarchy attachment — set `batchGroupId`
-after the entity is parented into the live tree, not before, or the member silently drops out of the
-group. `BatchManager.generate()` runs once automatically on the app's first rendered frame; if group
-membership changes afterward, call `app.batcher.markGroupDirty(id)` (or `generate([id])`) yourself.
-An Engine-only app without the full `Application` bootstrap must register the class via
-`AppOptions.batchManager` before it can batch anything.
-
-## Rung 3: hardware instancing — merge without touching layout
-
-Reach for this once distinct materials or per-frame transform updates would defeat `BatchManager`.
-Build a per-instance vertex buffer with `VertexFormat.getDefaultInstancingFormat(device)` (one mat4
-per instance), call `meshInstance.setInstancing(vb)`, and set `instancingCount`. A custom vertex
-chunk needs its own `INSTANCING` code path with an identity-matrix fallback for the non-instanced
-case (cross-reference `override-shader-chunks`).
-
-Culling trade-off: instanced meshes cull as one unit against a single bounding volume — an
-off-screen instance inside an otherwise-visible group still draws unless you opt in. Pass
-`setInstancing(vb, true)` and set a `RenderComponent#customAabb` spanning every instance's world
-extent so the renderer has something correct to cull against instead of culling nothing or
-culling the whole group by one instance's bounds.
-
-Adapt the official recipes rather than deriving the buffer layout or vertex-shader wiring from
-memory: `graphics/instancing-basic` for the format/buffer contract, `graphics/instancing-custom` for
-the vertex-shader side. Locate both at the installed engine version via `find-examples`.
-
-## Prove and report
-
-Verify the rendered image is unchanged with `verify-pixels` before calling the change done —
-merging or instancing must not move a single pixel. Re-measure `app.stats.drawCalls` afterward and
-state the before/after counts in the change description; "fewer draw calls" without numbers is not
-a result.
+Confirm the image is unchanged with `verify-pixels`.

package/skills/reuse-scripts/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: reuse-scripts
-description: Use before implementing non-core PlayCanvas behavior to discover the installed Engine's curated scripts and reuse or adapt those that fit the required behavior and approved art direction.
+description: Use before writing PlayCanvas behaviour from scratch, to reuse the scripts and helpers the installed Engine already ships.
 ---
 
-# Engine scripts
+# Reuse shipped Engine code
 
-Before writing behavior from scratch, inspect the curated scripts shipped with the installed
-`playcanvas` package under `scripts/esm/**`. Discover the current set:
+Before writing behaviour, check what the installed `playcanvas` package already provides.
+
+Scripts live under `scripts/esm/**`; import only from there. List them:
 
 ```sh
 rg 'static scriptName =' node_modules/playcanvas/scripts/esm \
@@ -14,50 +15,26 @@ rg 'static scriptName =' node_modules/playcanvas/scripts/esm \
   | sort
 ```
 
-Read the selected file for its named export, `@attribute` properties, and defaults. Not every module
-is a `Script`; the parsers below `scripts/esm/parsers` are plain classes registered with a resource
-handler instead.
-
-Only import from `scripts/esm/**`. Legacy sibling directories depend on the global Engine namespace.
-After selecting a script, use `find-examples` to locate its matching versioned Engine example. When
-`node_modules/playcanvas` is a linked or source checkout, its `examples/src/examples/**` are already
-on disk; read them there and skip the fetch.
-
-## Check fit before integration
-
-Compare candidates with the required behavior, approved art direction, and runtime constraints.
-Reuse a suitable script directly or adapt its configuration and extension points. If none fits,
-state the limitation and implement only the missing behavior, preserving reusable parts and their
-lifecycle, bounds, and input invariants.
-
-For visual behavior, resolve an unclear art direction with the user before substantial implementation.
-Present references, mockups, or inexpensive variants; follow existing approval and confirm significant
-departures. A script's default appearance is only a starting point for assessing its fit.
-
-## Adapt the reference integration
-
-Treat the selected script source and its closest official example as complementary references:
+Common ones are `CameraControls`, `FirstPersonController`, `ThirdPersonController`,
+`ShadowCatcher`, `ProceduralSky`, `Water`, and `Grid`, plus XR and splat scripts. Modules under
+`scripts/esm/parsers` are resource-handler classes, not scripts.
 
-1. Read the source for exports, properties, defaults, fallbacks, required components, and lifecycle.
-2. Read the example for assets, entity references, mesh requirements, layer ordering, scene settings,
-   and render-pipeline setup.
-3. Integrate the selected behavior with its required components, assets, and passes. Adapt the look
-   to the approved direction and preserve defaults and dependencies that still apply.
-4. After a rendered frame, fail on console, shader, or missing-asset diagnostics. Exercise the
-   behavior with real input where applicable and inspect returned screenshots from representative
-   views at the final backbuffer density.
-5. Use the example to check integration correctness and the user's approved direction to judge the
-   final look. Report any remaining gap.
+Core exports that are not scripts include `CameraFrame` for post-processing, `Picker`
+(`getSelectionAsync`), `TransformGizmo`, `OutlineRenderer`, `MiniStats`, `GltfExporter`, and
+`UsdzExporter`.
 
-If no matching example exists, state that and derive the integration from installed source instead
-of inventing it from memory.
+## Integrate
 
-## Preserve grouped defaults
+1. Read the source for exports, `@attribute` properties, defaults, and required components.
+2. Find its official example with `find-examples`, and copy the assets, layers, scene settings, and
+   render setup it depends on.
+3. Adapt configuration and extension points. If nothing fits, implement only the missing part and
+   say what was missing.
+4. After a rendered frame, fail on console, shader, or missing-asset errors.
 
-Grouped property updates differ by authoring surface. Read the selected reference and preserve
-defaults that are not being changed.
+Keep a shipped script's input mapping and damping unless asked otherwise, and verify input
+directions with real input rather than deriving signs from memory.
 
-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.
+Grouped property updates differ by surface; preserve defaults you do not change. 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/reuse-scripts/references/direct-engine.md

@@ -6,9 +6,9 @@ and attach it with `entity.script.create()`. Preserve an existing script compone
 Some production helpers are core Engine exports rather than scripts. Follow the matching example's
 construction and teardown contract instead of forcing them through `script.create`.
 
-Keep script constructors at module scope. `create` takes two distinct option keys that are not
-interchangeable: `properties` is assigned straight onto the instance, while `attributes` supplies
-declared `@attribute` fields. Passing the wrong one silently does nothing.
+Keep script constructors at module scope. `create` takes two option keys: `attributes` is passed to
+the constructor for declared `@attribute` fields, while `properties` is `Object.assign`ed onto the
+instance after construction, overwriting any field it names.
 
 Prefer mutating an existing grouped property when only a few fields change; preserve other defaults
 and follow any update or rebuild contract in the selected source.

package/skills/verify-pixels/SKILL.md

@@ -1,70 +1,36 @@
 ---
 name: verify-pixels
-description: Use when changing PlayCanvas rendering code that must not visibly change the rendered image — draw-call optimization, hardware instancing, shader or material refactors, noise or lightmap bakes, or asset pipeline swaps — before shipping.
+description: Use when a PlayCanvas rendering change is meant to leave the image unchanged, to prove it with deterministic captures and pixel comparison.
 ---
 
 # Prove pixels unchanged
 
-Choose the gate before building the capture harness. Both classes require controlled captures
-that cover the affected surfaces.
+## Choose the gate
 
-## Classify the change
+- Byte-exact: the change keeps the same decoded data and the same shading math, so every pixel
+  must match.
+- Side-by-side review: the change alters sampled values, random order, precision, or where math
+  runs. Report it as "not byte-gateable" and show old and new at each pose; do not invent
+  thresholds.
 
-| Change | Gate |
-| --- | --- |
-| Batching, instancing, mesh indexing, chunking, pooling that preserves RNG order, an asset format swap with identical decoded data | Byte-exact matrix |
-| Re-rolled or re-sampled procedural noise, a changed RNG consumption order, math moved between CPU and GPU, changed precision, fewer octaves or samples | Not byte-gateable: side-by-side review |
+## Make frames deterministic
 
-For the second class, sampled values or precision can change. Report it as "not byte-gateable" and
-use the side-by-side gate after the shared capture setup below; do not invent uncalibrated perceptual
-thresholds to approve it.
+- Load every asset and match camera, canvas size, lighting, and animation time between builds. Seed
+  incidental randomness.
+- Drive animated shaders from one app-owned time value, not `Date.now()` or `performance.now()`.
+- `app.timeScale = 0` makes `dt` zero, but `update` still runs; anything counting frames or reading
+  wall-clock time still advances.
+- Set `app.autoRender = false`, then `app.renderNextFrame = true` before each frame to capture.
 
-## Cover every touched surface
+## Capture and compare
 
-List every touched material or surface and a capture pose it dominates. Use at least two
-representative poses, adding as many as coverage requires; a horizon strip does not cover a water
-shader change. For animated surfaces, include a second phase mid-animation.
+- WebGL: `await (device as WebglGraphicsDevice).readPixelsAsync(x, y, w, h, pixels)`. WebGPU:
+  render into a `RenderTarget` and read its `colorBuffer` with `Texture#read()`. Avoid colour
+  conversion and lossy encoding.
+- Capture the unmodified build twice first. The captures must match exactly, or the harness itself
+  is noisy.
+- Cover every touched surface in at least two poses, plus a mid-animation phase where relevant.
+- Report the count, for example "0 of 65536 pixels differ", or the count and where the differences
+  are. "Looks the same" is not a result.
 
-## Make the frame deterministic
-
-For both gates, load assets fully and match the scene state, camera, canvas size, lighting, and
-animation time between builds. Seed incidental randomness so only the intended change varies.
-
-- Drive every animated shader or vertex effect from one app-owned time value, never `Date.now()` or
-  `performance.now()` read inside the render path, so a captured phase is exactly reproducible.
-- Freeze the clock with `app.timeScale = 0` before capturing; nothing should advance between frames
-  you did not explicitly step.
-- Step frames explicitly: set `app.autoRender = false` once, then set `app.renderNextFrame = true`
-  before each frame you want rendered. The engine renders exactly that frame and clears the flag —
-  do not rely on the free-running render loop plus a timed screenshot.
-
-## Gate and report the byte-exact class
-
-Read the exact backbuffer with `await device.readPixelsAsync(x, y, w, h, pixels)`. In the installed
-engine this method lives on `WebglGraphicsDevice`, so narrow to it; WebGPU needs an equivalent
-readback. An existing capture path must preserve raw pixels without colour conversion or lossy
-encoding before comparison.
-
-Before trusting any diff between the old and new build, capture the same pose × phase matrix twice
-from the *unmodified* build. Two captures of identical, frozen state must be bit-identical. If they
-are not, the capture path itself is the source of noise — an unseeded animation, an asset still
-loading, a GPU timing race — and must be fixed before it can say anything about the real change.
-
-Byte-compare each pose × phase pair between the two builds; do not diff by looking. Zero differing
-pixels passes outright. Any nonzero diff must be reviewed on-screen, and its cause and extent stated
-in the change description — never merged silently. Report the actual count every time, for example
-"0 of 65536 pixels differ" or "312 of 65536 pixels differ, confined to the object's silhouette edge".
-"Looks the same" or "no visible difference" is not a result.
-
-## Review the other class side by side
-
-For each planned pose and phase, show the controlled old and new captures together in one image
-for the user's accept or reject. State what differs and why, for example "noise tile replaces
-runtime fbm: pattern period changed, tint and amplitude match". If no difference is visible, report
-that. Skip the cross-build byte comparison for this class.
-
-## Keep the harness small
-
-Reuse the project's capture harness when available. Keep harness code out of the shipped bundle,
-behind a dev-only import or in a tools directory, and list its files in the change description.
-Capture with a headless browser and return images only at accept-or-reject points, not after every edit.
+Keep harness code out of the shipped bundle; attach it through `inspect-runtime`.

package/templates/engine/base/README.md

@@ -17,6 +17,10 @@ npm run dev
 
 Open <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
 
+## Inspector
+
+`npm run dev` loads the [PlayCanvas Inspector](https://github.com/playcanvas/inspector), a debug panel for the hierarchy, assets, materials, textures, frame graph and physics. Press the backquote key (<kbd>&#96;</kbd>) to show or hide it, <kbd>F9</kbd> to pause and <kbd>F10</kbd> to step a frame. It is wired up in `vite.config.ts` and `src/inspector.ts` and is left out of production builds.
+
 ## Scripts
 
 | Command             | Description                       |

package/templates/engine/base/package.json

@@ -15,14 +15,15 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "playcanvas": "^2.22.6"
+        "playcanvas": "^2.23.0"
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
+        "@playcanvas/inspector": "^0.2.0",
         "eslint": "^9.39.5",
         "prettier": "^3.9.9",
         "typescript": "~6.0.3",
-        "vite": "^8.3.1"
+        "vite": "^8.3.2"
     },
     "engines": {
         "node": ">=22.23.2"