从零开始XR开发：Three.js实现交互式3D积木搭建器

前言

在空间计算和XR技术快速发展的今天，越来越多的开发者开始探索3D交互应用的开发。本文将带你从零开始，逐步实现一个功能完整的3D积木搭建器。这个项目不仅能帮助你理解Three.js的基础应用，还能深入学习物理引擎集成、拖拽交互系统以及复杂3D场景的构建。

项目源码在文末，欢迎大家下载和分享 ~~~

技术栈概览

在开始实践之前，让我们先了解本项目所使用的核心技术栈。选择合适的技术栈是项目成功的关键，每个技术都在系统中扮演着重要角色。

技术名称	版本	作用描述	选择理由
Three.js	0.170.0	3D渲染引擎	功能强大且文档完善，社区活跃度高，是Web 3D开发的首选方案
Cannon-es	0.20.0	物理引擎	轻量级JavaScript物理引擎，与Three.js配合良好，支持刚体碰撞和重力模拟
TypeScript	5.0+	开发语言	提供类型安全，降低运行时错误，提升代码可维护性
Vite	5.0+	构建工具	快速的开发服务器和热更新，显著提升开发体验

这套技术栈的组合经过了大量实践验证，能够高效地构建复杂的3D交互应用。Three.js负责渲染，Cannon-es处理物理模拟，TypeScript保证代码质量，Vite则提供流畅的开发体验。

第一步：搭建基础3D场景

万丈高楼平地起，任何复杂的3D应用都始于一个基础场景。在这个阶段，我们需要初始化Three.js的核心组件，包括场景、相机和渲染器。这三者构成了Three.js应用的基石，缺一不可。

场景的搭建过程需要特别注意光照系统的配置。良好的光照不仅能提升视觉效果，还能帮助用户更好地感知3D空间中的深度关系。我们使用环境光提供基础照明，配合方向光产生阴影效果，让积木在地面上投射出真实的影子，增强空间感。

export class PhysicsWorld {public world: CANNON.World;private bodies: Map < THREE.Mesh,CANNON.Body > =new Map();constructor() {this.world = new CANNON.World({gravity: new CANNON.Vec3(0, -9.82, 0)});this.world.broadphase = new CANNON.NaiveBroadphase();this.world.solver.iterations = 10;const groundShape = new CANNON.Plane();const groundBody = new CANNON.Body({mass: 0,shape: groundShape});groundBody.quaternion.setFromEuler( - Math.PI / 2, 0, 0);this.world.addBody(groundBody);}addBox(mesh: THREE.Mesh, mass: number = 1) : CANNON.Body {const geometry = mesh.geometry as THREE.BoxGeometry;const parameters = geometry.parameters;const shape = new CANNON.Box(new CANNON.Vec3(parameters.width / 2, parameters.height / 2, parameters.depth / 2));const body = new CANNON.Body({mass: mass,shape: shape,position: new CANNON.Vec3(mesh.position.x, mesh.position.y, mesh.position.z)});this.world.addBody(body);this.bodies.set(mesh, body);return body;}
}

轨道控制器的加入让用户可以自由地观察场景。通过鼠标拖动旋转视角，滚轮缩放视图，这些交互方式已经成为3D应用的标准配置。控制器的阻尼效果能让相机移动更加平滑自然，而不是生硬的即时响应。

第二步：集成物理引擎

有了基础场景后，我们需要让积木具备真实的物理特性。这就需要集成Cannon-es物理引擎。物理引擎的作用是模拟真实世界的物理规律，包括重力、碰撞、摩擦等效果。

物理世界的创建是一个精细的过程。我们需要设置合适的重力加速度，配置碰撞检测算法，并创建地面这个静态物体。物理世界中的对象分为动态和静态两类，动态对象会受到重力和碰撞影响，而静态对象则保持不动，仅参与碰撞检测。

export class PhysicsWorld {public world: CANNON.World;private bodies: Map < THREE.Mesh,CANNON.Body > =new Map();constructor() {this.world = new CANNON.World({gravity: new CANNON.Vec3(0, -9.82, 0)});this.world.broadphase = new CANNON.NaiveBroadphase();this.world.solver.iterations = 10;const groundShape = new CANNON.Plane();const groundBody = new CANNON.Body({mass: 0,shape: groundShape});groundBody.quaternion.setFromEuler( - Math.PI / 2, 0, 0);this.world.addBody(groundBody);}addBox(mesh: THREE.Mesh, mass: number = 1) : CANNON.Body {const geometry = mesh.geometry as THREE.BoxGeometry;const parameters = geometry.parameters;const shape = new CANNON.Box(new CANNON.Vec3(parameters.width / 2, parameters.height / 2, parameters.depth / 2));const body = new CANNON.Body({mass: mass,shape: shape,position: new CANNON.Vec3(mesh.position.x, mesh.position.y, mesh.position.z)});this.world.addBody(body);this.bodies.set(mesh, body);return body;}
}

物理引擎与渲染引擎的同步是关键环节。每一帧渲染前，我们都需要更新物理世界的状态，然后将物理体的位置和旋转同步到对应的Three.js网格对象上。这个过程看似简单，但必须精确执行，否则会出现视觉与物理不匹配的问题。

第三步：实现积木系统

现在我们可以创建各种类型的积木了。积木系统的设计采用了预设模式，每种积木都有预定义的尺寸、颜色和类型。这样的设计既保证了积木的一致性，又提供了足够的灵活性。

积木的创建过程包含了几何体构建、材质设置、物理体添加三个主要步骤。几何体定义了积木的形状，材质决定了它的外观，而物理体则赋予了它碰撞和重力特性。这三者必须精确对应，才能保证积木在视觉和物理上的表现一致。

export class BlockSystem {public static readonly BLOCK_PRESETS: BlockDefinition[] = [{type: BlockType.CUBE,size: new THREE.Vector3(1, 1, 1),color: 0xff6b6b,name: '标准立方体'},{type: BlockType.LONG_BLOCK,size: new THREE.Vector3(2, 0.5, 0.5),color: 0x4ecdc4,name: '长条积木'},{type: BlockType.FLAT_BLOCK,size: new THREE.Vector3(2, 0.25, 1),color: 0xf9ca24,name: '平板积木'},{type: BlockType.CYLINDER,size: new THREE.Vector3(0.5, 1, 0.5),color: 0x45b7d1,name: '圆柱积木'},{type: BlockType.SPHERE,size: new THREE.Vector3(0.5, 0.5, 0.5),color: 0xff9ff3,name: '球体积木'}];createBlock(definition: BlockDefinition, position: THREE.Vector3) : THREE.Mesh {let geometry: THREE.BufferGeometry;switch (definition.type) {case BlockType.CUBE:geometry = new THREE.BoxGeometry(definition.size.x, definition.size.y, definition.size.z);break;case BlockType.CYLINDER:geometry = new THREE.CylinderGeometry(definition.size.x, definition.size.x, definition.size.y, 32);break;case BlockType.SPHERE:geometry = new THREE.SphereGeometry(definition.size.x, 32, 32);break;default:geometry = new THREE.BoxGeometry(1, 1, 1);}const material = new THREE.MeshStandardMaterial({color: definition.color,roughness: 0.7,metalness: 0.3});const mesh = new THREE.Mesh(geometry, material);mesh.position.copy(position);mesh.castShadow = true;mesh.receiveShadow = true;this.scene.add(mesh);this.physics.addBox(mesh, 1);return mesh;}
}

为了提升用户体验，我们为每种积木设计了独特的视觉样式。立方体使用红色，长条积木是青色，平板积木为黄色。这种色彩编码帮助用户快速识别不同类型的积木，在搭建复杂结构时尤其有用。

第四步：开发拖拽交互系统

拖拽功能是积木搭建器的核心交互方式。用户需要能够抓取积木、移动到目标位置、然后释放。这个看似简单的交互背后，涉及射线检测、物理状态管理、拖拽平面计算等多个技术点。

射线检测是实现拖拽的基础。当用户点击屏幕时，我们从相机位置发射一条射线，检测它与场景中物体的交点。一旦检测到可拖拽物体，就进入拖拽状态。此时需要冻结物体的物理状态，否则重力会导致物体下落，影响拖拽体验。

export class DragControls {private onMouseDown(event: MouseEvent) : void {this.updateMousePosition(event);this.raycaster.setFromCamera(this.mouse, this.camera);const intersects = this.raycaster.intersectObjects(this.draggableObjects);if (intersects.length > 0) {const object = intersects[0].object as THREE.Mesh;this.selectedObject = object;this.isDragging = true;this.physics.freezeBody(object);const normal = new THREE.Vector3(0, 1, 0);this.dragPlane.setFromNormalAndCoplanarPoint(normal, intersects[0].point);this.offset.copy(intersects[0].point).sub(object.position);this.highlightObject(object, true);}}private onMouseMove(event: MouseEvent) : void {if (this.isDragging && this.selectedObject) {this.raycaster.setFromCamera(this.mouse, this.camera);const intersection = new THREE.Vector3();this.raycaster.ray.intersectPlane(this.dragPlane, intersection);if (intersection) {this.selectedObject.position.copy(intersection.sub(this.offset));const body = this.physics.getBody(this.selectedObject);if (body) {body.position.copy(this.selectedObject.position as any);}}}}
}

拖拽平面的概念很重要。为了让积木在3D空间中平滑移动，我们创建了一个虚拟平面，积木在这个平面上移动。平面的法向量始终朝上，确保积木保持水平移动，这样的设计符合用户的直觉预期。

第五步：构建自动化建筑系统

有了基础的积木系统后，我们可以实现更高级的功能：自动搭建建筑物。这个功能通过预定义的建筑结构，自动批量创建和放置积木，极大地提升了搭建效率。

房屋搭建器采用了模块化设计思路。地基、墙壁、屋顶、装饰等每个部分都是独立的模块，通过精确的坐标计算组合在一起。这种设计不仅让代码结构清晰，也便于后续扩展更多建筑类型。

export class HouseBuilder {buildSmallHouse(centerX: number = 0, centerZ: number = 0) : THREE.Mesh[] {const blocks: THREE.Mesh[] = [];const baseY = 0.125;// 搭建地基const foundation = [{x: centerX - 1,y: baseY,z: centerZ - 1},{x: centerX,y: baseY,z: centerZ - 1},{x: centerX + 1,y: baseY,z: centerZ - 1},// ... 更多地基位置];foundation.forEach(pos = >{const block = this.blockSystem.createBlock(BlockSystem.BLOCK_PRESETS.find(p = >p.type === BlockType.FLAT_BLOCK) ! , new THREE.Vector3(pos.x, pos.y, pos.z));this.dragControls.addDraggable(block);this.physics.freezeBody(block);blocks.push(block);});// 搭建墙壁const wallHeight = baseY + 0.75;const walls = [{x: centerX - 1,y: wallHeight,z: centerZ - 1},{x: centerX + 1,y: wallHeight,z: centerZ - 1},// ... 更多墙壁位置];walls.forEach(pos = >{const block = this.blockSystem.createBlock(BlockSystem.BLOCK_PRESETS.find(p = >p.type === BlockType.CUBE) ! , new THREE.Vector3(pos.x, pos.y, pos.z));this.dragControls.addDraggable(block);this.physics.freezeBody(block);blocks.push(block);});return blocks;}
}

建筑物的物理状态管理需要特别处理。我们使用freezeBody方法将建筑物的所有积木设置为静态，这样它们就不会受到重力影响而坍塌。但同时保留了拖拽功能，用户依然可以调整建筑物的位置或单个积木的摆放。

一个完整的小房子包含了地基、墙壁、屋顶、装饰和烟囱等多个部分。地基使用平板积木铺设，墙壁用立方体堆叠，屋顶再次使用平板覆盖，烟囱则用圆柱积木表现。这种分层搭建的思路，既符合真实建筑的构造方式，也让代码逻辑清晰易懂。

第六步：打造用户界面

完善的用户界面能显著提升应用的易用性。我们设计了一个侧边栏控制面板，提供积木选择、建筑搭建、场景控制等功能。界面采用半透明黑色背景，既保持美观又不遮挡3D场景。

界面布局经过精心设计。积木选择区域使用网格布局，每个按钮都标注了快捷键，方便用户快速操作。建筑搭建区提供一键搭建功能，用户只需点击按钮就能看到完整的建筑出现。场景控制区则包含清除、重置、重力开关等实用功能。

// 暴露给UI的全局函数
(window as any).buildHouse = () => {
houseBuilder.buildSmallHouse(0, 0);
updateStats();
}; (window as any).buildHouseWithGarden = () = >{houseBuilder.buildHouseWithGarden(0, 0);updateStats();
}; (window as any).toggleGravity = () = >{const gravity = physics.world.gravity;if (gravity.y === 0) {physics.world.gravity.set(0, -9.82, 0);} else {physics.world.gravity.set(0, 0, 0);}updateStats();
};
function updateStats() {const blockCountEl = document.getElementById('blockCount');const gravityStatusEl = document.getElementById('gravityStatus');if (blockCountEl) {blockCountEl.textContent = blockSystem.getBlockCount().toString();}if (gravityStatusEl) {const gravity = physics.world.gravity;gravityStatusEl.textContent = gravity.y === 0 ? '关闭': '开启';}
}

实时统计功能让用户随时了解场景状态。统计面板显示当前积木数量和重力开关状态，这些信息会在用户操作后自动更新。通过这些反馈，用户能更好地掌控整个搭建过程。

技术亮点与优化

整个项目的实现过程中，有几个值得特别说明的技术亮点。首先是物理引擎与渲染引擎的同步机制。我们在每一帧动画循环中，先更新物理世界状态，再将物理体的变换同步到Three.js对象，最后执行渲染。这个顺序保证了物理模拟的准确性和视觉的流畅性。

性能优化方面，我们采用了多项措施。阴影贴图分辨率设置为2048×2048，在质量和性能之间取得平衡。物理引擎的迭代次数设为10，既保证了碰撞检测的精度，又不会造成过大的计算负担。拖拽时冻结物理体的策略，避免了不必要的物理计算，提升了交互响应速度。

优化项目	优化方案	效果说明
渲染性能	PCF软阴影 + 合理贴图分辨率	在保证视觉效果前提下降低GPU负担
物理计算	拖拽时冻结物理体	减少不必要的碰撞检测和物理模拟
内存管理	及时释放不用的几何体和材质	避免内存泄漏，保持应用长时间稳定运行
交互响应	事件节流和防抖	减少事件处理频率，提升交互流畅度

代码架构的设计遵循了单一职责原则。物理世界管理、积木系统、拖拽控制、建筑搭建等功能都封装在独立的类中，各司其职。这种模块化设计不仅让代码易于理解和维护，也为后续功能扩展提供了良好的基础。

源码地址

GithHub: https://github.com/Damon-Liu-code/3D-building-block-simulator
InsCode: https://inscode.csdn.net/@weixin_41793160/3D-building-block-simulator
在线运行: https://3d-simulator.inscode.cc/

总结与展望

通过这个项目的实践，我们从零开始构建了一个功能完整的3D积木搭建器。从基础的3D场景搭建，到物理引擎集成，再到复杂的拖拽交互和自动化建筑系统，每一步都凝聚了对3D应用开发的深入理解。

对于有志于XR应用开发的开发者，这个项目提供了一个很好的学习起点。掌握了这些基础技术后，可以进一步探索更高级的主题，如WebXR API的使用、AR内容的开发、或是在Rokid等专业XR平台上构建应用。空间计算的时代已经到来，现在正是投身这个领域的最佳时机。让我们一起探索3D交互应用的无限可能，在虚拟与现实交融的未来中，创造出更加精彩的应用体验。