babylonjs

Babylon.js 8

快速参考

Babylon.js 是一款功能强大的 Web 开源 3D 引擎。版本 8 支持 WebGL2 和 WebGPU。

坐标系： 左手坐标系（X=右，Y=上，Z=前）。旋转单位为弧度。

NPM 包：

• @babylonjs/core - 引擎、场景、网格、材质、相机、灯光
• @babylonjs/gui - 2D/3D GUI 控件
• @babylonjs/loaders - glTF、OBJ、STL 加载器
• @babylonjs/materials - 其他材质类型
• @babylonjs/inspector - 调试检查器

Tree-shaking： 从深层路径导入，以生成最小化的打包文件：

import { Scene } from "@babylonjs/core/scene";
import { Vector3 } from "@babylonjs/core/Maths/math.vector";
import { Color3, Color4 } from "@babylonjs/core/Maths/math.color";
import { Mesh } from "@babylonjs/core/Meshes/mesh";
import { PBRMaterial } from "@babylonjs/core/Materials/PBR/pbrMaterial";
import { ArcRotateCamera } from "@babylonjs/core/Cameras/arcRotateCamera";

副作用导入（无需引用导出项即可启用功能）：

import "@babylonjs/core/Meshes/thinInstanceMesh";
import "@babylonjs/core/Rendering/edgesRenderer";
import "@babylonjs/core/Collisions/collisionCoordinator";
import "@babylonjs/loaders/glTF/2.0/glTFLoader";

最小场景设置

import { Engine } from "@babylonjs/core/Engines/engine";
import { Scene } from "@babylonjs/core/scene";
import { ArcRotateCamera } from "@babylonjs/core/Cameras/arcRotateCamera";
import { HemisphericLight } from "@babylonjs/core/Lights/hemisphericLight";
import { Vector3 } from "@babylonjs/core/Maths/math.vector";
import { CreateSphere } from "@babylonjs/core/Meshes/Builders/sphereBuilder";
import { CreateGround } from "@babylonjs/core/Meshes/Builders/groundBuilder";

const engine = new Engine(canvas, true);
const scene = new Scene(engine);
const camera = new ArcRotateCamera("cam", 0, Math.PI/4, 10, Vector3.Zero(), scene);
camera.attachControl(canvas, true);
const light = new HemisphericLight("light", new Vector3(0, 1, 0), scene);
const sphere = CreateSphere("sphere", { diameter: 2 }, scene);
const ground = CreateGround("ground", { width: 6, height: 6 }, scene);
sphere.position.y = 1;

engine.runRenderLoop(() => scene.render());
window.addEventListener("resize", () => engine.resize());

关键模式

PBR 材质（最常用于逼真渲染）

const pbr = new PBRMaterial("pbr", scene);
pbr.albedoColor = new Color3(1.0, 0.766, 0.336);
pbr.metallic = 0.3;
pbr.roughness = 0.7;
// Optional: connect to environment for reflections
pbr.reflectionTexture = scene.environmentTexture;
mesh.material = pbr;

Thin Instances（高性能批处理）

import "@babylonjs/core/Meshes/thinInstanceMesh";
const buffer = new Float32Array(16 * count);
for (let i = 0; i < count; i++) {
  Matrix.Translation(x, y, z).copyToArray(buffer, i * 16);
}
mesh.thinInstanceSetBuffer("matrix", buffer, 16, false);
mesh.thinInstanceBufferUpdated("matrix");

资源加载（glTF）

import "@babylonjs/loaders/glTF/2.0/glTFLoader";
const container = await BABYLON.LoadAssetContainerAsync("model.glb", scene);
container.addAllToScene();

可观察对象模式（Babylon 的事件系统）

scene.onBeforeRenderObservable.add(() => { /* per frame */ });
const observer = scene.onPointerObservable.add((info) => { /* pointer events */ });
scene.onPointerObservable.remove(observer); // unsubscribe

程序化建模 — 支持动画的层级结构

在每个关节处先放置一个 TransformNode，再附加几何体，以基元构建复杂模型。每个自由度设置一个枢轴；几何体的局部位置即其相对于关节的偏移量。

const robotRoot = new TransformNode("robotRoot", scene);
const shoulderPivot = new TransformNode("shoulderPivot", scene);
shoulderPivot.parent = robotRoot;                  // pivot lives at the joint axis
const upperArm = CreateCapsule("upperArm", { height: 1.2, radius: 0.16 }, scene);
upperArm.parent = shoulderPivot;
upperArm.position.y = 0.6;                          // geometry sticks out from joint
// Animation later: shoulderPivot.rotation.y = ...  // rotates whole arm cleanly

对于布尔运算（钻孔、切槽），请使用 Babylon 8 中的 CSG2。对于旋转对称的部件（瓶子、轮毂、柱子），请使用 CreateLathe。对于沿路径扫掠的部件（电缆、导轨），请使用 CreateTube 或 ExtrudeShape。请参阅 [procedural-parametric-modeling.md](references/procedural-parametric-modeling

参考文件

阅读以下文件，了解特定主题的详细 API 用法：

• core-concepts.md - 引擎/场景设置、相机、灯光、阴影、可观察对象、坐标系
• meshes.md - 网格构建器、变换、TransformNode、实例、Thin Instances、克隆、合并、拾取
• procedural-parametric-modeling.md - 使用基元通过代码构建高质量 3D 模型。完整的基元目录（lathe、tube、extrude、多面体、测地体、CSG2 布尔运算、自定义 VertexData）、质量优化技巧（细分、倒角、边缘、材质调色板），以及完整的支持动画的父级/枢轴层级模式，并附有一个完整的机械臂示例。当你需要通过代码构建任何非简单模型，或模型需要制作动画时，请阅读此文件。
• materials.md - PBR、Standard、纹理、环境/HDR、Node Material、Shader Material
• gui.md - AdvancedDynamicTexture、所有控件类型、容器、布局、事件
• animation-loading.md - Animation API、组、缓动、骨骼动画、资源加载、AssetContainer
• performance.md - 场景/网格/材质优化、实例化策略比较、监控、内存管理

按需查阅文档

对于参考文件未涵盖的主题，请从在线文档中获取：

• 文档站点： https://doc.babylonjs.com
• GitHub 原始 Markdown： https://raw.githubusercontent.com/BabylonJS/Documentation/master/content/{path}.md
• doc-urls.md - 所有文档章节的完整 URL 映射

要获取特定主题，请先阅读 URL 映射以查找路径，然后使用 WebFetch 获取文档站点上的 URL，或从 GitHub 获取原始 Markdown。

仅在在线文档中介绍的主题（参考文件中没有）

• Physics V2（Havok）：/features/featuresDeepDive/physics
• WebXR/VR/AR：/features/featuresDeepDive/webXR
• 后期处理管线：/features/featuresDeepDive/postProcesses
• Solid Particle System：/features/featuresDeepDive/particles/solid_particle_system
• 人群导航：/features/featuresDeepDive/crowdNavigation
• Node Geometry（程序化）：/features/featuresDeepDive/mesh/nodeGeometry
• Frame Graph：/features/featuresDeepDive/frameGraph
• Flow Graph：/features/featuresDeepDive/flowGraph
• Smart Filters：/features/featuresDeepDive/smartFilters
• Gaussian Splatting：/features/featuresDeepDive/importers（splat/ply 格式）

常见注意事项

1. 四元数与欧拉角： 设置 mesh.rotationQuaternion 会禁用 mesh.rotation。若要切换回去，请设置 mesh.rotationQuaternion = null。
2. 副作用导入： thin instances、edge rendering、加载器和碰撞等功能都需要导入其模块，即使你不会直接使用导出的内容。
3. 释放所有资源： Babylon.js 不会自动回收 GPU 资源。使用完网格、材质和纹理后，务必调用 .dispose()。
4. 材质共享： 修改共享材质会影响使用该材质的所有网格。若要独立修改，请克隆材质或创建新材质。
5. TransformNode 与 Mesh： 使用 TransformNode 进行分组和构建层级。空的 Mesh 对象会浪费 CPU 资源进行视锥体评估。
6. 左手坐标系： glTF 使用右手坐标系；Babylon 会在导入时自动转换。手动进行坐标计算时可能需要调整。
7. Alpha 排序： 透明网格需要正确的渲染顺序。请使用 mesh.alphaIndex 或渲染组。
8. Thin instance 的限制： 可见性只能整体控制，所有实例共用一个包围盒，且无法为每个实例单独设置材质。需要单独控制时，请使用常规实例。
9. 先设置枢轴，再创建几何体： 通过代码构建动画模型时，先创建关节的 TransformNode 并设置其父级，然后将几何体作为子级添加，并设置局部偏移。使用 MergeMeshes 后再补设枢轴非常麻烦——请先确保层级结构正常，再进行合并。
10. CSG2 设置： Babylon 8 的 CSG2（由 Manifold 支持的布尔运算）需要在使用前调用一次 await InitializeCSG2Async()，且在世界空间中运算。务必释放中间的 CSG2.FromMesh 对象——它们会占用 WASM 内存。
11. 负缩放会翻转绕序： 通过 scaling.x *= -1 镜像整个层级会反转三角形绕序，导致背面剔除失效。可通过 material.sideOrientation = Mesh.DOUBLESIDE 修复，或重新烘焙。