用途
PixiJS 3D(@pixi/3d)是 PixiJS 的 3D 扩展。核心是 View3D:它是 Pixi 舞台上一个普通的 2D 显示对象,把 3D 场景渲染到自己的矩形区域内,因此 3D 与 2D 可以自由混合。该技能用于在编写或编辑使用 @pixi/3d 的代码时提供指导,覆盖场景、View3D、Mesh3D、Model3D、灯光、阴影、相机、OrbitCamera 等内容。
主要能力
- 场景图:所有 3D 内容挂在 view.root(Container3D)下,节点支持 position、rotation(欧拉角弧度)、quaternion、scale、visible、lookAt、addChild、traverse 与 getLocalBounds。
- 几何体:内置 CubeGeometry、SphereGeometry、CylinderGeometry、ConeGeometry、CapsuleGeometry、TorusGeometry、PlaneGeometry、IcosahedronGeometry 等,并可自定义顶点数据。
- 材质:Material3D 为基于物理的材质,支持 baseColor、metallic、roughness、纹理、alphaMode;FlatMaterial 为无光照材质;发光通过 emissive 组配置,自定义外观通过 extraBits 着色器片段实现。
- 模型与动画:用 Assets.load<Scene3DSource> 加载 glTF/GLB,再用 Model3D 包装;动画通过 model.player 播放,支持骨骼与变形目标。
- 灯光与阴影:DirectionalLight、PointLight、SpotLight、AmbientLight 均为节点;视图 environment 提供半球补光或基于图像的照明;阴影通过灯光的 castShadow、网格的 castShadow/receiveShadow 与视图的 shadowQuality 控制。
- 相机:view.camera 为 Camera3D,支持透视与正交模式;extras 提供 OrbitCamera、FPSCamera。
- 批量与特效:BatchedMesh3D 与自动实例化;extras 提供粒子、Bloom、SSAO、移轴、运动模糊、FXAA、卡通材质、传送门等。
- 2D 与 3D 结合:HUD、按钮、精灵为普通 Pixi 对象叠加在视图之上;Sprite3D 可在场景内显示可被遮挡的图片;worldToScreen 用于把 2D 标签放到 3D 位置。
使用方式
起步应用为 Vite + TypeScript,安装 pixi.js 与 @pixi/3d 后,在 src/main.ts 中创建 Application 并 await app.init,再创建 View3D 加入 app.stage;灯光、地面、网格、模型均作为 view.root 的子节点;相机用 position.set 与 lookAt 定位,OrbitCamera 可从鼠标驱动相机;逐帧逻辑挂在 app.ticker 上。构造器统一接收一个选项对象,之后同样参数为普通属性。
渲染器默认 WebGL,可通过 app.init({ preference: 'webgpu' }) 切换。抗锯齿通过应用层 antialias 设置,View3D 没有该选项。选项值使用字符串字面量,没有枚举类型。
适用场景
适合需要在既有 PixiJS 2D 应用中嵌入 3D 元素、展示 glTF 模型、实现带光照与阴影的产品展示、或做 2D/3D 混合界面与特效的场景;也适合从 Three.js 迁移的开发者参考对照表。
限制
文档列出了若干静默失败陷阱,例如 lookAt 或加载的 glTF 节点会写入 quaternion、addChild 保留局部数值而 reparentChild 保留世界位置、view.root 包含相机不可清空、alphaMode 默认 opaque 会忽略透明度、PlaneGeometry 贴图需 flipV、同一来源的模型共享材质、3D 节点默认 eventMode 为 passive、全屏视图会拦截其后方 2D 对象的点击、OrbitCamera 关闭 enabled 后仍需关闭 autoUpdate 等。文档还列出现有库限制及临时绕过方案,如缺少法线的 glTF 网格光照异常、SphereGeometry 贴图左右镜像、未设置 position/scale/anchor 的 Sprite3D 按 1×1 单位绘制。对于本文未覆盖的签名或选项,需查阅官方类 API 页面与 llms.txt 索引。