npm - create-playcanvas - Versions diffs - 0.3.0 → 0.5.0 - Mend

create-playcanvas 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (114) hide show

package/templates/{vanilla-ts → engine/base}/README.md RENAMED Viewed

@@ -1,4 +1,4 @@
-# PlayCanvas + TypeScript Starter
+# PlayCanvas Engine + TypeScript Starter
 A Vite-powered PlayCanvas Engine project with TypeScript, hot module replacement, ESLint and Prettier.
@@ -9,13 +9,13 @@ Node.js 22.23.2 or later.
 ## Getting started
 ```bash
-npm create playcanvas@latest playcanvas-project -- --template vanilla-ts
+npm create playcanvas@latest playcanvas-project -- --template engine
 cd playcanvas-project
 npm install
 npm run dev
 ```
-Open <http://localhost:5173>. Edit `src/App.ts` to test hot module replacement.
+Open <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
 ## Scripts
@@ -28,24 +28,12 @@ Open <http://localhost:5173>. Edit `src/App.ts` to test hot module replacement.
 | `npm run fmt`       | Check formatting                  |
 | `npm run typecheck` | Run TypeScript checks             |
-## Project structure
-```text
-.
-├── public/
-│   └── environment-map.png
-├── src/
-│   ├── assets/
-│   ├── App.ts
-│   ├── main.ts
-│   └── style.css
-├── eslint.config.mjs
-├── index.html
-└── tsconfig.json
-```
 Run `npm run build` to generate a deployable static site in `dist/`.
+## 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.
 ## Further reading
 - [PlayCanvas Engine manual](https://developer.playcanvas.com/user-manual/engine/)

package/templates/engine/base/eslint.config.mjs ADDED Viewed

@@ -0,0 +1,3 @@
+import typescriptConfig from '@playcanvas/eslint-config/typescript';
+export default [{ ignores: ['.claude', '.agents'] }, ...typescriptConfig];

package/templates/{vanilla-ts → engine/base}/src/vite-env.d.ts RENAMED Viewed

@@ -11,3 +11,9 @@ declare module 'playcanvas/scripts/esm/grid.mjs' {
     export const Grid: typeof Script & (new () => Script);
 }
+declare module 'playcanvas/scripts/esm/sky/procedural-sky.mjs' {
+    import type { Script } from 'playcanvas';
+    export const ProceduralSky: typeof Script & (new () => Script);
+}

package/templates/{vanilla-ts → engine/interactive-sphere}/src/main.ts RENAMED Viewed

@@ -16,7 +16,7 @@ document.querySelector<HTMLDivElement>('#root')!.innerHTML = `
             <img src="${playcanvasLogo}" class="playcanvas-logo logo" alt="PlayCanvas logo" />
           </a>
           <a href="https://www.typescriptlang.org/" target="_blank">
-            <img src="${typescriptLogo}" class="logo vanilla" alt="TypeScript logo" />
+            <img src="${typescriptLogo}" class="logo typescript" alt="TypeScript logo" />
           </a>
         </header>
       </div>

package/templates/{vanilla-ts → engine/interactive-sphere}/src/style.css RENAMED Viewed

@@ -59,7 +59,7 @@ h1 {
     filter: drop-shadow(0 0 2em #646cffaa);
 }
-.logo.vanilla:hover {
+.logo.typescript:hover {
     filter: drop-shadow(0 0 2em #3178c6aa);
 }

package/templates/{vanilla-ts → engine/interactive-sphere}/src/utils.ts RENAMED Viewed

@@ -5,7 +5,6 @@
  * @returns A throttled function
  */
 export const throttle = <T extends unknown[]>(fn: (...args: T) => void, interval = 100) => {
-    // interval in ms
     let last = 0;
     return (...args: T) => {
         const now = Date.now();

package/templates/engine/model-viewer/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <link rel="icon" type="image/png" href="/src/assets/playcanvas.png" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>PlayCanvas + TS</title>
+    </head>
+    <body>
+        <canvas id="application-canvas"></canvas>
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>

package/templates/engine/model-viewer/src/main.ts ADDED Viewed

@@ -0,0 +1,81 @@
+import type { ContainerResource } from 'playcanvas';
+import {
+    AppBase,
+    AppOptions,
+    Asset,
+    AssetListLoader,
+    CameraComponentSystem,
+    ContainerHandler,
+    Entity,
+    FILLMODE_FILL_WINDOW,
+    RESOLUTION_AUTO,
+    RenderComponentSystem,
+    ScriptComponentSystem,
+    TONEMAP_ACES2,
+    TextureHandler,
+    createGraphicsDevice
+} from 'playcanvas';
+import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
+import { ProceduralSky } from 'playcanvas/scripts/esm/sky/procedural-sky.mjs';
+import './style.css';
+// Swap this for your own model - anything you drop in public/ is served from the site root
+const MODEL_URL = '/playcanvas-cube.glb';
+const canvas = document.getElementById('application-canvas') as HTMLCanvasElement;
+const device = await createGraphicsDevice(canvas);
+device.maxPixelRatio = Math.min(window.devicePixelRatio, 2);
+const createOptions = new AppOptions();
+createOptions.graphicsDevice = device;
+createOptions.componentSystems = [RenderComponentSystem, CameraComponentSystem, ScriptComponentSystem];
+createOptions.resourceHandlers = [TextureHandler, ContainerHandler];
+const app = new AppBase(canvas);
+app.init(createOptions);
+// Set the canvas to fill the window and automatically change resolution to be the same as the canvas size
+app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
+app.setCanvasResolution(RESOLUTION_AUTO);
+// Ensure canvas is resized when window changes size
+const resize = () => app.resizeCanvas();
+window.addEventListener('resize', resize);
+app.on('destroy', () => {
+    window.removeEventListener('resize', resize);
+});
+// Load the model before starting, so the first frame already has something in it
+const model = new Asset('model', 'container', { url: MODEL_URL });
+await new Promise<void>((resolve) => {
+    new AssetListLoader([model], app.assets).load(() => resolve());
+});
+app.start();
+// A container asset holds the whole glTF scene, so instantiate it to get an entity hierarchy
+app.root.addChild((model.resource as ContainerResource).instantiateRenderEntity());
+// The procedural sky is both the background and the image-based lighting, so no light or
+// environment map asset is needed. Its default luminance is scene-scale bright, so turn it down to
+// keep the model out of clipping
+const sky = new Entity('sky');
+sky.addComponent('script');
+sky.script?.create(ProceduralSky, {
+    properties: { luminance: 0.2 }
+});
+app.root.addChild(sky);
+// Create camera entity with orbit controls. The sky is HDR, so it needs tone mapping to bring it
+// back into displayable range - without it the whole image blows out to white
+const camera = new Entity('camera');
+camera.addComponent('camera', {
+    toneMapping: TONEMAP_ACES2
+});
+camera.setPosition(0, 0, 3);
+camera.addComponent('script');
+camera.script?.create(CameraControls);
+app.root.addChild(camera);

package/templates/engine/model-viewer/src/style.css ADDED Viewed

@@ -0,0 +1,8 @@
+body {
+    margin: 0;
+    overflow: hidden;
+}
+canvas {
+    display: block;
+}

package/templates/engine/spinning-cube/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <link rel="icon" type="image/png" href="/src/assets/playcanvas.png" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>PlayCanvas + TS</title>
+    </head>
+    <body>
+        <canvas id="application-canvas"></canvas>
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>

package/templates/engine/spinning-cube/src/main.ts ADDED Viewed

@@ -0,0 +1,65 @@
+import {
+    AppBase,
+    AppOptions,
+    CameraComponentSystem,
+    Color,
+    ContainerHandler,
+    Entity,
+    FILLMODE_FILL_WINDOW,
+    LightComponentSystem,
+    RESOLUTION_AUTO,
+    RenderComponentSystem,
+    TextureHandler,
+    createGraphicsDevice
+} from 'playcanvas';
+import './style.css';
+const canvas = document.getElementById('application-canvas') as HTMLCanvasElement;
+const device = await createGraphicsDevice(canvas);
+device.maxPixelRatio = Math.min(window.devicePixelRatio, 2);
+const createOptions = new AppOptions();
+createOptions.graphicsDevice = device;
+createOptions.componentSystems = [RenderComponentSystem, CameraComponentSystem, LightComponentSystem];
+createOptions.resourceHandlers = [TextureHandler, ContainerHandler];
+const app = new AppBase(canvas);
+app.init(createOptions);
+app.start();
+// Set the canvas to fill the window and automatically change resolution to be the same as the canvas size
+app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
+app.setCanvasResolution(RESOLUTION_AUTO);
+// Ensure canvas is resized when window changes size
+const resize = () => app.resizeCanvas();
+window.addEventListener('resize', resize);
+app.on('destroy', () => {
+    window.removeEventListener('resize', resize);
+});
+// Create box entity
+const box = new Entity('cube');
+box.addComponent('render', {
+    type: 'box'
+});
+app.root.addChild(box);
+// Create camera entity
+const camera = new Entity('camera');
+camera.addComponent('camera', {
+    clearColor: new Color(0.5, 0.6, 0.9)
+});
+camera.setPosition(0, 0, 3);
+app.root.addChild(camera);
+// Create directional light entity
+const light = new Entity('light');
+light.addComponent('light');
+light.setEulerAngles(45, 0, 0);
+app.root.addChild(light);
+// Rotate the box according to the delta time since the last frame
+app.on('update', (dt: number) => box.rotate(10 * dt, 20 * dt, 30 * dt));

package/templates/engine/spinning-cube/src/style.css ADDED Viewed

@@ -0,0 +1,8 @@
+body {
+    margin: 0;
+    overflow: hidden;
+}
+canvas {
+    display: block;
+}

package/templates/engine/splat-viewer/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <link rel="icon" type="image/png" href="/src/assets/playcanvas.png" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>PlayCanvas + TS</title>
+    </head>
+    <body>
+        <canvas id="application-canvas"></canvas>
+        <script type="module" src="/src/main.ts"></script>
+    </body>
+</html>

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

@@ -0,0 +1,74 @@
+import {
+    AppBase,
+    AppOptions,
+    Asset,
+    AssetListLoader,
+    CameraComponentSystem,
+    Entity,
+    FILLMODE_FILL_WINDOW,
+    GSplatComponentSystem,
+    GSplatHandler,
+    RESOLUTION_AUTO,
+    ScriptComponentSystem,
+    TextureHandler,
+    createGraphicsDevice
+} from 'playcanvas';
+import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
+import './style.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';
+const canvas = document.getElementById('application-canvas') as HTMLCanvasElement;
+// Antialiasing is disabled - splat rendering is fragment bound, so MSAA costs a lot and adds little
+const device = await createGraphicsDevice(canvas, { antialias: false });
+device.maxPixelRatio = Math.min(window.devicePixelRatio, 2);
+const createOptions = new AppOptions();
+createOptions.graphicsDevice = device;
+createOptions.componentSystems = [CameraComponentSystem, GSplatComponentSystem, ScriptComponentSystem];
+// TextureHandler is required as well as GSplatHandler - a .sog is a container whose splat data is
+// stored as textures, and without it the splat loads but silently renders nothing
+createOptions.resourceHandlers = [TextureHandler, GSplatHandler];
+const app = new AppBase(canvas);
+app.init(createOptions);
+// Set the canvas to fill the window and automatically change resolution to be the same as the canvas size
+app.setCanvasFillMode(FILLMODE_FILL_WINDOW);
+app.setCanvasResolution(RESOLUTION_AUTO);
+// Ensure canvas is resized when window changes size
+const resize = () => app.resizeCanvas();
+window.addEventListener('resize', resize);
+app.on('destroy', () => {
+    window.removeEventListener('resize', resize);
+});
+// Load the splat before starting, so the first frame already has something in it
+const splat = new Asset('splat', 'gsplat', { url: SPLAT_URL });
+await new Promise<void>((resolve) => {
+    new AssetListLoader([splat], app.assets).load(() => resolve());
+});
+app.start();
+// Splats are captured in their own space, so this one needs offsetting and flipping upright
+const toyCat = new Entity('toy cat');
+toyCat.addComponent('gsplat', { asset: splat });
+toyCat.setPosition(0, -0.7, 0);
+toyCat.setEulerAngles(0, 0, 180);
+app.root.addChild(toyCat);
+// Create camera entity with orbit controls
+const camera = new Entity('camera');
+camera.addComponent('camera');
+camera.setPosition(0, 0, 2.5);
+camera.addComponent('script');
+camera.script?.create(CameraControls);
+app.root.addChild(camera);

package/templates/engine/splat-viewer/src/style.css ADDED Viewed

@@ -0,0 +1,8 @@
+body {
+    margin: 0;
+    overflow: hidden;
+}
+canvas {
+    display: block;
+}

package/templates/index.ts CHANGED Viewed

@@ -1,18 +1,50 @@
 import colors from 'picocolors';
-const { cyan, yellow } = colors;
+const { cyan, magenta, yellow } = colors;
 export const TEMPLATES = [
     {
-        name: 'vanilla-ts',
-        display: 'Vanilla',
-        description: 'with PlayCanvas Engine',
+        name: 'engine',
+        display: 'Engine',
+        description: 'with the PlayCanvas Engine API directly',
         color: yellow
     },
     {
-        name: 'react-ts',
+        name: 'react',
         display: 'React',
         description: 'with @playcanvas/react',
         color: cyan
+    },
+    {
+        name: 'web-components',
+        display: 'Web Components',
+        description: 'with @playcanvas/web-components',
+        color: magenta
+    }
+];
+// Every template holds a `base` directory of shared tooling plus one directory per boilerplate,
+// which is copied over the top. Assets a boilerplate needs in every template live once in
+// `_shared/<boilerplate>` and are seeded in first. The first entry is the default.
+export const BOILERPLATES = [
+    {
+        name: 'spinning-cube',
+        display: 'Spinning Cube',
+        description: 'a rotating cube and a light'
+    },
+    {
+        name: 'interactive-sphere',
+        display: 'Interactive Sphere',
+        description: 'orbit controls, a grid and pointer picking'
+    },
+    {
+        name: 'model-viewer',
+        display: 'Model Viewer',
+        description: 'a glTF model, orbit controls and a procedural sky'
+    },
+    {
+        name: 'splat-viewer',
+        display: 'Splat Viewer',
+        description: 'a Gaussian splat and orbit controls'
     }
 ];

package/templates/react/base/.prettierignore ADDED Viewed

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

package/templates/{react-ts → react/base}/README.md RENAMED Viewed

@@ -9,13 +9,13 @@ Node.js 22.23.2 or later.
 ## Getting started
 ```bash
-npm create playcanvas@latest playcanvas-project -- --template react-ts
+npm create playcanvas@latest playcanvas-project -- --template react
 cd playcanvas-project
 npm install
 npm run dev
 ```
-Open <http://localhost:5173>. Edit `src/Scene.tsx` to test hot module replacement.
+Open <http://localhost:5173>. Edit the files under `src/` and save to see the scene update.
 ## Scripts
@@ -28,25 +28,12 @@ Open <http://localhost:5173>. Edit `src/Scene.tsx` to test hot module replacemen
 | `npm run fmt`       | Check formatting                  |
 | `npm run typecheck` | Run TypeScript checks             |
-## Project structure
-```text
-.
-├── public/
-│   └── environment-map.png
-├── src/
-│   ├── assets/
-│   ├── App.tsx
-│   ├── Scene.tsx
-│   └── main.tsx
-├── eslint.config.mjs
-├── index.html
-├── tsconfig.json
-└── vite.config.ts
-```
 Run `npm run build` to generate a deployable static site in `dist/`.
+## 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.
 ## Further reading
 - [PlayCanvas React manual](https://developer.playcanvas.com/user-manual/react/)

package/templates/{react-ts → react/base}/eslint.config.mjs RENAMED Viewed

@@ -2,6 +2,7 @@ import reactConfig from '@playcanvas/eslint-config/react';
 import typescriptConfig from '@playcanvas/eslint-config/typescript';
 export default [
+    { ignores: ['.claude', '.agents'] },
     ...typescriptConfig,
     ...reactConfig,
     {

package/templates/{react-ts → react/base}/src/vite-env.d.ts RENAMED Viewed

@@ -11,3 +11,9 @@ declare module 'playcanvas/scripts/esm/grid.mjs' {
     export const Grid: typeof Script & (new () => Script);
 }
+declare module 'playcanvas/scripts/esm/sky/procedural-sky.mjs' {
+    import type { Script } from 'playcanvas';
+    export const ProceduralSky: typeof Script & (new () => Script);
+}

package/templates/{react-ts → react/interactive-sphere}/src/Scene.tsx RENAMED Viewed

@@ -9,7 +9,6 @@ import { useEffect, useState } from 'react';
  * The Scene renders a sphere with a grid and camera controls
  */
 function Scene({ onClick }: SceneProps) {
-    // Track the hover state and set the color based on the hover state
     const [hovering, setHovering] = useState(false);
     // Set a material color based on the hover state
@@ -21,7 +20,7 @@ function Scene({ onClick }: SceneProps) {
     // Load the environment map
     const { asset: envMap } = useEnvAtlas('/environment-map.png');
-    // change the mouse cursor based on the hover state
+    // Change the mouse cursor based on the hover state
     useEffect(() => {
         document.body.style.cursor = hovering ? 'pointer' : 'default';

package/templates/react/model-viewer/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <link rel="icon" type="image/png" href="/src/assets/playcanvas.png" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>PlayCanvas + React</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>

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

@@ -0,0 +1,43 @@
+import { Application, Container, Entity } from '@playcanvas/react';
+import { Camera, Script } from '@playcanvas/react/components';
+import { useModel } from '@playcanvas/react/hooks';
+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';
+function Model() {
+    const { asset } = useModel(MODEL_URL);
+    // Don't render until the model is loaded
+    if (!asset) return null;
+    return <Container asset={asset} />;
+}
+function App() {
+    return (
+        <Application>
+            {/* The procedural sky is both the background and the image-based lighting, so no
+                light or environment map asset is needed. Its default luminance is scene-scale
+                bright, so turn it down to keep the model out of clipping */}
+            <Entity name="sky">
+                <Script script={ProceduralSky} luminance={0.2} />
+            </Entity>
+            {/* Create a camera entity with orbit controls. The sky is HDR, so it needs tone
+                mapping to bring it back into displayable range - without it the whole image blows
+                out to white */}
+            <Entity name="camera" position={[0, 0, 3]}>
+                <Camera toneMapping={TONEMAP_ACES2} />
+                <Script script={CameraControls} />
+            </Entity>
+            <Model />
+        </Application>
+    );
+}
+export default App;

package/templates/react/model-viewer/src/index.css ADDED Viewed

@@ -0,0 +1,9 @@
+body {
+    margin: 0;
+    overflow: hidden;
+}
+#root {
+    width: 100vw;
+    height: 100vh;
+}

package/templates/react/model-viewer/src/main.tsx ADDED Viewed

@@ -0,0 +1,11 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import './index.css';
+import App from './App.tsx';
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <App />
+    </StrictMode>
+);

package/templates/react/spinning-cube/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <link rel="icon" type="image/png" href="/src/assets/playcanvas.png" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>PlayCanvas + React</title>
+    </head>
+    <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.tsx"></script>
+    </body>
+</html>

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

@@ -0,0 +1,36 @@
+import { Application, Entity } from '@playcanvas/react';
+import { Camera, Light, Render } from '@playcanvas/react/components';
+import { useAppEvent } from '@playcanvas/react/hooks';
+import type { Entity as PcEntity } from 'playcanvas';
+import { useRef } from 'react';
+function Scene() {
+    const cube = useRef<PcEntity>(null);
+    // Rotate the cube according to the delta time since the last frame
+    useAppEvent('update', (dt: number) => cube.current?.rotate(10 * dt, 20 * dt, 30 * dt));
+    return (
+        <>
+            <Entity name="camera" position={[0, 0, 3]}>
+                <Camera clearColor="#8099e6" />
+            </Entity>
+            <Entity name="light" rotation={[45, 0, 0]}>
+                <Light type="directional" />
+            </Entity>
+            <Entity name="cube" ref={cube}>
+                <Render type="box" />
+            </Entity>
+        </>
+    );
+}
+function App() {
+    return (
+        <Application>
+            <Scene />
+        </Application>
+    );
+}
+export default App;