create-playcanvas 0.3.0 → 0.5.0

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

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

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

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

package/skills/inspect-glb/SKILL.md

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

package/skills/inspect-glb/scripts/inspect.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+// zero-dep glb metadata inspector. bounds come from decoded vertex positions, not accessor min/max,
+// so a rotated node reports its true extent and models can be placed touching.
+import fs from 'node:fs';
+
+const GLB_MAGIC = 0x46546c67;
+const JSON_CHUNK = 0x4e4f534a;
+const BIN_CHUNK = 0x004e4942;
+const IDENTITY = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+
+// componentType -> byte size, signedness and normalized divisor (glTF 2.0 table 3.1 / 5.1)
+const COMPONENTS = {
+    5120: { size: 1, signed: true, norm: 127, read: (b, o) => b.readInt8(o) },
+    5121: { size: 1, signed: false, norm: 255, read: (b, o) => b.readUInt8(o) },
+    5122: { size: 2, signed: true, norm: 32767, read: (b, o) => b.readInt16LE(o) },
+    5123: { size: 2, signed: false, norm: 65535, read: (b, o) => b.readUInt16LE(o) },
+    5125: { size: 4, signed: false, norm: 4294967295, read: (b, o) => b.readUInt32LE(o) },
+    5126: { size: 4, signed: true, norm: 1, read: (b, o) => b.readFloatLE(o) }
+};
+
+const mul = (a, b) => {
+    const o = new Array(16);
+    for (let c = 0; c < 4; c++) {
+        for (let r = 0; r < 4; r++) {
+            o[c * 4 + r] =
+                a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3];
+        }
+    }
+    return o;
+};
+
+const compose = ([tx, ty, tz], [x, y, z, w], [sx, sy, sz]) => {
+    const x2 = x + x,
+        y2 = y + y,
+        z2 = z + z;
+    const xx = x * x2,
+        xy = x * y2,
+        xz = x * z2;
+    const yy = y * y2,
+        yz = y * z2,
+        zz = z * z2;
+    const wx = w * x2,
+        wy = w * y2,
+        wz = w * z2;
+    return [
+        (1 - (yy + zz)) * sx,
+        (xy + wz) * sx,
+        (xz - wy) * sx,
+        0,
+        (xy - wz) * sy,
+        (1 - (xx + zz)) * sy,
+        (yz + wx) * sy,
+        0,
+        (xz + wy) * sz,
+        (yz - wx) * sz,
+        (1 - (xx + yy)) * sz,
+        0,
+        tx,
+        ty,
+        tz,
+        1
+    ];
+};
+
+const xform = (m, [x, y, z]) => [
+    m[0] * x + m[4] * y + m[8] * z + m[12],
+    m[1] * x + m[5] * y + m[9] * z + m[13],
+    m[2] * x + m[6] * y + m[10] * z + m[14]
+];
+
+// + 0 normalizes -0 so a floored model reports 0, not -0
+const round = (v) => Math.round(v * 1e4) / 1e4 + 0;
+
+// buffer 0 of a GLB is the BIN chunk; other buffers are external files or data URIs
+const bufferBytes = (g, bin, index) => {
+    const uri = g.buffers?.[index]?.uri;
+    if (uri === undefined) return bin;
+    const base64 = /^data:[^,]*;base64,(.*)$/s.exec(uri);
+    return base64 ? Buffer.from(base64[1], 'base64') : null;
+};
+
+// widen min/max with every decoded POSITION transformed by matrix. returns null on success,
+// otherwise a reason the vertices could not be read so the caller can fall back and say so.
+const accumulate = (g, bin, accessor, matrix, min, max) => {
+    const acc = g.accessors?.[accessor];
+    if (!acc) return 'no-position-accessor';
+    if (acc.sparse) return 'sparse-accessor';
+    if (acc.bufferView === undefined) return 'no-vertex-data';
+    const comp = COMPONENTS[acc.componentType];
+    if (!comp || acc.type !== 'VEC3') return 'unsupported-accessor';
+    const view = g.bufferViews?.[acc.bufferView];
+    if (!view) return 'unsupported-accessor';
+    if (view.extensions?.EXT_meshopt_compression) return 'meshopt-compressed';
+    const bytes = bufferBytes(g, bin, view.buffer ?? 0);
+    if (!bytes) return 'external-buffer';
+    const stride = view.byteStride ?? comp.size * 3;
+    const base = (view.byteOffset ?? 0) + (acc.byteOffset ?? 0);
+    if (!acc.count || base + (acc.count - 1) * stride + comp.size * 3 > bytes.length) return 'truncated-buffer';
+    const scale = acc.normalized ? comp.norm : 1;
+    for (let v = 0; v < acc.count; v++) {
+        const o = base + v * stride;
+        let x = comp.read(bytes, o) / scale;
+        let y = comp.read(bytes, o + comp.size) / scale;
+        let z = comp.read(bytes, o + comp.size * 2) / scale;
+        if (acc.normalized && comp.signed) {
+            if (x < -1) x = -1;
+            if (y < -1) y = -1;
+            if (z < -1) z = -1;
+        }
+        // inlined to avoid allocating a vector per vertex on million-vertex meshes
+        const px = matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12];
+        const py = matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13];
+        const pz = matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14];
+        if (px < min[0]) min[0] = px;
+        if (py < min[1]) min[1] = py;
+        if (pz < min[2]) min[2] = pz;
+        if (px > max[0]) max[0] = px;
+        if (py > max[1]) max[1] = py;
+        if (pz > max[2]) max[2] = pz;
+    }
+    return null;
+};
+
+// loose fallback: bound the 8 corners of the accessor's local box. over-estimates a mesh that does
+// not fill its box when the node rotation is not a multiple of 90 degrees.
+const accumulateCorners = (acc, matrix, min, max) => {
+    if (!acc?.min || !acc?.max) return;
+    for (let c = 0; c < 8; c++) {
+        const point = xform(matrix, [
+            c & 1 ? acc.max[0] : acc.min[0],
+            c & 2 ? acc.max[1] : acc.min[1],
+            c & 4 ? acc.max[2] : acc.min[2]
+        ]);
+        for (let k = 0; k < 3; k++) {
+            if (point[k] < min[k]) min[k] = point[k];
+            if (point[k] > max[k]) max[k] = point[k];
+        }
+    }
+};
+
+export const inspectGlb = (buf) => {
+    if (buf.length < 20 || buf.readUInt32LE(0) !== GLB_MAGIC || buf.readUInt32LE(16) !== JSON_CHUNK) {
+        throw new Error('not a GLB (or JSON chunk missing)');
+    }
+    const jsonLength = buf.readUInt32LE(12);
+    const g = JSON.parse(buf.toString('utf8', 20, 20 + jsonLength));
+    const binAt = 20 + jsonLength;
+    const bin =
+        binAt + 8 <= buf.length && buf.readUInt32LE(binAt + 4) === BIN_CHUNK
+            ? buf.subarray(binAt + 8, binAt + 8 + buf.readUInt32LE(binAt))
+            : null;
+    const nodes = g.nodes ?? [];
+    const nodeName = (i) => nodes[i]?.name ?? `node_${i}`;
+    const parents = new Array(nodes.length).fill(-1);
+    for (let i = 0; i < nodes.length; i++) {
+        for (const child of nodes[i].children ?? []) parents[child] = i;
+    }
+    const nodePath = (i) => {
+        const names = [];
+        for (; i >= 0; i = parents[i]) names.unshift(nodeName(i));
+        return names.join('/');
+    };
+    const children = new Set(nodes.flatMap((n) => n.children ?? []));
+    const roots = g.scenes?.[g.scene ?? 0]?.nodes ?? nodes.map((_, i) => i).filter((i) => !children.has(i));
+
+    const world = new Array(nodes.length);
+    const walk = (i, parent) => {
+        const n = nodes[i];
+        const local = n.matrix ?? compose(n.translation ?? [0, 0, 0], n.rotation ?? [0, 0, 0, 1], n.scale ?? [1, 1, 1]);
+        world[i] = mul(parent, local);
+        for (const child of n.children ?? []) walk(child, world[i]);
+    };
+    for (const root of roots) walk(root, IDENTITY);
+
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    const notes = new Set();
+    let meshNodes = 0;
+    for (let i = 0; i < nodes.length; i++) {
+        if (nodes[i].mesh === undefined || !world[i]) continue;
+        meshNodes++;
+        // glTF 2.0: "the transform of the skinned mesh node MUST be ignored" - joints drive the pose
+        const matrix = nodes[i].skin === undefined ? world[i] : IDENTITY;
+        for (const prim of g.meshes?.[nodes[i].mesh]?.primitives ?? []) {
+            const note = prim.extensions?.KHR_draco_mesh_compression
+                ? 'draco-compressed'
+                : accumulate(g, bin, prim.attributes?.POSITION, matrix, min, max);
+            if (!note) continue;
+            notes.add(note);
+            accumulateCorners(g.accessors?.[prim.attributes?.POSITION], matrix, min, max);
+        }
+    }
+
+    const ok = min[0] !== Infinity;
+    return {
+        aabb: ok ? { min: min.map(round), max: max.map(round) } : null,
+        dims: ok ? max.map((v, i) => round(v - min[i])) : null,
+        center: ok ? max.map((v, i) => round((v + min[i]) / 2)) : null,
+        groundOffset: ok ? round(-min[1]) : null,
+        boundsSource: ok ? (notes.size ? 'accessor-minmax' : 'vertices') : null,
+        ...(notes.size ? { boundsNotes: [...notes].sort() } : {}),
+        nodes: nodes.length,
+        nodePaths: nodes.map((_, i) => nodePath(i)).sort(),
+        meshNodes,
+        materials: (g.materials ?? []).map((m, i) => m.name ?? `material_${i}`),
+        clips: (g.animations ?? []).map((a, i) => ({
+            name: a.name ?? `clip_${i}`,
+            duration: round(Math.max(0, ...a.samplers.map((s) => g.accessors?.[s.input]?.max?.[0] ?? 0)))
+        })),
+        joints: [...new Set((g.skins ?? []).flatMap((s) => s.joints ?? []).map(nodeName))].sort(),
+        animationTargets: [
+            ...new Set(
+                (g.animations ?? [])
+                    .flatMap((a) => a.channels ?? [])
+                    .flatMap((c) =>
+                        c.target?.node === undefined ? [] : [`${nodePath(c.target.node)}.${c.target.path}`]
+                    )
+            )
+        ].sort(),
+        skinned: !!g.skins?.length
+    };
+};
+
+if (import.meta.main ?? import.meta.filename === process.argv[1]) {
+    const files = process.argv.slice(2);
+    if (!files.length) {
+        console.error('usage: node inspect.mjs <file.glb> [more.glb ...]');
+        process.exit(1);
+    }
+    // report per-file failures so one unreadable file cannot discard a whole glob
+    const out = files.map((file) => {
+        try {
+            return { file, ...inspectGlb(fs.readFileSync(file)) };
+        } catch (e) {
+            return { file, error: e.message };
+        }
+    });
+    console.log(JSON.stringify(out.length === 1 ? out[0] : out, null, 2));
+}

package/skills/light-scene/SKILL.md

@@ -0,0 +1,84 @@
+---
+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.
+---
+
+# Cinematic rendering
+
+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.
+
+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`:
+
+- 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 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.
+
+Keep the two named 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 either 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
+
+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.

package/skills/manage-game-state/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: manage-game-state
+description: Use when structuring a PlayCanvas game's control flow — a small state machine such as ready, playing, paused, and over, pointer-lock capture, pausing on focus or pointer-lock loss, a full reset, and a stable clock and timestep — so the loop stays deterministic and recoverable.
+---
+
+# Game state and loop
+
+Model the game as a small explicit state machine with one owner of the clock. Every transition names
+its states; behaviour, input, and the interface read the current state rather than a scatter of
+booleans.
+
+## States and transitions
+
+- Enumerate the states — for example ready, playing, paused, over — and make transitions explicit
+  and total. Do not infer state from side effects.
+- Gate the simulation on the active state: advance gameplay, timers, and physics only while playing.
+
+## Capture input and pause
+
+- Request pointer lock from a user gesture such as a click, never on load. Treat loss of pointer lock
+  and tab blur as a pause: freeze the simulation and the clock, and resume on the next gesture.
+- Make `pointerlockchange` idempotent: when `document.pointerLockElement` is the canvas, transition
+  ready or paused to playing and leave playing unchanged; only transition playing to paused when the
+  element is no longer the canvas. Never implement it as a toggle. Browsers and automation can both
+  report an already-acquired lock, and a duplicate enter event must not pause the game.
+- Clamp the per-frame delta before integrating anything, as `build-app` requires, so a backgrounded
+  tab or a slow frame cannot inject one large step into movement, cooldowns, or the clock.
+
+## Reset
+
+- A reset restores every owned system to its ready values — entities, camera, clock, timers,
+  cooldowns, effects, and overlays — not only the player. Route reset through the same setup the
+  initial state uses, so ready and reset cannot drift apart.
+- Transition to `ready` explicitly before releasing pointer lock. Never derive the reset state from
+  `document.pointerLockElement`; pointer lock is an input side effect, not the state machine.
+- Define timer semantics once and keep them literal in state and snapshots. A field named `reload`
+  is remaining cooldown time: `0` means ready, firing assigns a positive duration, and the active
+  loop counts it down to exactly `0`. Do not expose a normalized readiness value under that name.
+
+## Prove the loop
+
+Drive the full cycle with real input: enter play, lose pointer lock and confirm the clock and
+simulation freeze, resume, reset and confirm every field returns to its ready value, then reach the
+end state and restart. Read these from the app's own state snapshot, never from console mutation —
+manufactured state is not evidence.
+
+Choose the authoring surface with the `build-app` skill and own the loop and lifecycle in the surface
+that creates the application.

package/skills/reuse-scripts/SKILL.md

@@ -0,0 +1,59 @@
+---
+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.
+---
+
+# Engine scripts
+
+The installed `playcanvas` package ships production scripts under `scripts/esm/**`. Discover the
+current set rather than maintaining a stale list:
+
+```sh
+rg 'static scriptName =' node_modules/playcanvas/scripts/esm \
+  | sed "s|.*/scripts/esm/||; s|:.*static scriptName = ['\"]|  ->  |; s|['\"].*||" \
+  | 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.
+
+If no matching example exists, state that and derive the integration from installed source instead
+of inventing it from memory.
+
+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.
+
+## Preserve grouped defaults
+
+Grouped property updates differ by authoring surface. Read the selected reference and preserve
+defaults that are not being changed.
+
+Read exactly one reference matching the code being edited:
+[direct Engine](references/direct-engine.md), [React](references/react.md), or
+[Web Components](references/web-components.md). Choose from imports and markup, not installed
+dependencies alone.

package/skills/reuse-scripts/references/direct-engine.md

@@ -0,0 +1,41 @@
+# 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);
+```
+
+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';
+
+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:
+
+```ts
+import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
+
+const sky = skyEntity.script?.create(ProceduralSky);
+if (sky) sky.sunLight = sun;
+```
+
+If the installed script subpaths have no declarations, declare only the patterns the project uses:
+
+```ts
+declare module 'playcanvas/scripts/esm/*.mjs';
+declare module 'playcanvas/scripts/esm/*/*.mjs';
+```

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

@@ -0,0 +1,28 @@
+# 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>;
+```
+
+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.
+
+Props on `<Script>` become script properties. Pass complete grouped properties or use a ref to
+mutate the existing group after mount. Verify the current component props in the installed
+`@playcanvas/react` declarations.
+
+If the installed Engine script subpaths have no declarations, add:
+
+```ts
+declare module 'playcanvas/scripts/esm/*.mjs';
+declare module 'playcanvas/scripts/esm/*/*.mjs';
+```

package/skills/reuse-scripts/references/web-components.md

@@ -0,0 +1,27 @@
+# Web Components projects
+
+Expose an Engine script as an ES module and register it as an asset:
+
+```html
+<pc-app>
+    <pc-asset src="/scripts/camera-controls.mjs"></pc-asset>
+    <pc-scene>
+        <pc-entity name="Camera">
+            <pc-camera></pc-camera>
+            <pc-scripts>
+                <pc-script name="cameraControls" move-speed="4"></pc-script>
+            </pc-scripts>
+        </pc-entity>
+    </pc-scene>
+</pc-app>
+```
+
+The `name` must equal the class's static `scriptName`. Extra kebab-case attributes map to camelCase
+script properties. Use the `attributes` JSON attribute for nested or reserved properties; it
+recursively merges partial grouped objects into the script's defaults. Arrays are not merged element
+by element, so an array in the JSON replaces the script's default array whole, and a kebab-case
+attribute always wins over the same key inside the JSON.
+
+Use `asset:`, `entity:`, `vec2:`, `vec3:`, `vec4:`, or `color:` prefixes where a property needs a
+typed reference. Verify the selected script's export, property names, and defaults against the
+installed Engine file.

package/templates/engine/base/.prettierignore

@@ -0,0 +1,2 @@
+.claude
+.agents