Skip to main content

PixiJS 3D

Every template comes with PixiJS 3D, the @pixi/3d package. Its View3D is a 2D display object that draws a 3D scene into its rectangle, so 3D and 2D share one stage. Each app template draws a lit, spinning cube behind its 2D content to show this.

How it's set up​

  • @pixi/3d is a dependency next to pixi.js. It needs pixi.js 8.23.0 or later, which the templates install.
  • Importing @pixi/3d registers it with PixiJS. app.init then loads the 3D code for the renderer it starts, WebGL or WebGPU. Vite, webpack and the import map keep each in its own file, so the browser downloads only the one it uses. The esbuild template bundles both into bundle.js.
  • Import @pixi/3d before app.init runs. A View3D on an app that started earlier draws nothing. That happens when 3D code is in a file that loads later, so the game templates import @pixi/3d at the top of src/main.ts. Keep that import when you split your game into files that load on demand.
  • The import map template maps @pixi/3d and @pixi/3d/extras to jsDelivr, next to pixi.js.
  • The extension template lists @pixi/3d as a peer dependency, like pixi.js.

The cube​

The bundler templates draw the cube in src/main.ts, the React template in the SpinningCube component in src/App.tsx, and the game templates in src/cube.ts. This is the bundler version:

src/main.ts
const view = new View3D({
autoResize: true,
environment: { skyColor: 0xc9d6ff, groundColor: 0x3a2f45 },
});

const cube = new Mesh3D({
geometry: new CubeGeometry(),
material: new Material3D({ baseColor: 0xe72264 }),
});

const sun = new DirectionalLight({ intensity: 3 });

sun.position.set(-3, 5, 2);
sun.lookAt(cube.position);

view.root.addChild(cube, sun);
view.camera.position.set(0, 1.6, 3);
view.camera.lookAt(cube.position);
  • autoResize makes the view fill the screen, and keeps it filling the screen when the window resizes. The game templates give the view a fixed width, height and anchor instead, and place it like a sprite. See the starter game.
  • environment is soft light from every direction: skyColor lights surfaces that face up, and groundColor lights surfaces that face down.
  • Everything 3D goes under view.root, including lights. The view owns its camera.
  • Lights and cameras face along their -Z axis. lookAt turns them to face a point.
  • The view is added to the stage before the bunny, so the bunny draws in front of it. A 2D object added after a view always draws over it. The view also catches pointer events anywhere on screen, so put clickable 2D objects in front of it.
  • The camera sits above and in front of the cube, so you see its top as well as its sides.
  • The app's ticker turns the cube every frame.

Every app template passes antialias: true to app.init, which smooths the edges of 3D shapes. View3D has no antialias option of its own.

Extras​

@pixi/3d/extras has optional pieces, such as camera controls, particles, toon shading and post-processing effects like bloom. For example, to orbit the camera around the cube when you drag, import OrbitCamera and create one after the view.camera lines:

import { OrbitCamera } from "@pixi/3d/extras";

new OrbitCamera({ view });

OrbitCamera reads the view's pointer events. In a game template, change eventMode in src/cube.ts to "static" first. In the React template, keep it in a const and call its destroy() in the effect's cleanup, or each hot reload adds another controller.

TypeScript​

The app templates' tsconfig.json uses the DOM library, which in TypeScript 7 leaves out some WebGPU constants, such as GPUTextureUsage. If your code uses them, install @types/web and use it in place of DOM and DOM.Iterable, as the PixiJS 3D README explains.

Coding agents​

@pixi/3d comes with an agent skill in node_modules/@pixi/3d/skills/pixijs-3d. It has a complete example for each job, such as loading glTF models, shadows, picking and particles. Point your coding agent at that folder before it writes 3D code.

Remove it​

If your project is 2D only:

  1. Delete the cube code and its @pixi/3d imports:
    • In a bundler template, the code from new View3D to the camera lines in src/main.ts or src/main.js, view in app.stage.addChild, and the cube line in the ticker.
    • In the React template, SpinningCube and <SpinningCube />, the environment constant, View3D in extend, and src/pixi-react.d.ts.
    • In a game template, src/cube.ts, and in src/scene.ts the createSpinningCube import and the code that adds the cube.
  2. In a game template, delete import "@pixi/3d" from src/main.ts.
  3. Run npm uninstall @pixi/3d. In the import map template, delete the two @pixi/3d entries from index.html.

Only code that imports @pixi/3d adds it to a build, so steps 1 and 2 are what make the build smaller.

Learn more​

The PixiJS 3D repository has a quick start, guides for each part, and examples.