Babylon.js 快速入门：怎么创建第一个 3D 场景

在浏览器中呈现一个 3D 场景，本质上是在一个 HTML5 <canvas> 画布上逐帧绘制空间模型与光影反射。要在 Babylon.js 中构建并运行第一个场景，核心路径非常清晰：引入引擎脚本、准备渲染画布、初始化驱动渲染的底层引擎（Engine）、在场景容器（Scene）中布置相机与光源、放置一个几何网格（Mesh），最后通过一个持续刷新的渲染循环将画面实时推送到屏幕上。

一、前置准备与基础骨架搭建

在编写 3D 渲染代码之前，需要准备两项基础设施：一个用于承载画面的 HTML 页面，以及一套本地静态文件服务。虽然 Babylon.js 脚本可以通过 CDN 链接直接通过 <script> 标签引入，但因为现代浏览器对 WebGL 上下文和后续加载外部资源有严格的安全策略，直接在本地双击打开（file:/// 协议）可能会触发权限与跨域警告。建议使用 VS Code 的 Live Server 插件，或者在终端运行 npx serve 启动一个本地 HTTP 服务。

在页面结构中，最关键的 HTML 标签是 <canvas id="renderCanvas"></canvas>。为了让 3D 视角充满整个视口，通常将 canvas 的 CSS 样式设置为 width: 100%; height: 100%; touch-action: none;。其中 touch-action: none; 非常关键，它能阻止移动端或手势触控板在拖拽 3D 物体时误触发浏览器的默认滚屏手势。

二、核心概念与装配逻辑

Babylon.js 的 API 组织遵循非常严密的面向对象架构。在进入代码之前，理清以下几个关键概念的分工，能帮助你避免许多初学者常犯的逻辑错误：

• Engine（引擎）：直接与浏览器的 WebGL/WebGPU 底层接口交互，负责管理图形硬件上下文、着色器编译和渲染缓冲。一个页面通常只需要一个 Engine 实例。
• Scene（场景）：三维虚拟空间的逻辑容器。所有你看到的模型、灯光、摄像机、粒子系统以及声音，都必须注册到特定的 Scene 实例中。
• Camera（相机）：决定观众在三维空间中以什么角度看画面。新手最常用的类型是 ArcRotateCamera（弧形旋转相机），它始终围绕一个目标中心点旋转，天生支持鼠标拖拽旋转、滚轮缩放，极易上手。
• Light（光源）：三维世界没有光就是漆黑一片。HemisphericLight（半球光）提供漫反射环境光，最适合快速照亮整个场景。
• Mesh（网格物体）：包含顶点坐标、多边形面和法线信息的几何实体。通过 BABYLON.MeshBuilder 可以直接生成立方体、球体、地面等内置形状。

三、完整单文件代码实现

下面是一份完整的 index.html 代码。你只需要将代码保存为本地文件，并通过静态服务器打开，就能立即在浏览器中看到一个可以使用鼠标任意拖拽、旋转的 3D 立方体：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>My First Babylon.js Scene</title>
  <style>
    html, body {
      width: 100%;
      height: 100%;
      margin: 0;
      padding: 0;
      overflow: hidden;
    }
    #renderCanvas {
      width: 100%;
      height: 100%;
      touch-action: none;
      display: block;
    }
  </style>
  <!-- 引入 Babylon.js 核心引擎库 -->
  <script src="https://cdn.babylonjs.com/babylon.js"></script>
</head>
<body>

  <canvas id="renderCanvas"></canvas>

  <script>
    // 1. 获取 Canvas 元素
    const canvas = document.getElementById("renderCanvas");

    // 2. 初始化底层渲染引擎，第二个参数表示开启抗锯齿
    const engine = new BABYLON.Engine(canvas, true);

    // 3. 构建 3D 场景的装配函数
    const createScene = function () {
      // 实例化场景容器
      const scene = new BABYLON.Scene(engine);

      // 创建弧形旋转相机：参数依次为名称、alpha(水平角)、beta(俯仰角)、radius(距离)、目标点、所属场景
      const camera = new BABYLON.ArcRotateCamera(
        "camera1",
        -Math.PI / 2,
        Math.PI / 2.5,
        5,
        new BABYLON.Vector3(0, 0, 0),
        scene
      );

      // 将相机控制权绑定到画布，允许鼠标/触摸控制
      camera.attachControl(canvas, true);

      // 创建半球光，方向朝向天顶 (Y 轴正方向)
      const light = new BABYLON.HemisphericLight(
        "light1",
        new BABYLON.Vector3(0, 1, 0),
        scene
      );
      light.intensity = 0.8; // 设置光照强度

      // 创建一个尺寸为 2 的立方体
      const box = BABYLON.MeshBuilder.CreateBox("box1", { size: 2 }, scene);

      // 创建标准材质并为立方体赋予赭红色
      const material = new BABYLON.StandardMaterial("boxMat", scene);
      material.diffuseColor = new BABYLON.Color3(0.65, 0.42, 0.35); // #A66C5B
      box.material = material;

      return scene;
    };

    // 4. 调用函数生成场景
    const scene = createScene();

    // 5. 注册渲染循环，驱动画面持续刷新
    engine.runRenderLoop(function () {
      scene.render();
    });

    // 6. 监听窗口变化，自适应调整渲染分辨率
    window.addEventListener("resize", function () {
      engine.resize();
    });
  </script>
</body>
</html>

四、关键原理：坐标系与相机视角控制

在 3D 图形学中，物体的位置与相机的观察方向依赖于空间坐标系。Babylon.js 默认采用左手坐标系（Left-Handed System）：当屏幕朝向你时，X 轴正方向水平向右，Y 轴正方向竖直向上，而 Z 轴正方向则深入屏幕内部。

掌握 ArcRotateCamera 的三维球坐标参数至关重要：

• alpha：绕 Y 轴水平公转的角度（弧度制）。改变 alpha 相当于绕着物体水平走圈。
• beta：垂直方向的俯仰角。当 beta 为 0 时相机正处于头顶鸟瞰位置，当 beta 达到 Math.PI / 2 时相机处于正水平面。
• radius：相机距目标焦点（target）的空间直线距离。鼠标滚轮缩放实际上就是在增减这个数值。
• target：相机视线聚焦的空间点，通常聚焦在物体所在的原点 new BABYLON.Vector3(0, 0, 0)。

五、新手常见问题与排错清单

在第一次运行 Babylon.js 代码时，如果画面没有如期出现，可以按照以下四个常见现象迅速定位原因：

• 现象 1：画面纯黑，什么都看不到
  这是最常见的问题。产生原因通常有两个：一是遗漏了灯光配置（若未添加 Light，基础材质表面漫反射为 0 因而呈现死黑）；二是相机机位与物体距离过近或穿模，直接位于立方体内部。检查代码中是否实例化了 HemisphericLight，并将 radius 参数设为大于几何体尺寸的值。
• 现象 2：鼠标拖拽时，3D 物体没有任何旋转反应
  确认是否调用了 camera.attachControl(canvas, true)。只有显式执行了该方法，Babylon.js 才会将 Canvas 上的鼠标按压、移动、滚轮事件与相机矩阵计算器绑定。
• 现象 3：调整浏览器窗口大小时，画面出现拉伸变形或严重模糊
  WebGL 的画布渲染分辨率由 Canvas 的像素宽度和高度决定，而非单纯的 CSS 百分比宽高。当窗口大小发生变化时，必须通过 window.addEventListener("resize", () => engine.resize()) 通知引擎重新同步 GPU 视口与帧缓冲区尺寸。
• 现象 4：移动端拖拽物体时整个网页跟着上下滑动
  为 <canvas> 元素的 CSS 添加 touch-action: none;。该样式通知移动端浏览器将触控手势完全委托给 JavaScript 处理，避免触发默认的下拉或滚页手势。

六、结语与后续探索

通过上面的步骤，你已经成功运行了属于自己的第一个 Babylon.js 3D 场景。虽然这只是一个受光照照射的立方体，但它已经涵盖了 Web 3D 渲染引擎最核心的工作闭环：从 WebGL 上下文托管、场景拓扑搭建，到机位交互控制与逐帧渲染管线。

在掌握了这一套基础骨架后，后续的进阶拓展主要沿着两个方向展开：一是几何模型的丰富度，利用 BABYLON.SceneLoader.ImportMeshAsync 载入外部美术资产（例如主流的 .gltf 或 .glb 格式三维模型）；二是光影与材质质感的提升，从基础 StandardMaterial 进阶到支持粗糙度、金属度和环境贴图的高级 PBRMaterial（基于物理的渲染材质）。这些内容虽然更为丰富，但其底层所依赖的 Engine、Scene 与 RenderLoop 机制与本文完全一致。