create-playcanvas 0.11.0 → 0.12.0

package/templates/engine/splat-viewer/src/main.ts

@@ -16,7 +16,7 @@ import {
 } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 
-import './style.css';
+import './starter.css';
 
 // 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

package/templates/engine/third-person-controller/src/main.ts

@@ -42,9 +42,8 @@ const PINE_LAYERS: [number, number, number][] = [
 ];
 
 WasmModule.setConfig('Ammo', {
-    glueUrl: '/ammo/ammo.wasm.js',
-    wasmUrl: '/ammo/ammo.wasm.wasm',
-    fallbackUrl: '/ammo/ammo.js'
+    glueUrl: './ammo/ammo.wasm.js',
+    wasmUrl: './ammo/ammo.wasm.wasm'
 });
 await new Promise<void>((resolve) => {
     WasmModule.getInstance('Ammo', () => resolve());

package/templates/engine/web-lens/vite.config.ts

@@ -19,7 +19,10 @@ export default defineConfig({
         // npm run package zips this folder and writes the zip beside it, inside the ignored dist/
         outDir: 'dist/lens',
         // source maps only add to the 8 MB upload
-        sourcemap: false
+        sourcemap: false,
+        // a PlayCanvas build is 1-2.5 MB minified, nearly all of it engine code the first frame needs,
+        // so warn only for chunks well past that rather than at Vite's 500 kB default
+        chunkSizeWarningLimit: 3000
     },
     preview: {
         // npm run start serves the build under the Lens rules, so a request for anything outside

package/templates/react/base/AGENTS.md

@@ -0,0 +1,41 @@
+# AGENTS.md
+
+A PlayCanvas app in TypeScript and React, built with Vite. The scene is declared in JSX with `@playcanvas/react`, which drives the PlayCanvas Engine. `README.md` describes the starter this project began from and how to control it.
+
+## Commands
+
+- `npm install` installs dependencies.
+- `npm run dev` starts the dev server, usually at <http://localhost:5173>, with hot reload and the PlayCanvas Inspector.
+- `npm run typecheck` checks types.
+- `npm run lint` runs ESLint, and `npm run lint:fix` fixes what it can.
+- `npm run fmt` checks formatting, and `npm run fmt:fix` applies Prettier.
+- `npm run build` builds the production site into `dist/`, and `npm run start` serves it.
+
+## Layout
+
+- `index.html` is the page, with the `#root` element React renders into.
+- `src/main.tsx` mounts `<App />` inside `<StrictMode>`.
+- `src/App.tsx` holds the scene: an `<Application>` of `<Entity>` elements, with components such as `<Camera>`, `<Light>` and `<Render>` inside them.
+- `src/starter.css` styles the page and the starter's panels.
+- `src/inspector.ts` loads the Inspector. `vite.config.ts` adds it in the dev server only, so production builds leave it out.
+- `public/` holds files copied into the build as they are, such as models and textures.
+
+## Conventions
+
+- Import `<Application>` and `<Entity>` from `@playcanvas/react`, components from `@playcanvas/react/components` and hooks such as `useApp`, `useAppEvent` and `useModel` from `@playcanvas/react/hooks`. Engine classes and types come from `playcanvas`.
+- Reach an entity's engine object through a `ref`, typed with `Entity` from `playcanvas`.
+- Do per-frame work in `useAppEvent('update', (dt) => ...)` on engine objects, not in React state, which would re-render every frame.
+- In development, `<StrictMode>` mounts each component twice, so anything an effect adds to the engine, such as an entity, a script or an event listener, needs a cleanup that removes it.
+- Builds use relative URLs (`base: './'` in `vite.config.ts`), so they run from any folder. Load files in `public/` with relative paths such as `./model.glb`, not `/model.glb`.
+- The engine ships ready-made scripts, such as camera controls and character controllers, under `playcanvas/scripts/esm/`. Use one before writing the same behavior yourself.
+- `node_modules/playcanvas/build/playcanvas.d.ts` documents the installed engine's API.
+- TypeScript is strict, and unused locals and parameters are errors.
+
+## Checking your work
+
+- Run `npm run typecheck`, `npm run lint` and `npm run build` before you finish. All three must pass.
+- To see the result, run `npm run dev` and open the page in a browser. The console should show `Powered by PlayCanvas` and no errors. Press the backquote key for the Inspector, which shows the hierarchy, assets, materials, textures, frame graph and physics. <kbd>F9</kbd> pauses and <kbd>F10</kbd> steps a frame.
+
+## Agent skills
+
+`.claude/skills/` and `.agents/skills/` hold PlayCanvas skills for coding agents. Use them rather than working from memory: `build-app` when restructuring the app, `find-examples` for a feature the project doesn't use yet, `reuse-scripts` before writing a behavior, `inspect-glb` before placing a model, `inspect-runtime` to read state from the running app, and `verify-pixels` to prove a refactor leaves the image unchanged.

package/templates/react/base/README.md

@@ -9,8 +9,6 @@ Node.js 22.23.2 or later.
 ## Getting started
 
 ```bash
-npm create playcanvas@latest playcanvas-project -- --format react
-cd playcanvas-project
 npm install
 npm run dev
 ```
@@ -23,16 +21,22 @@ Open <http://localhost:5173>. Edit the files under `src/` and save to see the sc
 
 ## Scripts
 
-| Command             | Description                       |
-| ------------------- | --------------------------------- |
-| `npm run dev`       | Start the Vite development server |
-| `npm run build`     | Build for production              |
-| `npm run start`     | Preview the production build      |
-| `npm run lint`      | Run ESLint                        |
-| `npm run fmt`       | Check formatting                  |
-| `npm run typecheck` | Run TypeScript checks             |
+Run these with `npm run <script>`:
 
-Run `npm run build` to generate a deployable static site in `dist/`.
+| Script      | Description                       |
+| ----------- | --------------------------------- |
+| `dev`       | Start the Vite development server |
+| `build`     | Build for production              |
+| `start`     | Preview the production build      |
+| `lint`      | Run ESLint                        |
+| `fmt`       | Check formatting                  |
+| `typecheck` | Run TypeScript checks             |
+
+Run `npm run build` to generate a deployable static site in `dist/`. Its paths are relative, so it runs from any folder, such as a GitHub Pages project site or an itch.io upload.
+
+## Coding agents
+
+`AGENTS.md` gives coding agents such as Claude Code, Codex and Cursor this project's commands, layout, conventions and checks. `CLAUDE.md` imports it for Claude Code.
 
 ## Agent skills
 

package/templates/react/base/package.json

@@ -22,7 +22,7 @@
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
-        "@playcanvas/inspector": "^0.3.0",
+        "@playcanvas/inspector": "^0.4.0",
         "@types/react": "^19.3.0",
         "@types/react-dom": "^19.3.0",
         "@vitejs/plugin-react": "^6.1.2",

package/templates/react/base/vite.config.ts

@@ -3,6 +3,14 @@ import { defineConfig } from 'vite';
 
 // https://vite.dev/config/
 export default defineConfig({
+    // Relative URLs, so the build runs wherever it's served from: a domain root, a subpath such as
+    // GitHub Pages or itch.io, or a Snapchat Web Lens
+    base: './',
+    build: {
+        // A PlayCanvas build is 1-2.5 MB minified (300-600 kB gzipped), nearly all of it engine code the
+        // first frame needs, so warn only for chunks well past that rather than at Vite's 500 kB default
+        chunkSizeWarningLimit: 3000
+    },
     plugins: [
         react(),
         {

package/templates/react/interactive-sphere/src/App.tsx

@@ -1,19 +1,18 @@
 import { Application } from '@playcanvas/react';
 import { useState } from 'react';
 
-import './App.css';
+import './counter.css';
 import Scene from './Scene';
+import './starter.css';
 
 function App() {
     const [count, setCount] = useState(0);
 
     return (
         <>
-            <div className="full-bleed">
-                <Application className="playcanvas-app">
-                    <Scene onClick={() => setCount((count) => count + 1)} />
-                </Application>
-            </div>
+            <Application className="playcanvas-app">
+                <Scene onClick={() => setCount((count) => count + 1)} />
+            </Application>
             <p className="counter">Click count: {count}</p>
         </>
     );

package/templates/react/interactive-sphere/src/Scene.tsx

@@ -18,7 +18,7 @@ function Scene({ onClick }: SceneProps) {
     const material = useMaterial({ diffuse });
 
     // Load the environment map
-    const { asset: envMap } = useEnvAtlas('/environment-map.png');
+    const { asset: envMap } = useEnvAtlas('./environment-map.png');
 
     // Change the mouse cursor based on the hover state
     useEffect(() => {

package/templates/react/model-viewer/src/App.tsx

@@ -5,8 +5,10 @@ import { TONEMAP_ACES2 } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
 
-// Swap this for your own model - anything you drop in public/ is served from the site root
-const MODEL_URL = '/playcanvas-cube.glb';
+import './starter.css';
+
+// Swap this for your own model - files in public/ are served next to index.html, so use a ./ path
+const MODEL_URL = './playcanvas-cube.glb';
 
 function Model() {
     const { asset } = useModel(MODEL_URL);

package/templates/react/spinning-cube/src/App.tsx

@@ -4,6 +4,8 @@ import { useAppEvent } from '@playcanvas/react/hooks';
 import type { Entity as PcEntity } from 'playcanvas';
 import { useRef } from 'react';
 
+import './starter.css';
+
 function Scene() {
     const cube = useRef<PcEntity>(null);
 

package/templates/react/splat-viewer/src/App.tsx

@@ -3,6 +3,8 @@ import { Camera, GSplat, Script } from '@playcanvas/react/components';
 import { useSplat } from '@playcanvas/react/hooks';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 
+import './starter.css';
+
 // 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
 const SPLAT_URL = 'https://developer.playcanvas.com/assets/toy-cat.sog';

package/templates/react/web-lens/vite.config.ts

@@ -20,7 +20,10 @@ export default defineConfig({
         // npm run package zips this folder and writes the zip beside it, inside the ignored dist/
         outDir: 'dist/lens',
         // source maps only add to the 8 MB upload
-        sourcemap: false
+        sourcemap: false,
+        // a PlayCanvas build is 1-2.5 MB minified, nearly all of it engine code the first frame needs,
+        // so warn only for chunks well past that rather than at Vite's 500 kB default
+        chunkSizeWarningLimit: 3000
     },
     preview: {
         // npm run start serves the build under the Lens rules, so a request for anything outside

package/templates/web-components/base/AGENTS.md

@@ -0,0 +1,39 @@
+# AGENTS.md
+
+A PlayCanvas app in TypeScript, built with Vite. The scene is declared in HTML with `@playcanvas/web-components`, custom elements that drive the PlayCanvas Engine. `README.md` describes the starter this project began from and how to control it.
+
+## Commands
+
+- `npm install` installs dependencies.
+- `npm run dev` starts the dev server, usually at <http://localhost:5173>, with hot reload and the PlayCanvas Inspector.
+- `npm run typecheck` checks types.
+- `npm run lint` runs ESLint, and `npm run lint:fix` fixes what it can.
+- `npm run fmt` checks formatting, and `npm run fmt:fix` applies Prettier.
+- `npm run build` builds the production site into `dist/`, and `npm run start` serves it.
+
+## Layout
+
+- `index.html` holds the scene: `<pc-app>` wraps a `<pc-scene>` of `<pc-entity>` elements, with components such as `<pc-camera>`, `<pc-light>` and `<pc-render>` inside them.
+- `src/main.ts` does what HTML can't, such as attaching scripts and handling input.
+- `src/starter.css` styles the page and the starter's panels.
+- `src/inspector.ts` loads the Inspector. `vite.config.ts` adds it in the dev server only, so production builds leave it out.
+- `public/` holds files copied into the build as they are, such as models and textures.
+
+## Conventions
+
+- Attribute values are strings, such as `position="0 0 3"` and `clear-color="#8099e6"`. `node_modules/@playcanvas/web-components/dist/custom-elements.json` lists every element and its attributes.
+- Attach a script that's imported through the bundler in `src/main.ts`, not with `<pc-script-instance name="...">`, which only finds scripts that a `<pc-asset>` fetched at runtime. Wait for the element with `whenReady()`, then add the script through its `.entity`.
+- `<pc-app>` dispatches ordinary pointer events, such as `pointerup`, on the `<pc-entity>` under the pointer, so listen for them on the element. Only entities with a listener receive them.
+- Builds use relative URLs (`base: './'` in `vite.config.ts`), so they run from any folder. Load files in `public/` with relative paths such as `./model.glb`, not `/model.glb`.
+- The engine ships ready-made scripts, such as camera controls and character controllers, under `playcanvas/scripts/esm/`. Use one before writing the same behavior yourself.
+- `node_modules/playcanvas/build/playcanvas.d.ts` documents the installed engine's API.
+- TypeScript is strict, and unused locals and parameters are errors.
+
+## Checking your work
+
+- Run `npm run typecheck`, `npm run lint` and `npm run build` before you finish. All three must pass.
+- To see the result, run `npm run dev` and open the page in a browser. The console should show `Powered by PlayCanvas` and no errors. Press the backquote key for the Inspector, which shows the hierarchy, assets, materials, textures, frame graph and physics. <kbd>F9</kbd> pauses and <kbd>F10</kbd> steps a frame.
+
+## Agent skills
+
+`.claude/skills/` and `.agents/skills/` hold PlayCanvas skills for coding agents. Use them rather than working from memory: `build-app` when restructuring the app, `find-examples` for a feature the project doesn't use yet, `reuse-scripts` before writing a behavior, `inspect-glb` before placing a model, `inspect-runtime` to read state from the running app, and `verify-pixels` to prove a refactor leaves the image unchanged.

package/templates/web-components/base/README.md

@@ -10,8 +10,6 @@ Node.js 22.23.2 or later.
 ## Getting started
 
 ```bash
-npm create playcanvas@latest playcanvas-project -- --format web-components
-cd playcanvas-project
 npm install
 npm run dev
 ```
@@ -24,16 +22,18 @@ Open <http://localhost:5173>. Edit `index.html` to change the scene.
 
 ## Scripts
 
-| Command             | Description                       |
-| ------------------- | --------------------------------- |
-| `npm run dev`       | Start the Vite development server |
-| `npm run build`     | Build for production              |
-| `npm run start`     | Preview the production build      |
-| `npm run lint`      | Run ESLint                        |
-| `npm run fmt`       | Check formatting                  |
-| `npm run typecheck` | Run TypeScript checks             |
+Run these with `npm run <script>`:
 
-Run `npm run build` to generate a deployable static site in `dist/`.
+| Script      | Description                       |
+| ----------- | --------------------------------- |
+| `dev`       | Start the Vite development server |
+| `build`     | Build for production              |
+| `start`     | Preview the production build      |
+| `lint`      | Run ESLint                        |
+| `fmt`       | Check formatting                  |
+| `typecheck` | Run TypeScript checks             |
+
+Run `npm run build` to generate a deployable static site in `dist/`. Its paths are relative, so it runs from any folder, such as a GitHub Pages project site or an itch.io upload.
 
 ## How it fits together
 
@@ -62,6 +62,10 @@ JetBrains IDEs pick it up automatically. For VS Code, add to `.vscode/settings.j
 }
 ```
 
+## Coding agents
+
+`AGENTS.md` gives coding agents such as Claude Code, Codex and Cursor this project's commands, layout, conventions and checks. `CLAUDE.md` imports it for Claude Code.
+
 ## Agent skills
 
 This project includes [`@playcanvas/skills`](https://github.com/playcanvas/skills) under `.claude/skills/` and `.agents/skills/`, so Claude Code, Codex and Cursor pick up PlayCanvas-specific workflows automatically.

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

@@ -15,12 +15,12 @@
         "typecheck": "tsc --noEmit"
     },
     "dependencies": {
-        "@playcanvas/web-components": "^0.28.0",
+        "@playcanvas/web-components": "^0.28.1",
         "playcanvas": "^2.23.3"
     },
     "devDependencies": {
         "@playcanvas/eslint-config": "3.0.0-beta.8",
-        "@playcanvas/inspector": "^0.3.0",
+        "@playcanvas/inspector": "^0.4.0",
         "eslint": "^9.39.5",
         "prettier": "^3.9.10",
         "typescript": "~6.0.3",

package/templates/web-components/base/vite.config.ts

@@ -2,6 +2,14 @@ import { defineConfig } from 'vite';
 
 // https://vite.dev/config/
 export default defineConfig({
+    // Relative URLs, so the build runs wherever it's served from: a domain root, a subpath such as
+    // GitHub Pages or itch.io, or a Snapchat Web Lens
+    base: './',
+    build: {
+        // A PlayCanvas build is 1-2.5 MB minified (300-600 kB gzipped), nearly all of it engine code the
+        // first frame needs, so warn only for chunks well past that rather than at Vite's 500 kB default
+        chunkSizeWarningLimit: 3000
+    },
     plugins: [
         {
             // Dev only: install the PlayCanvas Inspector before the app starts (press ` to toggle)

package/templates/web-components/first-person-controller/index.html

@@ -14,12 +14,7 @@
             <pc-material id="green-material" diffuse="#2e6638" emissive="#09140b" gloss="0.2"></pc-material>
             <pc-material id="wood-material" diffuse="#7a451a" emissive="#180e05" gloss="0.2"></pc-material>
             <pc-material id="metal-material" diffuse="#475461" emissive="#0e1113" gloss="0.5"></pc-material>
-            <pc-wasm
-                name="Ammo"
-                glue="/ammo/ammo.wasm.js"
-                wasm="/ammo/ammo.wasm.wasm"
-                fallback="/ammo/ammo.js"
-            ></pc-wasm>
+            <pc-wasm name="Ammo" glue="./ammo/ammo.wasm.js" wasm="./ammo/ammo.wasm.wasm"></pc-wasm>
             <pc-scene>
                 <pc-entity name="light" rotation="50 30 0"
                     ><pc-light

package/templates/web-components/interactive-sphere/src/main.ts

@@ -4,8 +4,8 @@ import { Asset, TEXTURETYPE_RGBP } from 'playcanvas';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { Grid } from 'playcanvas/scripts/esm/grid.mjs';
 
+import './counter.css';
 import './starter.css';
-import './style.css';
 
 const HOVER_COLOR = '#40ccff';
 const DEFAULT_COLOR = '#e6edf9';
@@ -25,7 +25,7 @@ const app = appElement.app!;
 const envAtlas = new Asset(
     'env-atlas',
     'texture',
-    { url: '/environment-map.png' },
+    { url: './environment-map.png' },
     {
         type: TEXTURETYPE_RGBP,
         mipmaps: false

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

@@ -8,8 +8,8 @@
     </head>
     <body>
         <pc-app>
-            <!-- Swap this for your own model - anything you drop in public/ is served from the site root -->
-            <pc-asset id="model" src="/playcanvas-cube.glb"></pc-asset>
+            <!-- Swap this for your own model - files in public/ are served next to index.html, so use a ./ path -->
+            <pc-asset id="model" src="./playcanvas-cube.glb"></pc-asset>
 
             <pc-scene>
                 <!-- Camera. Orbit controls are attached in src/main.ts. The sky is HDR, so it needs

package/templates/web-components/model-viewer/src/main.ts

@@ -4,7 +4,6 @@ import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
 
 import './starter.css';
-import './style.css';
 
 // The camera is awaited as <pc-camera> rather than the <pc-entity> holding it - an entity becomes
 // ready before its component children do, and CameraControls needs the camera component to exist

package/templates/web-components/physics-playground/index.html

@@ -8,12 +8,7 @@
     </head>
     <body>
         <pc-app>
-            <pc-wasm
-                name="Ammo"
-                glue="/ammo/ammo.wasm.js"
-                wasm="/ammo/ammo.wasm.wasm"
-                fallback="/ammo/ammo.js"
-            ></pc-wasm>
+            <pc-wasm name="Ammo" glue="./ammo/ammo.wasm.js" wasm="./ammo/ammo.wasm.wasm"></pc-wasm>
             <pc-material id="floor-material" diffuse="#2e333d" gloss="0.2"></pc-material>
             <pc-material id="cyan-material" diffuse="#29ade6" gloss="0.45"></pc-material>
             <pc-material id="coral-material" diffuse="#f25738" gloss="0.45"></pc-material>

package/templates/web-components/spinning-cube/src/main.ts

@@ -3,7 +3,6 @@ import { whenReady } from '@playcanvas/web-components';
 import { Script } from 'playcanvas';
 
 import './starter.css';
-import './style.css';
 
 class Rotate extends Script {
     static scriptName = 'rotate';

package/templates/web-components/splat-viewer/src/main.ts

@@ -2,7 +2,6 @@ import { whenReady } from '@playcanvas/web-components';
 import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
 
 import './starter.css';
-import './style.css';
 
 // The camera is awaited as <pc-camera> rather than the <pc-entity> holding it - an entity becomes
 // ready before its component children do, and CameraControls needs the camera component to exist

package/templates/web-components/third-person-controller/index.html

@@ -16,12 +16,7 @@
             <pc-material id="shirt-material" diffuse="#268bd2"></pc-material>
             <pc-material id="skin-material" diffuse="#c78759"></pc-material>
             <pc-material id="pants-material" diffuse="#2e4a85"></pc-material>
-            <pc-wasm
-                name="Ammo"
-                glue="/ammo/ammo.wasm.js"
-                wasm="/ammo/ammo.wasm.wasm"
-                fallback="/ammo/ammo.js"
-            ></pc-wasm>
+            <pc-wasm name="Ammo" glue="./ammo/ammo.wasm.js" wasm="./ammo/ammo.wasm.wasm"></pc-wasm>
             <pc-scene>
                 <pc-entity name="camera" position="0 3 6"><pc-camera clear-color="#7ab8e6"></pc-camera></pc-entity>
                 <pc-entity name="light" rotation="45 30 0"

package/templates/web-components/web-lens/vite.config.ts

@@ -19,7 +19,10 @@ export default defineConfig({
         // npm run package zips this folder and writes the zip beside it, inside the ignored dist/
         outDir: 'dist/lens',
         // source maps only add to the 8 MB upload
-        sourcemap: false
+        sourcemap: false,
+        // a PlayCanvas build is 1-2.5 MB minified, nearly all of it engine code the first frame needs,
+        // so warn only for chunks well past that rather than at Vite's 500 kB default
+        chunkSizeWarningLimit: 3000
     },
     preview: {
         // npm run start serves the build under the Lens rules, so a request for anything outside