Introduction

PixiJS 3D, the @pixi/3d package, draws 3D scenes in a PixiJS application. A View3D holds the scene. It's a display object you add to the stage like a sprite. Hello cube shows the smallest scene, a cube and a light in a view.

How 2D and 3D fit together

2D content later in the display list draws over the scene. 2D content earlier in the list shows behind it, unless you give the view a background. By default the view catches pointer events anywhere in its rectangle, so the user can't click, tap or hover 2D content behind it. Interaction shows the ways around this.

The scene inside a view is its own tree of Container3D nodes under the view's root. A 2D display object can't go in that tree, and a 3D node can't go on the stage. To show 2D content on a 3D surface, draw it into a ContainerTexture (Rendering 2D into 3D). To pin a 2D label over a 3D object, use worldToScreen (View3D and 2D content).

Inside the scene, +Y points up, and the defaults expect one unit to be a metre, not a pixel. A camera draws nothing past its far distance, 1000 units by default, so it cuts off a scene built at pixel sizes.

Features

Some parts come from @pixi/3d/extras, another entry point that Installation explains.

• Scene graph. Meshes, models, lights and cameras are all nodes. Each has a position, rotation and scale relative to its parent. See Scene graph and transforms and Scene objects.
• Meshes. A Mesh3D draws a geometry with a material. The geometry is the shape, and the material is how its surface looks. Built-in geometries such as CubeGeometry make common shapes, and a Geometry3D holds your own vertex data. See Meshes and Geometry. Resources and cleanup covers sharing geometries and materials between meshes and freeing their GPU memory.
• Sprites and batched meshes. A Sprite3D is a flat textured rectangle that turns to face the camera by default. BatchedMesh3D draws thousands of rigid meshes from one node. See Sprite3D and Batched meshes.
• Models. Assets.load reads glTF, an open standard format for 3D models, from .gltf and .glb files. A Model3D builds a loaded file's meshes, lights and cameras as nodes under itself. See Loading models and Compressed models.
• Animation. The model's player plays a file's animation clips by name and blends them. See Animation.
• Materials. Material3D is physically based, so it shades a surface the way real materials reflect light. PhongMaterial costs less per pixel, FlatMaterial draws with no lighting, and the extras add ToonMaterial for cartoon shading. See Materials.
• Lights and shadows. A DirectionalLight shines one way everywhere, like the sun. A PointLight shines every way from one point, like a bulb, and a SpotLight shines in a cone, like a torch. An AmbientLight shines from no direction. Directional and spot lights can cast shadows. See Lights and Shadows.
• Environment. The view's environment lights the scene from its surroundings. Use a Hemisphere for a sky-and-ground gradient, or a cube map for a picture of the surroundings on the six faces of a cube. See Environment.
• Cameras. A Camera3D's mode is perspective, where far things look smaller, or orthographic, where they don't. The extras' OrbitCamera lets the user drag the camera around a target point, and FPSCamera gives first-person controls. See Cameras and Camera controls.
• Interaction. 3D nodes take PixiJS's pointer events. Set a node's eventMode and listen on it as in 2D. See Interaction.
• Particles. The extras' ParticleSystem3D emits and moves particles for effects such as fire and snow, and ParticleContainer3D draws particles that your own code moves. See Particles.
• Post-processing. The extras hold effects and passes. An effect changes the finished picture, and BloomEffect is one that adds a glow. A pass is an extra drawing step that redraws meshes, and OutlinePass is one that draws ink outlines. Both go in the view's passes. See Post-processing.
• Math. PixiJS 3D has Vector3 and Matrix4, Quaternion for rotations, and shapes such as Ray, Plane and Box. See Math.
• Debugging. The extras' GraphDebugOverlay records frames and lists what each one drew. See Debugging.

There's no physics engine; bring your own.

Renderers and performance

PixiJS 3D draws with WebGPU or WebGL2. WebGL and WebGPU covers choosing one.

Performance explains what keeps a frame cheap and has a checklist for phones.

Next steps

• Installation: install @pixi/3d and the pixi.js version it needs.
• Quick start: build a first scene step by step, then load a model into it.
• View3D and 2D content: size a view and mix it with 2D content.
• Scene graph and transforms: the axes and units, and where 3D differs from 2D.