create-playcanvas 0.8.0 → 0.9.0

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

@@ -1,20 +1,7 @@
 # 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-script>
-                <pc-script-instance name="cameraControls" move-speed="4"></pc-script-instance>
-            </pc-script>
-        </pc-entity>
-    </pc-scene>
-</pc-app>
-```
+Expose the selected script as an ES module and register its URL with a `pc-asset` directly under
+`pc-app`. Attach a `pc-script` to the owning `pc-entity`, with a `pc-script-instance` for the class.
 
 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

package/skills/verify-pixels/SKILL.md

@@ -1,50 +1,36 @@
 ---
 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.
+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
 
-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.
+## Choose the gate
+
+- 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.
+
+## Make frames deterministic
+
+- 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.
+
+## Capture and compare
+
+- 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.
+
+Keep harness code out of the shipped bundle.

package/templates/engine/base/package.json

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

package/templates/react/ar-placement/src/App.tsx

@@ -7,7 +7,7 @@ import { useState } from 'react';
 import { ArPlacement } from './ar-placement';
 import './starter.css';
 
-function App() {
+function Scene() {
     const [camera, setCamera] = useState<PcEntity | null>(null);
     const [preview, setPreview] = useState<PcEntity | null>(null);
     const surface = useMaterial({ diffuse: '#474d57' });
@@ -16,29 +16,37 @@ function App() {
 
     return (
         <>
-            <Application graphicsDeviceOptions={{ alpha: true, xrCompatible: true }}>
-                <Entity name="camera" ref={setCamera} position={[3, 2.4, 4]} rotation={[-20, 37, 0]}>
-                    <Camera clearColor="#0d141f" />
+            <Entity name="camera" ref={setCamera} position={[3, 2.4, 4]} rotation={[-20, 37, 0]}>
+                <Camera clearColor="#0d141f" />
+            </Entity>
+            <Entity name="light" rotation={[45, 30, 0]}>
+                <Light type="directional" intensity={2} />
+            </Entity>
+            <Entity name="preview" ref={setPreview}>
+                <Entity name="surface" scale={[4, 0.15, 4]}>
+                    <Render type="cylinder" material={surface} />
+                </Entity>
+                <Entity name="box" position={[0, 0.65, 0]}>
+                    <Render type="box" material={cyan} />
                 </Entity>
-                <Entity name="light" rotation={[45, 30, 0]}>
-                    <Light type="directional" intensity={2} />
+                <Entity name="reticle" position={[0, 0.12, 0]} scale={[1.5, 0.03, 1.5]}>
+                    <Render type="cylinder" material={coral} />
                 </Entity>
-                <Entity name="preview" ref={setPreview}>
-                    <Entity name="surface" scale={[4, 0.15, 4]}>
-                        <Render type="cylinder" material={surface} />
-                    </Entity>
-                    <Entity name="box" position={[0, 0.65, 0]}>
-                        <Render type="box" material={cyan} />
-                    </Entity>
-                    <Entity name="reticle" position={[0, 0.12, 0]} scale={[1.5, 0.03, 1.5]}>
-                        <Render type="cylinder" material={coral} />
-                    </Entity>
+            </Entity>
+            {camera && preview && (
+                <Entity name="placement">
+                    <Script script={ArPlacement} camera={camera} preview={preview} />
                 </Entity>
-                {camera && preview && (
-                    <Entity name="placement">
-                        <Script script={ArPlacement} camera={camera} preview={preview} />
-                    </Entity>
-                )}
+            )}
+        </>
+    );
+}
+
+function App() {
+    return (
+        <>
+            <Application graphicsDeviceOptions={{ alpha: true, xrCompatible: true }}>
+                <Scene />
             </Application>
             <div className="hud">
                 <section className="panel">

package/templates/react/base/package.json

@@ -15,20 +15,20 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "@playcanvas/react": "^0.11.5",
-        "playcanvas": "^2.22.0",
-        "react": "^19.2.8",
-        "react-dom": "^19.2.8"
+        "@playcanvas/react": "^0.11.7",
+        "playcanvas": "^2.22.6",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0"
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
-        "@types/react": "^19.2.18",
-        "@types/react-dom": "^19.2.7",
+        "@types/react": "^19.3.0",
+        "@types/react-dom": "^19.3.0",
         "@vitejs/plugin-react": "^6.1.1",
         "eslint": "^9.39.5",
-        "prettier": "^3.9.6",
+        "prettier": "^3.9.9",
         "typescript": "~6.0.3",
-        "vite": "^8.2.2"
+        "vite": "^8.3.1"
     },
     "engines": {
         "node": ">=22.23.2"

package/templates/react/sprite-game/src/App.tsx

@@ -5,25 +5,33 @@ import { useMaterial } from '@playcanvas/react/hooks';
 import { SpriteGame } from './sprite-game';
 import './starter.css';
 
-function App() {
+function Scene() {
     const dirt = useMaterial({ emissive: '#734729' });
     const grass = useMaterial({ emissive: '#479e57' });
 
+    return (
+        <>
+            <Entity name="camera" position={[0, 0, 10]}>
+                <Camera projection={1} orthoHeight={4.4} clearColor="#5cb9e6" />
+            </Entity>
+            <Entity name="dirt" position={[0, -3.39, 0]} scale={[20, 2.6, 1]}>
+                <Render type="box" material={dirt} />
+            </Entity>
+            <Entity name="grass" position={[0, -2, 0]} scale={[20, 0.18, 1]}>
+                <Render type="box" material={grass} />
+            </Entity>
+            <Entity name="game" position={[0, -2.15, 0]}>
+                <Script script={SpriteGame} />
+            </Entity>
+        </>
+    );
+}
+
+function App() {
     return (
         <>
             <Application>
-                <Entity name="camera" position={[0, 0, 10]}>
-                    <Camera projection={1} orthoHeight={4.4} clearColor="#5cb9e6" />
-                </Entity>
-                <Entity name="dirt" position={[0, -3.39, 0]} scale={[20, 2.6, 1]}>
-                    <Render type="box" material={dirt} />
-                </Entity>
-                <Entity name="grass" position={[0, -2, 0]} scale={[20, 0.18, 1]}>
-                    <Render type="box" material={grass} />
-                </Entity>
-                <Entity name="game" position={[0, -2.15, 0]}>
-                    <Script script={SpriteGame} />
-                </Entity>
+                <Scene />
             </Application>
             <div className="hud">
                 <section className="panel">

package/templates/web-components/base/package.json

@@ -15,15 +15,15 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "@playcanvas/web-components": "^0.21.0",
-        "playcanvas": "^2.22.0"
+        "@playcanvas/web-components": "^0.26.0",
+        "playcanvas": "^2.22.6"
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
         "eslint": "^9.39.5",
-        "prettier": "^3.9.6",
+        "prettier": "^3.9.9",
         "typescript": "~6.0.3",
-        "vite": "^8.2.2"
+        "vite": "^8.3.1"
     },
     "engines": {
         "node": ">=22.23.2"

package/templates/web-components/interactive-sphere/index.html

@@ -9,7 +9,7 @@
     <body>
         <pc-app>
             <!-- Materials are declared once and referenced by id -->
-            <pc-material id="sphere-material" diffuse="lightgrey"></pc-material>
+            <pc-material id="sphere-material" diffuse="#e6edf9"></pc-material>
 
             <pc-scene>
                 <!-- Camera. Orbit controls are attached in src/main.ts -->

package/templates/web-components/splat-viewer/index.html

@@ -8,7 +8,7 @@
     </head>
     <body>
         <!-- Antialiasing is disabled - splat rendering is fragment bound, so MSAA costs a lot and adds little -->
-        <pc-app antialias="false" high-resolution="false">
+        <pc-app antialias="false" max-pixel-ratio="1">
             <!-- Hosted so the template stays small. Capture or edit your own splat at
                  https://superspl.at, then drop the .sog or .ply in public/ and point this at it instead -->
             <pc-asset id="splat" src="https://developer.playcanvas.com/assets/toy-cat.sog"></pc-asset>

package/skills/build-hud/SKILL.md

@@ -1,38 +0,0 @@
----
-name: build-hud
-description: Use when building a PlayCanvas game's on-screen interface such as ready, pause, and victory overlays, menus, and live indicators like gauges, timers, or reload meters, so the interface is driven by game state, readable over the scene, and separate from the 3D hierarchy.
----
-
-# Game interface
-
-A HUD is a view of game state, not a source of it. Render it from the current state each frame or on
-each transition; never store gameplay truth in the DOM or a UI element.
-
-## Choose the UI layer
-
-- Build the interface in the natural UI layer for the surface — a DOM or React overlay, or the
-  Engine `screen` and `element` UI — decided with the `build-app` skill. Keep it outside gameplay
-  model hierarchies, as `assemble-scene` requires.
-- For a screen-space Engine UI, adapt a user-interface example with `find-examples` rather than
-  guessing element anchoring, scaling, and font handling.
-
-## Drive from state
-
-- 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
-  bright, and unify interface colour with the scene's grade from `light-scene`.
-
-## Prove it reflects state
-
-Drive real input through every transition and confirm with screenshots that the correct overlay
-shows and each indicator tracks the snapshot — a reload meter empties and refills, a timer advances,
-a menu appears only in its state. A saved filepath or a visibility flag is not visual evidence;
-inspect the returned pixels as the local agent guide requires.
-
-Choose the authoring surface with the `build-app` skill and build the interface through its own UI
-primitives before reaching into the Engine.

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

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