Repository navigation
Releases
Releases · pixijs/3d
v0.1.0
PixiJS 3D is public. Combine 2D and 3D in one place, the PixiJS way.
npm install pixi.js @pixi/3d- Docs: https://3d.pixijs.download/release/docs/index.html
- CDN: https://cdn.jsdelivr.net/npm/@pixi/3d@0.1.0/dist/pixijs-3d.min.mjs
🚨 Behavior Change since 0.1.0-beta.3
@pixi/3dships ES modules only. The CommonJS build never loaded; on Node 20.19+ and 22.12+,require('@pixi/3d')now loads the ES modules. (#34)- The CDN files are
pixijs-3d.min.mjsandpixijs-3d-extras.min.mjs, renamed frompixi-3d…. - Warnings start with
[@pixi/3d], and the math types'toString()returns[@pixi/3d/math:Vector3 …].
🐛 Fixed
- Importing
@pixi/3d/extrasbefore@pixi/3dno longer throws "Class extends value undefined". (#34)
v0.1.0-beta.3
Closed beta build of @pixi/3d, from commit 97ece7a.
Download pixi-3d-0.1.0-beta.3.tgz, then install it next to PixiJS:
npm install pixi.js@^8.23.0
npm install ./pixi-3d-0.1.0-beta.3.tgzImports work exactly as they will from npm:
import { View3D } from '@pixi/3d';
import { OrbitCamera } from '@pixi/3d/extras';🚨 Behavior Change
- chore: bump pixi.js peer dependency to 8.23.0 by @Zyie
npm install pixi.js@^8.23.0
- feat: views default to toneMapping 'none' by @GoodBoyDigital
View3Dnow defaults totoneMapping: 'none'instead of'aces'. A scene that relied on the default draws its highlights brighter, and lit colour above 1 clips to white instead of rolling off. Unlit materials and abackgroundcolour now show as authored, where ACES drew white as light grey. To keep beta.2's look, passtoneMapping: 'aces'to each view, or setView3D.defaultOptions.toneMapping = 'aces'once before you create any view.
import { View3D } from '@pixi/3d'; // one view const view3d = new View3D({ toneMapping: 'aces' }); // or every view created after this line View3D.defaultOptions.toneMapping = 'aces';
- feat: post effects read linear light, with the curve in OutputPass by @GoodBoyDigital
PassStageno longer has'post'. Post effects run at'beforeToneMapping', on linear light before the view's tone curve, or at the new'afterToneMapping', on the picture as it shows, andPostEffect.stageis one of the two. Replace checks for'post', and replaceExclude<PassStage, 'post'>with the newSceneStagetype, whichMeshPassOptions.stageandWireframePassOptions.stagenow take.
import type { PassStage, SceneStage } from '@pixi/3d'; // before const stage: Exclude<PassStage, 'post'> = 'afterOpaque'; const isEffect = pass.stage === 'post'; // after const stage: SceneStage = 'afterOpaque'; const isEffect = pass.stage === 'beforeToneMapping' || pass.stage === 'afterToneMapping';
- A custom
PostEffectruns at'beforeToneMapping'unless it says otherwise. Its input is linear light inrgba16float, so values can go above 1 and aren't display-encoded. An effect that works on the picture as it shows, such as LUT grading or edge detection, or that shows data such as depth, normals or debug colours, must passstage: 'afterToneMapping'tosuper.
import { PostEffect } from '@pixi/3d'; import type { PostEffectOptions } from '@pixi/3d'; class MyLutEffect extends PostEffect { constructor(options: PostEffectOptions = {}) { super({ stage: 'afterToneMapping', ...options }); } }
- Effects now run grouped by stage: every
'beforeToneMapping'effect in array order, then the tone curve, then every'afterToneMapping'effect in array order.TintEffectdefaults to'afterToneMapping', so it runs afterBloomEffect,SsaoEffectandTiltShiftEffectwherever it sits inview.passes. To keep a tint ahead of them, give itstage: 'beforeToneMapping'; it then tints the light instead of the picture.
import { BloomEffect, TintEffect } from '@pixi/3d/extras'; // before: the tint ran first because it came first in the array view3d.passes = [new TintEffect({ tint: 0xffaa66 }), new BloomEffect()]; // after view3d.passes = [new TintEffect({ tint: 0xffaa66, stage: 'beforeToneMapping' }), new BloomEffect()];
- A view with a
'beforeToneMapping'effect, such asBloomEffect,SsaoEffect,TiltShiftEffector a customPostEffect, now draws its scene intorgba16floatlinear light. ItstoneMappingcurve then runs once on the whole image after those effects, not in each material. Transparent surfaces blend in linear light before the curve, so they look slightly different. Views without such an effect keep the curve in their materials. BloomEffectnow reads linear light before the tone curve, so every bloom looks different. Itsthresholdis measured in that light, and the default1blooms only what's brighter than white. Retune a threshold set for the old 8-bit image, such as0.5.SsaoEffectnow darkens linear light before the tone curve, so its occlusion looks lighter. Raiseintensityto match the old look.TiltShiftEffectalso blurs in linear light now.- Glass (a
Material3Dwithtransmission) now decodes the scene behind it with an exact 2.2 gamma instead of squaring it, so it looks slightly different in every view. No code change is needed. - In a view with a
'beforeToneMapping'effect,OutlinePass,WireframePassand any otherMeshPasswhose own shader writes a flat colour into the scene no longer show the colour you set. The output pass runs the tone curve and display encode over it, so most colours show lighter; black stays black. Under the defaulttoneMapping: 'none', give the pass its colour in linear light, each channel raised to the power 2.2, to get the old colour back. Under a filmic curve, keep coloured outlines and wireframes in views whose effects all run at'afterToneMapping'.
import { Color } from 'pixi.js'; import { BloomEffect, OutlinePass } from '@pixi/3d/extras'; const [r, g, b] = new Color(0xff8800).toRgbArray(); view3d.passes = [new OutlinePass({ color: [r ** 2.2, g ** 2.2, b ** 2.2] }), new BloomEffect()];
- On WebGL 2 without
EXT_color_buffer_float, a view with a'beforeToneMapping'effect now throws when it builds its render graph on its first render. To keep the effect working on those devices, run it at'afterToneMapping'there.
import { RendererType } from 'pixi.js'; import type { WebGLRenderer } from 'pixi.js'; import { BloomEffect } from '@pixi/3d/extras'; const renderer = app.renderer; const canDrawFloat = renderer.type !== RendererType.WEBGL || !!(renderer as WebGLRenderer).context.extensions.colorBufferFloat; view3d.passes = [new BloomEffect({ stage: canDrawFloat ? 'beforeToneMapping' : 'afterToneMapping' })];
graph.createColor()with noformatnow takes the scene colour's format, which isrgba16floatin a view with a'beforeToneMapping'effect, where it used to take the view target's. Passformatto keep a texture 8-bit.
// before const mask = graph.createColor({ label: 'mask' }); // after const mask = graph.createColor({ label: 'mask', format: 'rgba8unorm' });
DefaultGraph3DOptions.toneMappingis now required. A customgraphbuilder that passes theoptionsit receives on tocreateDefaultGraph3Dgets it from the view. A builder that writes its own options object must spreadoptionsinto it; in plain JavaScript, leaving it out shows a view with a'beforeToneMapping'effect without its tone curve or display encode.
import { createDefaultGraph3D } from '@pixi/3d'; import type { View3DOptions } from '@pixi/3d'; // before const graph: View3DOptions['graph'] = (renderer, options) => createDefaultGraph3D(renderer, { passes: options.passes, composite: true }).graph; // after const graph: View3DOptions['graph'] = (renderer, options) => createDefaultGraph3D(renderer, { ...options, composite: true }).graph;
- Lit material shaders on both backends now define a
decodeToLinear(c)function. A custom bit that defines a function with that name fails to compile, so rename yours. - In a custom
graphbuilder, asceneColorwith a float or-srgbformat, such asrgba16float, now marks the scene as linear light (RenderGraph.sceneIsLinear). Materials and the sky then leave out the tone curve and display encode, so the image shows too dark unless a pass in the graph applies them. In beta.2 the materials always applied them. Finish such a graph with anOutputPassgiven the builder'soptions.toneMapping. On such a view, and on any view with a'beforeToneMapping'effect, changingtoneMappingnow destroys the render graph and calls the builder again, so don't keep references to the passes it made.
import { OutputPass, RenderGraph } from '@pixi/3d'; import type { View3DOptions } from '@pixi/3d'; const buildGraph: View3DOptions['graph'] = (renderer, options) => { const graph = new RenderGraph({ globalTextureBindings: options.globalTextureBindings, defaultColor: (session) => session.defaultTarget.colorTexture, defaultDepth: (session) => session.defaultTarget.depthStencilTexture!, sceneColor: { label: 'sceneColor', format: 'rgba16float' }, sceneDepth: { label: 'sceneDepth' }, }); // add your passes, then finish the image graph.addPass(new OutputPass({ renderer, source: graph.sceneColor, toneMapping: options.toneMapping })); return graph; };
- fix: unlit materials show colours as authored by @GoodBoyDigital
BaseMaterial3D.toneMappedis removed, and every material, lit or unlit, now takes the view'stoneMapping. DeletetoneMappedoverrides and any reads or writes of it; TypeScript rejectsoverride toneMapped. There's no per-material opt-out. UndertoneMapping: 'none', the default, unlit art at exposure 1 matches pixi 2D, and under a filmic curve such as'aces'it shifts with the lit scene. To keep some art off the curve, draw it in its ownView3DwithtoneMapping: 'none'.
// before class SkyMaterial extends BaseMaterial3D { public override toneMapped = false; public override lit = false; } // after class SkyMaterial extends BaseMaterial3D { public override lit = false; }
FlatMaterial,Sprite3D,ParticleContainer3DandParticleSystem3Dparticles,PortalMaterialand glTFKHR_materials_unlitmaterials now encode their colour inputs for display, so they render differently with no code change. Beta.2 drew theirbaseColor,tint, particlecolorandcolorEnd, vertex colours and glTF unlit factors as linear values (a 128 grey drew as 55). UndertoneMapping: 'none'at exposure 1 ...
v0.1.0-beta.2
Closed beta build of @pixi/3d, from commit bdb9eb4.
Download pixi-3d-0.1.0-beta.2.tgz, then install it next to PixiJS:
npm install pixi.js
npm install ./pixi-3d-0.1.0-beta.2.tgzImports work exactly as they will from npm:
import { View3D } from '@pixi/3d';
import { OrbitCamera } from '@pixi/3d/extras';🚨 Behavior Change
- chore: bump pixi.js peer dependency to 8.22.0 by @Zyie
npm install pixi.js@^8.22.0
- breaking: read material rows from the data texture on WebGPU by @GoodBoyDigital
- This affects custom shader bits that declare
materialfields. - A material field must be
f32,u32,i32, avec2,vec3orvec4off32, ormat2x2<f32>. Creating a material with any other type throws, and the error names the bit and the field. A material struct larger than its 256-byte row also throws, where it used to spill into the next material's data. - In WGSL,
uMaterialStorageis a texture now, souMaterialStorage[i]no longer compiles. Read themateriallocal, which both stages have, or callgetMaterial(index)for another material's row.
// before let tint = uMaterialStorage[vMaterialIndex].tint; // after let tint = material.tint;
- In GLSL, the compiler emits
getMaterial()aftergl.header, so code in the header can't call it. Code in the stage slots still can.
- This affects custom shader bits that declare
- fix: WebGPU batch samplers take the implicit level of detail by @GoodBoyDigital
- The shader helpers
sampleBatchTextureand_unpackSlotare gone from the WGSL and GLSL headers, so a customShaderBitthat calls them fails to compile. Call the generatedsample<Name>(uv)andsample<Name>Direct(uv)getters instead, orsampleBatchSlotGrad(slot, uv, dx, dy)with the slot read from_textureSlotsin WGSL orvTextureSlotsin GLSL.
- The shader helpers
- feat: BatchedMesh3D cull option by @GoodBoyDigital
- A
BatchedMesh3Dno longer takes its culling mode from the view. Each batch has its owncull, and it defaults to'off', so every instance draws. In beta.1 a batch followed the view'scull, which defaults to'auto'. Turn culling back on for a large batch spread well beyond the view, such as scattered scenery:
const forest = new BatchedMesh3D({ size: treePositions.length, cull: 'auto' });
- A
- feat: OrbitCamera and FPSCamera keep the context menu from opening by @Zyie
- Once a View has an
OrbitCameraorFPSCamera, the browser's context menu stops opening over that View. PasspreventContextMenu: falseto get it back. The menu also opens while the controller'senabledisfalse.
import { OrbitCamera } from '@pixi/3d/extras'; new OrbitCamera({ view: view3d, preventContextMenu: false }); // or for every controller created after this line OrbitCamera.defaultOptions.preventContextMenu = false;
- Once a View has an
🎁 Added
- feat: View3D.background accepts a Hemisphere by @Zyie
View3D'sbackgroundtakes aHemisphereand draws its sky and ground gradient behind the scene, on WebGL and WebGPU. The gradient uses the same formula as a hemisphereenvironment, so one object passed to both gives a sky that matches the scene's light. The view's exposure and tone mapping apply, as they do to a cube map. A colour change shows on the next frame. The option also acceptsnull.
import { type Hemisphere, View3D } from '@pixi/3d'; const sky: Hemisphere = { skyColor: 0x88ccff, groundColor: 0x553311 }; const view3d = new View3D({ autoResize: true, environment: sky, background: sky }); sky.skyColor = 0xff8800; // sunset
- feat: OrbitCamera and FPSCamera keep the context menu from opening by @Zyie
OrbitCameraandFPSCameratake apreventContextMenuoption, also a property you can change at runtime. It defaults totrue, so a right-button pan or a drag to look around no longer opens the browser menu. Windows opens the menu on release, so there a right-button drag that ends outside the View still opens it.- 3D nodes receive
contextmenuevents like the other pointer events, withhit3Dset, and gain anoncontextmenuhandler property.preventDefault()keeps the browser menu closed.stopPropagation()lets it open and hides the event from the View's own listeners, such as a camera controller's.
mesh.on('contextmenu', (e) => { e.preventDefault(); openMenuFor(mesh, e.global); });
- feat: read material rows from the data texture on WebGPU by @GoodBoyDigital
⚡ Performance
- feat: upload only the changed texels of data textures by @GoodBoyDigital
- fix: cut per-frame garbage and wasted work on hot paths by @GoodBoyDigital
- fix: bound light-mask loops for mobile GPUs by @GoodBoyDigital
- fix: WebGPU batch samplers take the implicit level of detail by @GoodBoyDigital
- breaking: read material rows from the data texture on WebGPU by @GoodBoyDigital
🐛 Fixed
- fix: WebGL reads integer data through integer textures by @GoodBoyDigital
- fix: use the glTF default material for primitives without one by @Zyie
- fix: WebGL reads integer data through integer textures by @GoodBoyDigital
- chore: bump pixi.js peer dependency to 8.22.0 by @Zyie
- fix: shadow auto-fit reads live caster membership, not a stale sort by @Zyie
- fix: apply View3D visibility and transform changes by @Zyie
- fix: keep the WebGL bone texture aligned to whole rows when the bone pit grows by @Zyie
- fix: drop the GGX guard that flattened smooth highlights by @Zyie
- fix: copy atlas fast-path vertices as bytes and check the layout first by @GoodBoyDigital
- fix: copies read the target their camera drew, not whatever is bound by @GoodBoyDigital
- breaking: read material rows from the data texture on WebGPU by @GoodBoyDigital
- fix: a read-only-depth pass resolves to pixi's default target instead of reconfiguring the canvas by @Zyie
- fix: shadow passes let go of pipe stores when their renderer is destroyed by @Zyie
- fix: IBL prefilter and BRDF LUT release their one-shot bind groups by @Zyie
🧹 Chores
v0.1.0-beta.1
Closed beta build of @pixi/3d, from commit 1022460.
Download pixi-3d-0.1.0-beta.1.tgz, then install it next to PixiJS:
npm install pixi.js
npm install ./pixi-3d-0.1.0-beta.1.tgzImports work exactly as they will from npm:
import { View3D } from '@pixi/3d';
import { OrbitCamera } from '@pixi/3d/extras';🚨 Behavior Change
- feat: light tile mask on WebGPU, and one upload per camera by @GoodBoyDigital
prepareCamerano longer uploads a camera.uploadCameradoes that after the view's lights are packed, andRenderGraph.prepareCamerasruns both for every camera the graph draws. If you drive the graph yourself, callprepareCameras; a camera that never reachesuploadCamerakeeps all-set tile masks and walks every light slot, which is correct but slower.
- feat: WebGPU reads lights and shadow data from the global uniforms, like WebGL by @GoodBoyDigital
- The WGSL storage buffers
uLightStorageanduShadowStorageare gone. Both backends now read the same two uniform arrays,uLightDataanduShadowData, from the global group. A custom WGSL shader bit that read either storage buffer must switch to the global arrays. WGSL bindings are numbered in declaration order, so the global-group bindings after the removed pair shifted down by two.
- The WGSL storage buffers
- feat: screen-tile light mask for the WebGL forward light loop by @GoodBoyDigital
- A custom material built with
createLightingBitnow needs the camera bindings, because the light loop reads the tile mask and the viewport from the camera group.includeCamerais on by default; leave it on. The same applies on WebGPU.
- A custom material built with
🎁 Added
- feat: View3D.from and autoResize by @Zyie
View3D.from(source, options)turns a loaded glTF into a working scene in one call. TheModel3Dbecomes the View'sroot, the file's own camera is used when it has one, otherwise a defaultCamera3Dis placed to frame the model's bounds, and a file with no lights gets a key light parented under the camera. Passlight: falseto skip that light.View3Dis generic over its root, sofromreturnsView3D<Model3D>andview.rootis typed as the model. Options are everyView3DOptionsfield plus the per-instanceModel3Dones (scene,castShadow,receiveShadow,autoPlay,autoUpdate). glTF camera nodes now instantiate asCamera3Dand are listed onmodel.cameras; they were plain containers before.
import { Assets } from 'pixi.js'; import { View3D } from '@pixi/3d'; const view = View3D.from(await Assets.load('robot.glb'), { autoResize: true }); app.stage.addChild(view); view.root.player?.play('Wave');
- The new
autoResizeoption, off by default, makes a View fill the renderer's screen and follow it. The size is applied in pixi's per-frameonRenderhook, before the frame's bounds and instructions are built, so filters and hit-testing see the new rect in the same frame. Setting a size later turnsautoResizeoff, so an explicit size always wins. This is what the examples used to hand-roll:
// before const view3d = new View3D({ width: app.screen.width, height: app.screen.height, shadowQuality: 'high', }); app.ticker.add(() => { view3d.setSize(app.screen.width, app.screen.height); }); // after const view3d = new View3D({ autoResize: true, shadowQuality: 'high' });
- feat: write BatchedMesh3D matrices in place by @GoodBoyDigital
BatchedMesh3D.matricesexposes the batch's interleaved instance data, so a per-frame transform update can be computed straight into it instead of building aMatrix4and copying it throughsetMatrixAt. Callmatrices.update()once after writing to notify the batch. About 2.3 ms saved per frame at 500,000 instances on an M-series Mac.
const { data, stride, offset } = batched.matrices; for (let i = 0, o = offset; i < batched.size; i++, o += stride) { data[o + 13] = heights[i]; // translation Y } batched.matrices.update();
⚡ Performance
- feat: screen-tile light mask for the WebGL forward light loop by @GoodBoyDigital
- feat: light tile mask on WebGPU, and one upload per camera by @GoodBoyDigital
- feat: cull lights by camera depth and skip empty WebGL mask bits by @GoodBoyDigital
- perf: no environment lighting work for a view with no environment by @GoodBoyDigital
- perf: draw alpha-masked meshes after the opaque ones in a pass by @GoodBoyDigital
- perf: WebGPU reads lights and shadow data from the global uniforms, like WebGL by @GoodBoyDigital
- perf: lit shaders leave shadow sampling out until a light first casts by @GoodBoyDigital
🐛 Fixed
- fix: loader parsers carry the name pixi's validator hashes on by @Zyie
- fix: the WebGL group map stops warning about struct-only bind groups by @Zyie
- fix: glTF custom-attribute notices go through pixi's warn, once per semantic by @Zyie
- fix: the back-buffer notice for glass warns once per renderer by @Zyie
- fix: WebGL shader precision comes from one compiler plugin, plus IBL hardening by @GoodBoyDigital
- fix: WebGPU shadow lookup takes two floats, not the light struct by @GoodBoyDigital
- fix: fast-path default WebGPU texture values by @GoodBoyDigital
- fix: WebGPU batch texture sampling stalls on Apple GPUs with MSAA by @GoodBoyDigital
- fix: shadow pass no longer runs for lights that cannot cast by @GoodBoyDigital
🧹 Chores
- chore: drop the View3D resize boilerplate from the examples by @Zyie