/pixijs-3d

name: pixijs-3d
description: 'Use this skill whenever writing or editing code that uses PixiJS 3D (@pixi/3d): scenes, View3D, Mesh3D, Model3D, lights, shadows, cameras, OrbitCamera, FPSCamera, materials, Material3D, textures, glTF models and animation, BatchedMesh3D instancing, picking and pointer events, post-processing (bloom, SSAO), particles, render to texture, ContainerTexture, custom shader bits, 2D HUD over 3D, Sprite3D billboards, tone mapping and HDR environments, scene graph and transforms (local and world space, reparenting, bounds), vector and quaternion math (Vector3, Quaternion, Matrix4, slerp, Box, Ray, Plane, Frustum), porting a Three.js app. Read it before writing any @pixi/3d code: the API is new and differs from Three.js and from pixi3d, an older, unrelated npm package. Triggers on: @pixi/3d, pixi 3d, PixiJS 3D, View3D, Mesh3D, Model3D, Camera3D, Container3D, 3D scene in pixi, port or convert from Three.js.'
license: MIT

PixiJS 3D (`@pixi/3d`) is PixiJS's 3D extension. A `View3D` is an ordinary 2D display object on the Pixi stage that renders a 3D scene into its rectangle, so 3D and 2D mix freely. The scene hangs from `view.root`, the view owns its `camera`, lights are nodes in the scene, and the Pixi application ticker is the frame loop.

This file gives you the mental model, a complete starting app, and the conventions that catch people. The `references/` folder has one complete, runnable recipe per job; open the one you need.

For a signature or option this skill doesn't cover, fetch the class's API page: `https://3d.pixijs.download/release/docs/<module>.<Class>.html.md` (scene.View3D, materials.Material3D, extras_camera.OrbitCamera, maths.Vector3). To find a class's module, or a guide on a topic, look it up in `https://3d.pixijs.download/release/docs/llms.txt`.

Quick Start

A lit scene with shadows, two primitives, a loaded model and mouse orbit controls. Complete src/main.ts for a Vite + TypeScript app with `pixi.js` and `@pixi/3d` installed.

import {
  CubeGeometry,
  DirectionalLight,
  Material3D,
  Mesh3D,
  Model3D,
  PlaneGeometry,
  SphereGeometry,
  View3D,
} from '@pixi/3d';
import type { Scene3DSource } from '@pixi/3d';
import { OrbitCamera } from '@pixi/3d/extras';
import { Application, Assets } from 'pixi.js';

const app = new Application();
await app.init({ resizeTo: window, backgroundColor: 0x87b7e6, antialias: true });
document.body.appendChild(app.canvas);

// A View3D is a 2D display object that renders a 3D scene into its rectangle.
const view = new View3D({
  autoResize: true,
  shadowQuality: 'medium',
  environment: { skyColor: 0xbcd4f0, groundColor: 0x6b6250, intensity: 0.7 }, // hemisphere fill light
});
app.stage.addChild(view);

// Lights are nodes under view.root. Lights and cameras face their local -Z axis.
const sun = new DirectionalLight({ color: 0xfff2dc, intensity: 3, castShadow: true });
sun.rotation.set(-Math.PI / 4, Math.PI / 6, 0);
view.root.addChild(sun);

// PlaneGeometry lies in XY with a +Z normal: rotate it -90° around X to make a floor.
const ground = new Mesh3D({
  geometry: new PlaneGeometry({ width: 30, height: 30 }),
  material: new Material3D({ baseColor: 0x7f8f6a, roughness: 0.95, metallic: 0 }),
  rotation: { x: -Math.PI / 2, y: 0, z: 0 },
  castShadow: false,
  receiveShadow: true,
});
view.root.addChild(ground);

// Meshes take a geometry and a material. Options objects set position, rotation, scale, shadows.
view.root.addChild(
  new Mesh3D({
    geometry: new CubeGeometry({ width: 2, height: 2, depth: 2 }),
    material: new Material3D({ baseColor: 0xd9534f, roughness: 0.6, metallic: 0 }),
    position: { x: -3, y: 1, z: 0 },
  }),
  new Mesh3D({
    geometry: new SphereGeometry({ radius: 1.2 }),
    material: new Material3D({ baseColor: 0x4a90d9, roughness: 0.3, metallic: 0.2 }),
    position: { x: 3, y: 1.2, z: 0 },
  }),
);

// Models: load a glTF/GLB with Assets, then wrap the source in a Model3D.
const source = await Assets.load<Scene3DSource>('/assets/models/Duck.glb');
// The file's own node transforms set its size (this duck is about 1.6 units); read duck.getLocalBounds() before scaling.
const duck = new Model3D({ source, position: { x: 0, y: 0, z: 3 } });
view.root.addChild(duck);

// The view owns its camera. OrbitCamera (extras) drives it from the mouse.
view.camera.position.set(0, 5, 12);
view.camera.lookAt({ x: 0, y: 1, z: 0 });
new OrbitCamera({ view, enableDamping: true });

// Per-frame work goes on the application ticker.
app.ticker.add((ticker) => {
  duck.rotation.y += 0.01 * ticker.deltaTime;
});

Conventions

• **Scene graph.** Everything 3D goes under `view.root` (a `Container3D`); a mesh on `app.stage` does nothing useful. Nodes have `position`, `rotation` (Euler radians), `quaternion`, `scale`, `visible`, `lookAt(point)`, `addChild`, `traverse(callback)` over a subtree, and bounds via `getLocalBounds()`.
• **Options objects.** Constructors take one options object: `new Mesh3D({ geometry, material, position: { x, y, z }, castShadow, parent: view.root })`. The same values are plain properties afterwards (`mesh.position.set(x, y, z)`).
• **Camera.** `view.camera` is a `Camera3D`: `fov` is the vertical field of view in **degrees** (default 60), `near` 0.1, `far` 1000, `mode` `'perspective'` or `'orthographic'` with `orthographicSize` (half the view's **width** in world units, default 5). Aim it with `position.set(...)` and `lookAt(point)`.
• **Facing.** Cameras and lights look down their local -Z; meshes and glTF models face +Z. A `DirectionalLight` is aimed by its `rotation` (or `lookAt`), not a target.
• **Planes.** `PlaneGeometry` lies in the XY plane with a +Z normal. For a floor, rotate it -π/2 around X.
• **Primitive options.** `CubeGeometry({ width, height, depth })`, `SphereGeometry({ radius })`, `CylinderGeometry({ radiusTop, radiusBottom, height })` (no `radius`), `ConeGeometry({ radius, height })`, `CapsuleGeometry({ radius, height })` (height includes the