create-playcanvas 0.8.0 → 0.9.0

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,94 +1,41 @@
 ---
 name: light-scene
-description: Use when a PlayCanvas scene must read as a deliberate cinematic image rather than a flat asset preview, to set key and ambient lighting, sky and image-based lighting, shadows, tone mapping and exposure, 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.
 
-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`:
+## Defaults to change
 
-- 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.
+- `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`).
 
-For an outdoor scene with 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, tessellated plane, or reflection-coloured mesh is not the
-baseline and does not substitute for `Water` when the brief asks for reflective water.
+## Use what ships
 
-Keep the two named production integrations visible in the implementation:
+- `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`.
 
-- 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.
+Find each integration's example with `find-examples`.
 
-Do not continue to cosmetic tuning while either integration is missing or diagnostics report a
-shader, texture, or framebuffer error.
+## Warning signs
 
-## Stylized and prebaked scenes
-
-When the art direction is deliberately flat or stylized rather than photoreal, or the platform's
-startup, frame, or payload budget rules out the runtime pipeline above, do not treat `Water`,
-`CameraFrame`, and the sky/IBL bake as mandatory. The sanctioned alternative is baked static
-lighting via the `bake-lighting` skill plus custom material shading via the `override-shader-chunks`
-skill. Either way, dynamic objects and their attachments must sample or approximate the baked
-occlusion so they dim to the same levels as the baked surfaces, grounded with contact shadows. Fall
-back to the runtime pipeline above as the default path when neither trigger holds.
-
-## 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
-
-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. 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,59 +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.21'`)
-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.
-
-## 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.22'`. 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,61 +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.drawCalls.total` or `MiniStats`; the per-pass 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`.
 
-## Rung 1: stop drawing invisible things
+## 2. 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.
+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`.
 
-## Rung 2: `BatchManager` — merge without touching shaders
+## 3. Hardware instancing
 
-`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.
+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.
 
-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.
+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.
 
-## 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 and reuse production scripts shipped with the installed Engine, reproduce their official example integration, and verify the result against the installed version.
+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
 
-The installed `playcanvas` package ships production scripts under `scripts/esm/**`. Discover the
-current set rather than maintaining a stale list:
+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,46 +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.
-
-Use a relevant shipped script as the default implementation. If it cannot own the whole feature,
-preserve its input signs, angular damping, bounds, and lifecycle invariants in the custom portion
-instead of replacing them from memory.
-
-## Reproduce the reference integration
-
-Treat the selected script source and its closest official example as complementary references:
-
-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. Reproduce the smallest working baseline before customizing it. Preserve defaults that are not
-   deliberately changed, and tune one property group at a time.
-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. Compare the result with the official example when visual quality matters. Keep iterating or
-   report the gap; a running fallback is not proof of correct integration.
+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.
 
-If no matching example exists, state that and derive the integration from installed source instead
-of inventing it from memory.
+Core exports that are not scripts include `CameraFrame` for post-processing, `Picker`
+(`getSelectionAsync`), `TransformGizmo`, `OutlineRenderer`, `MiniStats`, `GltfExporter`, and
+`UsdzExporter`.
 
-For an outdoor water scene, start from `graphics/water.example.mjs` as one integration recipe. It
-combines `Water`, `ProceduralSky`, `CameraControls`, `CameraFrame`, a dedicated water layer, scene
-depth, normal and caustics textures, and conservative rendering defaults. Establish that complete
-baseline before adapting its camera, assets, time of day, or water tuning.
+## 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

@@ -1,37 +1,17 @@
 # Direct Engine projects
 
-Import the named script class and attach it to the owning entity:
-
-```ts
-import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
-
-camera.addComponent('script');
-const controls = camera.script?.create(CameraControls);
-```
+Import the selected class from its installed module, add a script component to the owning entity,
+and attach it with `entity.script.create()`. Preserve an existing script component.
 
 Some production helpers are core Engine exports rather than scripts. Follow the matching example's
-construction style instead of forcing them through `script.create`:
-
-```ts
-import { CameraFrame } from 'playcanvas';
+construction and teardown contract instead of forcing them through `script.create`.
 
-const frame = new CameraFrame(app, camera.camera!);
-frame.rendering.sceneDepthMap = true;
-frame.update();
-```
-
-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.
-
-Prefer mutating an existing grouped property when only a few fields change:
+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.
 
-```ts
-import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
-
-const sky = skyEntity.script?.create(ProceduralSky);
-if (sky) sky.sunLight = sun;
-```
+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.
 
 If the installed script subpaths have no declarations, declare only the patterns the project uses:
 

package/skills/reuse-scripts/references/react.md

@@ -1,17 +1,7 @@
 # React projects
 
-Import the named script class and attach it through React:
-
-```tsx
-import { Entity } from '@playcanvas/react';
-import { Camera, Script } from '@playcanvas/react/components';
-import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
-
-<Entity name="Camera" position={[4, 1, 4]}>
-    <Camera />
-    <Script script={CameraControls} />
-</Entity>;
-```
+Import the selected class from its installed module. Render `Script` from
+`@playcanvas/react/components` inside the owning `Entity`, passing the class through its `script` prop.
 
 Keep imported or custom script constructors at module scope. Declaring a class inside a component
 creates a new identity on render and can recreate the script.