create-playcanvas 0.6.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "create-playcanvas",
-    "version": "0.6.2",
+    "version": "0.7.0",
     "description": "Scaffold a PlayCanvas project",
     "keywords": [
         "playcanvas",

package/skills/apply-conventions/SKILL.md

@@ -43,6 +43,8 @@ details. Apply these stable conventions throughout the project.
 - Materials cull back faces by default; counter-clockwise winding defines the front face.
 - Clone a material before per-instance tinting or edits, and assign the clone; never mutate one
   shared by other instances, including default and asset-imported materials.
+- `setParameter` uploads raw values; author colours in sRGB and convert with `Color#linear()`
+  before upload — do not hand-roll gamma.
 - Entities do not have an `aabb`. Union descendant `meshInstance.aabb` values after transforms have
   synchronized.
 - Let `Mesh.update()` calculate local bounds. If passing `false` for `updateBoundingBox`, assign an

package/skills/bake-lighting/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: bake-lighting
+description: Use when a PlayCanvas scene's static lighting, shadows, or ambient occlusion costs too much per frame, or lighting must ship precomputed for startup or payload budgets.
+---
+
+# Precompute static lighting
+
+Static geometry lit by static lights can bake into lightmap textures once, removing per-frame
+shadow-map rendering and per-pixel dynamic lighting for that light entirely.
+
+## Engine `Lightmapper` flags
+
+- Engine-only bootstraps must register it: `AppOptions.lightmapper = Lightmapper`. `Application`
+  wires this by default; only a manual `AppOptions` assembly needs the explicit line.
+- Per light: `light.bake = true`, then `light.affectDynamic = false` once every mesh it lights is
+  lightmapped, so it stops contributing to the real-time pass.
+- Per mesh: `render.lightmapped = true` — required for the mesh to receive any light once
+  `affectDynamic` is false, a correctness requirement, not just an optimization —
+  `render.lightmapSizeMultiplier` to size its lightmap, `render.castShadowsLightmap` so lightmapped
+  meshes still shadow each other in the bake.
+- Bake mode: `BAKE_COLOR` for flat diffuse materials; `BAKE_COLORDIR` adds a dominant-light-direction
+  pass for normal- or specular-mapped materials that need one.
+- Baked ambient occlusion, independent of any light: `scene.ambientBake` plus
+  `ambientBakeNumSamples`, `ambientBakeOcclusionBrightness`/`OcclusionContrast`.
+- Run `app.lightmapper.bake(null, mode)` once the scene exists; `null` bakes every lightmapped node.
+
+## Verify UVs before trusting this on real assets
+
+Procedural primitives auto-generate a usable UV set; imported GLB models often do not ship a second,
+non-overlapping UV channel suitable for a lightmap atlas. Read the installed engine's source for
+what its `Lightmapper` actually requires — which UV set it samples, whether it unwraps one for you —
+before assuming a real model will bake correctly. Do not carry a primitive-only test result into
+production assets unchecked.
+
+## Choose the rung by budget, not by default
+
+On-device bake cost scales with baked-node count and lightmap resolution; estimate it against the
+startup budget before choosing a rung. Stay on-device unless:
+
+- the estimated bake time does not fit the startup or first-paint budget on the target device, or
+- the result needs stylized material detail beyond lighting that the runtime `Lightmapper` cannot
+  produce.
+
+Only then move to an offline bake shipped as assets, following the same shape as any other
+generated-asset pipeline: registry-keyed per-asset configs (a new asset is a config change, not new
+pipeline code), a CLI with per-target fast paths, staged size logging, worker-thread parallelism for
+build time, and a coverage self-audit that fails the bake when an expected output is missing or
+empty.
+
+## Keep dynamic objects consistent
+
+Whichever rung you use, dynamic objects moving through baked lighting must not read as ignoring it:
+sample or approximate the baked occlusion/shadow field for them and their attachments so they dim to
+the same levels as the static geometry around them, and ground them with a contact shadow. A
+dynamic object whose custom shading must meet baked maps is `override-shader-chunks` territory.
+
+## Prove it
+
+Capture `verify-pixels`-style frames both in and out of the baked shadow, before and after the
+change, and compare them. A screenshot glanced at once is not proof the bake reproduced the lighting
+it removed.

package/skills/build-hud/SKILL.md

@@ -20,6 +20,8 @@ each transition; never store gameplay truth in the DOM or a UI element.
 
 - Map each overlay to a game state and each indicator to a snapshot field. A transition shows or
   hides overlays; it does not duplicate the state the game already owns (see `manage-game-state`).
+- An indicator that is idle most of the time toggles `enabled` with its visibility; an element left
+  drawing at opacity 0 still costs a draw call every frame (see `reduce-draw-calls`).
 - Anchor and scale elements to the viewport so the layout holds at the target resolution and on
   resize. Verify at the acceptance resolution, not the default window size.
 - Keep copy minimal and legible over the scene: back text with a plate or shadow where the frame is

package/skills/light-scene/SKILL.md

@@ -33,6 +33,16 @@ Keep the two named production integrations visible in the implementation:
 Do not continue to cosmetic tuning while either integration is missing or diagnostics report a
 shader, texture, or framebuffer error.
 
+## 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

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

@@ -0,0 +1,59 @@
+---
+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.
+---
+
+# 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.

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

@@ -0,0 +1,61 @@
+---
+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.
+---
+
+# Cut draw calls, ranked by cost
+
+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
+
+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."
+
+## Rung 1: stop drawing invisible things
+
+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.
+
+## Rung 2: `BatchManager` — merge without touching shaders
+
+`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.
+
+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.

package/skills/verify-pixels/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: verify-pixels
+description: Use when changing PlayCanvas rendering code that must not change the rendered image — draw-call optimization, hardware instancing, shader or material refactors, or asset pipeline swaps — to prove the output unchanged before shipping.
+---
+
+# Prove pixels unchanged
+
+A rendering change that must not alter the image is not proven by eyeballing a screenshot at one
+pose. Build a deterministic capture, compare byte-exact counts across a pose × phase matrix, and
+prove the capture harness itself is trustworthy before trusting what it reports about the change.
+
+## Make the frame deterministic
+
+- 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.
+- Read the rendered pixels with `await device.readPixelsAsync(x, y, w, h, pixels)` against the exact
+  backbuffer, not a re-encoded screenshot (e.g. `canvas.toDataURL`) that can introduce compression or
+  colour-management differences the eye won't catch. In the installed engine this method lives on
+  `WebglGraphicsDevice`, not the base `GraphicsDevice` type, so narrow to it (or branch on
+  `device.isWebGL2`) before calling; a WebGPU project needs its own equivalent readback. If the
+  project already has a screenshot path, hold it to the same rule: fixed size, fixed pose, no lossy
+  step before the byte comparison.
+
+## Build a pose × phase matrix
+
+Single-pose, single-frame proof cannot see everything a rendering refactor can break. Choose at
+least two representative camera poses — angles that would expose a dropped instance, a wrong batch
+bound, or a seam differently — and at least two animation phases, including one mid-animation, not
+only frame zero. Capture every pose × phase pair for the build before the change and the build after
+it, with the same canvas size, camera, and lighting each time.
+
+## Run a same-build control first
+
+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.
+
+## Gate and report
+
+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.