create-playcanvas 0.3.0 → 0.4.0

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

@@ -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

@@ -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

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

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

@@ -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

@@ -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

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

package/templates/index.ts

@@ -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-ts → react/base}/README.md

@@ -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,23 +28,6 @@ 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/`.
 
 ## Further reading

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

@@ -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

@@ -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

@@ -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

@@ -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

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

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

@@ -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

@@ -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

@@ -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;

package/templates/react/spinning-cube/src/index.css

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

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

@@ -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/splat-viewer/index.html

@@ -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/splat-viewer/src/App.tsx

@@ -0,0 +1,39 @@
+import { Application, Entity } from '@playcanvas/react';
+import { Camera, GSplat, Script } from '@playcanvas/react/components';
+import { useSplat } from '@playcanvas/react/hooks';
+import { CameraControls } from 'playcanvas/scripts/esm/camera-controls.mjs';
+
+// 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';
+
+function Splat() {
+    const { asset } = useSplat(SPLAT_URL);
+
+    // Don't render until the splat is loaded
+    if (!asset) return null;
+
+    // Splats are captured in their own space, so this one needs offsetting and flipping upright
+    return (
+        <Entity name="toy cat" position={[0, -0.7, 0]} rotation={[0, 0, 180]}>
+            <GSplat asset={asset} />
+        </Entity>
+    );
+}
+
+// Antialiasing is disabled - splat rendering is fragment bound, so MSAA costs a lot and adds little
+function App() {
+    return (
+        <Application graphicsDeviceOptions={{ antialias: false }}>
+            {/* Create a camera entity with orbit controls */}
+            <Entity name="camera" position={[0, 0, 2.5]}>
+                <Camera />
+                <Script script={CameraControls} />
+            </Entity>
+
+            <Splat />
+        </Application>
+    );
+}
+
+export default App;

package/templates/react/splat-viewer/src/index.css

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

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

@@ -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/web-components/base/README.md

@@ -0,0 +1,66 @@
+# PlayCanvas Web Components + TypeScript Starter
+
+A Vite-powered `@playcanvas/web-components` project with TypeScript, ESLint and Prettier. The scene is
+declared as HTML custom elements in `index.html`.
+
+## Prerequisites
+
+Node.js 22.23.2 or later.
+
+## Getting started
+
+```bash
+npm create playcanvas@latest playcanvas-project -- --template web-components
+cd playcanvas-project
+npm install
+npm run dev
+```
+
+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 `npm run build` to generate a deployable static site in `dist/`.
+
+## How it fits together
+
+`index.html` holds the scene: `<pc-app>` wraps a `<pc-scene>` of `<pc-entity>` elements, each with
+components such as `<pc-camera>`, `<pc-light>` and `<pc-render>` attached. Entities are real DOM elements,
+so `document.querySelector` reaches them and `setAttribute` changes them.
+
+`src/main.ts` covers the two things HTML alone cannot do:
+
+- **Attaching engine scripts.** `<pc-script name="...">` resolves scripts that `<pc-asset>` fetched at
+  runtime. Scripts imported through the bundler — like `CameraControls` and `Grid` here — are attached
+  through the entity instead, reached via `whenReady()` and the element's `.entity` property.
+- **Responding to pointer input.** `<pc-app>` picks whatever is under the pointer and dispatches an
+  ordinary `PointerEvent` on the `<pc-entity>` it hit, so `addEventListener('pointerup', ...)` works on a
+  3D entity exactly as it would on a `<button>`. Events are only generated for entities that have a
+  listener.
+
+## Editor support
+
+The package ships a Custom Elements Manifest, which gives tag and attribute completion in `index.html`.
+JetBrains IDEs pick it up automatically. For VS Code, add to `.vscode/settings.json`:
+
+```json
+{
+    "html.customData": ["./node_modules/@playcanvas/web-components/dist/vscode.html-custom-data.json"]
+}
+```
+
+## Further reading
+
+- [PlayCanvas Web Components manual](https://developer.playcanvas.com/user-manual/web-components/)
+- [Web Components examples](https://playcanvas.github.io/web-components/examples)
+- [Vite documentation](https://vite.dev/)
+- [TypeScript documentation](https://www.typescriptlang.org/docs/)

package/templates/web-components/base/_gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

package/templates/web-components/base/eslint.config.mjs

@@ -0,0 +1,3 @@
+import typescriptConfig from '@playcanvas/eslint-config/typescript';
+
+export default typescriptConfig;