简介本资源是一个基于three.js与cannon.js构建的开放世界基础框架源码面向具备前端开发基础、希望快速入门3D场景与物理交互开发的中高级开发者。它解决了从零搭建可运行、可扩展3D开放世界的技术门槛问题覆盖场景渲染、刚体物理模拟、模型加载、UI控制及性能优化等核心环节。压缩包共237个文件含181个TypeScript主逻辑模块保障类型安全与工程可维护性、9个GLB三维模型、9个CSS样式表如loadingScreen.css、welcomeScreen.css等用于交互界面与视觉反馈、5个PNG纹理资源、4个JSON配置及2个WebAssembly模块用于高性能物理或渲染计算整体大小为66.09MB。已有284人学习下载。读者可直接复用其模块化架构、标准化资源配置方式与完整构建流程含webpack、tsconfig.json、package.json等快速启动个人3D项目并基于现有19个JS脚本兼容层、2个Markdown文档说明及清晰目录结构进行二次开发与功能拓展。1. 项目缘起为什么我们需要一个“开放世界”基础框架最近在捣鼓一些3D互动项目从简单的产品展示到复杂的模拟场景我发现很多需求最终都指向了同一个方向一个能跑、能跳、能交互的“小世界”。你可能想做一个多人在线的虚拟展厅或者一个物理模拟的科普应用又或者是一个带有简单游戏逻辑的互动故事。这些项目听起来五花八门但底层需求惊人地一致它们都需要一个三维场景来承载内容需要物理规则让物体“活”起来还需要一套清晰的代码结构来管理这个日益复杂的世界。这就是我动手搭建这个基于 three.js 和 cannon.js 的开放世界基础框架的初衷。我不想每次启动新项目都从零开始复制粘贴一堆散乱的代码然后花大量时间去解决相机控制、物理同步、对象管理这些重复性问题。我需要一个“地基”——一个经过验证的、模块化的、易于扩展的起点。它不追求实现某个特定游戏的完整玩法而是专注于解决构建一个可交互三维世界时最通用、最棘手的那些基础问题如何高效地组织场景图如何让视觉渲染和物理模拟和谐共处如何设计一个清晰的事件和状态管理系统这个框架的源码就是我对于这些问题交出的一份答卷。简单来说这个框架的目标是让你能快速搭建一个具备基础物理交互和对象管理能力的三维场景并把主要精力集中在创造独特的业务逻辑和内容上而不是反复调试相机碰撞或者物体穿透。2. 核心架构设计渲染与物理的“双线程”协同一个稳定的开放世界框架其核心在于如何处理渲染three.js与物理cannon.js这两个独立体系之间的关系。它们就像两个并行的线程一个负责计算物体的位置、旋转、碰撞物理线程另一个负责将这些计算结果美观地绘制到屏幕上渲染线程。设计不当就会出现物体抖动、穿透、或者性能低下等问题。2.1 实体-组件模式一切对象的基石我放弃了传统的继承层次结构转而采用了更灵活的实体-组件Entity-Component模式。在这个框架里世界中的每一个物体玩家、箱子、地面、子弹都是一个“实体”Entity它本身只是一个空壳一个唯一的ID标识。所有功能都以“组件”Component的形式挂载到这个实体上。// 示例创建一个带有渲染和物理功能的箱子 import { Entity } from ‘./core/Entity’; import { MeshComponent } from ‘./components/MeshComponent’; import { RigidBodyComponent } from ‘./components/RigidBodyComponent’; const boxEntity new Entity(‘crate_01’); // 添加视觉组件一个Three.js网格 const meshComp new MeshComponent(); meshComp.setGeometry(new THREE.BoxGeometry(1, 1, 1)); meshComp.setMaterial(new THREE.MeshStandardMaterial({ color: 0x8B4513 })); boxEntity.addComponent(meshComp); // 添加物理组件一个Cannon.js刚体 const physicsComp new RigidBodyComponent(); physicsComp.setShape(new CANNON.Box(new CANNON.Vec3(0.5, 0.5, 0.5))); physicsComp.setMass(5); // 5公斤重 boxEntity.addComponent(physicsComp); // 将实体添加到世界管理器 world.addEntity(boxEntity);这种设计的好处显而易见解耦与复用MeshComponent只关心如何渲染RigidBodyComponent只关心物理属性。我可以轻松创建一个只有视觉没有物理的装饰物如云朵或者一个只有物理没有视觉的触发器区域。动态组合运行时可以动态添加或移除组件。比如一个物体被击中后我可以移除它的RigidBodyComponent使其变成静态装饰同时添加一个ParticleComponent来播放爆炸特效。数据驱动实体的配置可以很容易地从JSON等数据文件加载便于关卡设计和内容管理。2.2 世界管理器中枢调度与生命周期World类是这个框架的绝对核心它扮演着管理员的角色职责包括实体管理维护所有实体的注册表负责它们的添加、移除、查询和遍历。通过实体ID可以快速找到任何对象。组件系统更新它维护着一个组件类型的列表如PhysicsSystem,RenderSystem。在每一帧的更新循环中World会依次调用这些系统的update(deltaTime)方法。例如PhysicsSystem会步进物理世界RenderSystem会更新所有需要每帧变化的材质或动画。渲染与物理桥接这是最关键的部分。框架内部实现了一个PhysicsSyncSystem。在物理系统更新后这个同步系统会遍历所有同时拥有RigidBodyComponent和MeshComponent的实体将Cannon.js刚体的position和quaternion四元数用于旋转复制给Three.js网格的对应属性。注意一定是“复制”而非引用以避免直接修改物理引擎的内部数据。// 简化的同步系统核心逻辑 class PhysicsSyncSystem { update(deltaTime) { const entities world.getEntitiesWith(‘RigidBodyComponent’, ‘MeshComponent’); for (const entity of entities) { const rigidBody entity.getComponent(‘RigidBodyComponent’).body; const mesh entity.getComponent(‘MeshComponent’).mesh; // 同步位置 mesh.position.copy(rigidBody.position); // 同步旋转使用四元数避免万向节锁 mesh.quaternion.copy(rigidBody.quaternion); } } }2.3 事件总线松耦合的通信机制在开放世界中对象间的交互错综复杂。玩家捡起物品、子弹击中目标、触发器被激活……如果让这些对象直接互相引用并调用方法代码会迅速变成一团乱麻“面条代码”。我引入了一个全局的、轻量级的事件总线Event Bus来解决这个问题。当一个事件发生时如“碰撞”发起者只需要向事件总线发布一个事件对象而不需要知道谁会对这个事件感兴趣。其他系统或实体可以订阅它们关心的事件类型。// 在物理系统中检测到碰撞时发布事件 eventBus.publish(‘COLLISION’, { entityA: entityAId, entityB: entityBId, contactPoint: contact.point, impulse: contact.getImpactVelocityAlongNormal() }); // 在音效系统中订阅碰撞事件来播放声音 eventBus.subscribe(‘COLLISION’, (eventData) { const materialA getMaterialOf(entityAId); const materialB getMaterialOf(entityBId); const volume calculateVolumeFromImpulse(eventData.impulse); playCollisionSound(materialA, materialB, volume); }); // 在游戏逻辑系统中订阅碰撞事件来判断是否击毁目标 eventBus.subscribe(‘COLLISION’, (eventData) { if (isBullet(eventData.entityA) isEnemy(eventData.entityB)) { world.destroyEntity(eventData.entityB); // 销毁敌人实体 increasePlayerScore(100); } });这种方式实现了极致的解耦。音效系统不知道物理系统如何工作游戏逻辑系统也不直接操作实体它们都只与事件总线对话。添加新功能比如一个碰撞火花特效系统变得非常简单只需订阅相应事件即可。3. 物理与渲染集成详解从“穿透”到“严丝合缝”将Cannon.js整合进Three.js场景远不止是同步位置那么简单。这里面充满了陷阱也是框架价值最集中的体现。3.1 形状匹配与视觉偏移最常见的坑是视觉网格与物理形状不匹配。Three.js的BoxGeometry默认以几何中心为原点且尺寸是“宽度”。而Cannon.js的Box形状参数是“半扩展”half-extents即从中心到各面的距离。// 创建一个1x2x3的盒子 const visualWidth 1, visualHeight 2, visualDepth 3; // Three.js 网格 const geometry new THREE.BoxGeometry(visualWidth, visualHeight, visualDepth); const mesh new THREE.Mesh(geometry, material); // 网格的原点默认在几何中心 // Cannon.js 刚体形状 (正确匹配) const halfExtents new CANNON.Vec3(visualWidth / 2, visualHeight / 2, visualDepth / 2); const boxShape new CANNON.Box(halfExtents); // 错误示例直接使用视觉尺寸 // const wrongShape new CANNON.Box(new CANNON.Vec3(visualWidth, visualHeight, visualDepth)); // 这会导致物理盒子比视觉盒子大一倍对于更复杂的模型比如一个角色其视觉网格的原点可能在脚底便于站立但物理胶囊体的原点应该在几何中心。这时就需要在RigidBodyComponent中引入一个offset属性用于存储物理体相对于视觉网格的偏移量并在同步位置时进行补偿计算。3.2 静态与动态物体优化物理世界中的物体分为静态、动态和运动学Kinematic几种。对它们的处理方式直接影响性能和效果。静态物体质量0如地面、墙壁。它们在物理世界中永不移动。框架在初始化时会将所有静态物体的物理体添加到一个静态集合中。物理引擎内部会对这类物体做大量优化如宽相位检测的优化因此不要滥用。一个常见的错误是给每一片草或每一粒石子都加一个静态刚体这会导致物理世界初始化极其缓慢。正确的做法是使用一个大的静态碰撞体如一个高度图或一个大的组合形状来代表整个地面。动态物体质量0受重力影响会因碰撞而运动。框架需要确保每一帧都同步它们的位置和旋转。运动学物体由代码而非物理引擎控制其运动但能影响动态物体。比如移动的平台。框架需要将代码设置的位置反向同步给物理引擎。在Cannon.js中可以通过设置刚体的type为Body.KINEMATIC并手动更新其position和velocity来实现。3.3 碰撞过滤与分组不是所有物体都应该相互碰撞。玩家不应该和自己发射的子弹碰撞幽灵应该穿透墙壁。Cannon.js提供了碰撞过滤组collisionFilterGroup和掩码collisionFilterMask机制。框架对此进行了封装允许通过组件属性来定义实体的碰撞类别。// 定义碰撞分组常量 export const COLLISION_GROUPS { DEFAULT: 1, PLAYER: 2, ENEMY: 4, PROJECTILE: 8, TRIGGER: 16, // ... 使用2的幂次方便于按位操作 }; // 在RigidBodyComponent中配置 const rbComp new RigidBodyComponent(); rbComp.collisionGroup COLLISION_GROUPS.PLAYER; // 玩家只与ENEMY, DEFAULT地面碰撞不与PROJECTILE自己的子弹碰撞 rbComp.collisionMask COLLISION_GROUPS.ENEMY | COLLISION_GROUPS.DEFAULT; // 在PhysicsSystem中创建刚体时应用这些设置 const body new CANNON.Body({ mass: 1 }); body.collisionFilterGroup component.collisionGroup; body.collisionFilterMask component.collisionMask;这样复杂的碰撞关系可以通过简单的位运算来管理既高效又清晰。4. 核心系统实现输入、相机与场景管理有了稳定的物理-渲染基础接下来需要构建与世界交互的通道。4.1 输入抽象层统一桌面与移动端开放世界需要复杂的输入控制。框架实现了一个InputManager它抽象了键盘、鼠标、触摸甚至游戏手柄的输入提供统一的查询接口。class InputManager { constructor(domElement) { this.keyStates new Map(); this.mouse { x: 0, y: 0, button: 0 }; this.touches new Map(); // ... 初始化事件监听 domElement.addEventListener(‘keydown’, this._onKeyDown.bind(this)); domElement.addEventListener(‘mousemove’, this._onMouseMove.bind(this)); // 对于触摸将多个触点映射为虚拟的“鼠标”或自定义手势 } isKeyPressed(keyCode) { return this.keyStates.get(keyCode) true; } getMouseDelta() { /* 返回上一帧到这一帧的鼠标移动量 */ } getPinchScale() { /* 处理双指缩放手势 */ } // 在World的每一帧更新中调用用于计算差值等 update() { this._lastMouseX this.mouse.x; // ... 其他逻辑 } }更重要的是InputManager也作为动作的映射层。你可以定义如“MoveForward”、“Jump”、“PrimaryFire”等虚拟动作然后绑定到不同的物理按键或触摸区域上。这样改变控制方案时只需修改映射关系而不需要改动游戏逻辑代码。4.2 智能相机控制器Three.js自带的OrbitControls适合查看模型但不适合用于角色控制。一个开放世界框架需要一个更强大的相机控制器。我实现了一个ThirdPersonCameraController它包含几个核心功能弹簧延迟跟随相机不是死死贴在角色身后而是像用一根弹簧拉着一样有一个平滑的延迟跟随效果。这能避免急停急转时镜头剧烈晃动提升舒适感。实现上我们使用线性插值Lerp或更复杂的阻尼弹簧算法来计算相机每一帧的目标位置。// 简化的弹簧跟随逻辑 const currentCameraPos camera.position; const targetPos player.position.clone().add(new THREE.Vector3(0, 5, -10)); // 假设目标在玩家后方上方 const smoothTime 0.1; // 平滑时间系数 // 使用 THREE.MathUtils.lerp 或自定义的阻尼函数 camera.position.lerp(targetPos, smoothTime);碰撞检测与规避当相机和玩家之间出现墙壁或树木时不能让它穿模。解决方案是从玩家头部向相机目标位置发射一条射线Raycast。如果检测到碰撞就将相机位置拉近到碰撞点前方一点的位置。同时当障碍物移开后相机再平滑地回到原位。鼠标/触摸控制视角将鼠标移动或单指拖拽的位移转换为相机围绕玩家的旋转角度偏航Yaw和俯仰角度Pitch并设置合理的上下限防止镜头穿到地面以下或天上。4.3 动态场景加载与LOD对于“开放世界”即使基础框架不直接实现大地形流式加载也需要为这种可能性设计接口。一个核心概念是“场景区块”Chunk管理。框架中的SceneManager负责管理一个主场景THREE.Scene但它也维护着一个以空间坐标如[chunkX, chunkZ]为键的区块地图。每个区块可以包含一组实体并可以独立加载和卸载。class SceneManager { constructor() { this.mainScene new THREE.Scene(); this.loadedChunks new Map(); // Map‘x,z’, { entities: Entity[], meshGroup: THREE.Group } this.playerChunkCoord null; } update(playerPosition) { // 1. 根据玩家位置计算当前所在区块坐标 const newChunkCoord this._calculateChunkCoord(playerPosition); // 2. 如果区块发生变化触发加载/卸载逻辑 if (!this._compareCoords(newChunkCoord, this.playerChunkCoord)) { this._onPlayerChunkChanged(newChunkCoord, this.playerChunkCoord); this.playerChunkCoord newChunkCoord; } // 3. 更新当前已加载区块内可能需要更新的内容如LOD this._updateActiveChunks(); } _onPlayerChunkChanged(newCoord, oldCoord) { // 计算需要加载的新区块和需要卸载的旧区块 const toLoad this._getChunksInRadius(newCoord, RENDER_DISTANCE); const toUnload this._getChunksInRadius(oldCoord, RENDER_DISTANCE); // 异步加载新区块的资源并实例化实体 this._loadChunksAsync(toLoad); // 卸载旧区块销毁实体释放资源 this._unloadChunks(toUnload); } }配合区块管理可以很容易地集成细节层次LOD系统。对于远处的物体使用面数少的简化模型当玩家靠近时再切换为高精度模型。Three.js本身提供了THREE.LOD对象框架可以将其封装到MeshComponent中根据实体与相机的距离自动管理不同层级的模型切换。5. 性能优化与调试实践一个框架如果性能低下或难以调试就失去了实用价值。以下是框架中内置的几个关键优化和调试手段。5.1 物理引擎的性能陷阱与规避Cannon.js是一个纯JavaScript实现的物理引擎在复杂场景下可能成为性能瓶颈。控制刚体数量这是最重要的原则。尽可能减少动态刚体的数量。能用少量复杂形状如CANNON.Trimesh或CANNON.ConvexPolyhedron就不要用大量简单形状堆砌。合理设置步长物理世界的更新频率world.step(fixedTimeStep)通常独立于渲染帧率。fixedTimeStep一般设为1/60约0.0167秒。即使游戏帧率掉到30帧物理世界也以60Hz的固定频率模拟这能保证物理行为的稳定性和可重现性。但步长越小计算越频繁。需要在精度和性能间权衡。使用“睡眠”机制静止的物体如落在地上不再滚动的球应该让其“睡眠”。Cannon.js的刚体有allowSleep和sleepSpeedLimit属性。当刚体速度低于某个阈值一段时间后引擎会将其置为睡眠状态不再参与每帧的碰撞和运动计算直到被其他物体碰撞唤醒。框架应在RigidBodyComponent中默认开启此选项。5.2 渲染侧的优化策略合并绘制调用对于大量静态且材质相同的小物体如草地、碎石使用THREE.InstancedMesh进行实例化渲染。它能将成千上万个物体的绘制合并为一次GPU调用性能提升是数量级的。框架可以提供InstancedMeshComponent来简化这一过程。视锥体剔除Three.js的渲染器默认会进行视锥体剔除Frustum Culling不渲染相机视野外的物体。但我们的SceneManager在区块层面进行的加载/卸载是更粗粒度、更有效的剔除避免了不必要的内存占用和CPU处理。着色器与材质优化避免在每一帧动态创建或编译着色器。尽量复用材质。对于需要大量重复但参数略有不同的物体如不同颜色的箱子考虑使用顶点颜色或纹理图集而不是为每个箱子创建独立的材质实例。5.3 强大的调试可视化调试物理世界是噩梦因为你看不到碰撞体。框架必须集成一个可开关的调试渲染器。物理调试渲染遍历物理世界中的所有刚体根据其形状Box, Sphere, Cylinder等用Three.js的线框几何体THREE.LineSegments在对应的位置、旋转和尺寸上绘制出来。这能让你清晰地看到每一个碰撞体的边界。射线检测可视化当进行射线检测如拾取物体、相机碰撞检测时可以将射线的路径和命中点用一条彩色的线实时绘制出来。性能面板在屏幕一角创建一个简单的THREE.Sprite或使用CSS叠加层显示当前帧率FPS、实体数量、三角形数量、物理步进时间等关键指标。这能帮助你快速定位性能热点。class DebugRenderer { constructor(physicsWorld, scene) { this.physicsWorld physicsWorld; this.debugScene new THREE.Scene(); this.meshes new Map(); // 存储刚体ID到线框网格的映射 } update() { // 清除上一帧的调试网格 // ... // 遍历所有刚体创建或更新对应的线框网格 this.physicsWorld.bodies.forEach(body { if (!body.shapes.length) return; const debugMesh this._createDebugMeshForBody(body); this.debugScene.add(debugMesh); }); // 最后用另一个渲染通道或叠加渲染器将debugScene画出来 } }将这些调试工具集成到框架中并通过一个全局配置变量如window.DEBUG true来控制开关能极大提升开发效率。6. 从框架到项目构建你的第一个世界理论说了这么多我们来看看如何用这个框架快速启动一个项目。6.1 项目初始化与配置假设你已经通过npm或直接引入的方式获得了框架源码。项目结构可能如下your-project/ ├── src/ │ ├── main.js # 应用入口 │ ├── systems/ # 自定义系统可选 │ ├── components/ # 自定义组件可选 │ └── entities/ # 自定义实体定义可选 ├── assets/ # 模型、纹理等资源 └── public/ └── index.html在main.js中你需要进行标准化的初始化import { World } from ‘./framework/core/World’; import { RenderSystem } from ‘./framework/systems/RenderSystem’; import { PhysicsSystem } from ‘./framework/systems/PhysicsSystem’; import { InputManager } from ‘./framework/core/InputManager’; import { ThirdPersonCameraController } from ‘./framework/controllers/ThirdPersonCameraController’; // 1. 初始化三大核心 const world new World(); const renderer new THREE.WebGLRenderer({ antialias: true }); const inputManager new InputManager(document.body); // 2. 创建并添加核心系统 world.registerSystem(new RenderSystem(renderer, document.getElementById(‘app’))); world.registerSystem(new PhysicsSystem()); // ... 注册其他系统如PhysicsSyncSystem, InputSystem等 // 3. 设置相机和控制器 const camera new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000); const cameraController new ThirdPersonCameraController(camera); world.registerSystem(cameraController); // 相机控制器本身也可以作为一个系统 // 4. 创建基础场景地面、灯光、天空盒 const groundEntity createGroundEntity(); // 一个辅助函数创建带物理的静态地面 world.addEntity(groundEntity); // ... 创建灯光、天空盒等环境实体 // 5. 创建玩家实体 const playerEntity createPlayerEntity(inputManager, cameraController); world.addEntity(playerEntity); // 6. 启动游戏循环 function gameLoop(timestamp) { const deltaTime (timestamp - lastTime) / 1000; // 转换为秒 lastTime timestamp; // 更新输入状态 inputManager.update(); // 更新世界这会驱动所有已注册系统的update方法 world.update(deltaTime); // 渲染系统会在其update中执行渲染 requestAnimationFrame(gameLoop); } let lastTime 0; requestAnimationFrame(gameLoop);6.2 扩展框架创建一个自定义“拾取”组件框架的威力在于易于扩展。假设你想实现一个“拾取物品”的功能。创建新组件在src/components/下创建PickableComponent.js。它可能包含属性如itemType物品类型、pickupRadius拾取半径等。创建新系统在src/systems/下创建PickupSystem.js。这个系统会在每帧更新中检查所有带有PickableComponent的实体与玩家实体之间的距离。如果距离小于拾取半径则发布一个PICKUP_AVAILABLE事件。响应事件在玩家控制逻辑中或另一个专门的PlayerInteractionSystem中订阅PICKUP_AVAILABLE事件。当玩家按下“拾取”键由InputManager映射时检查最近的可用拾取物然后发布ITEM_PICKED事件。处理拾取一个InventorySystem可以订阅ITEM_PICKED事件更新玩家的背包数据并调用world.destroyEntity来销毁或隐藏被拾取的实体。通过这种方式一个复杂的交互功能被清晰地分解为组件、系统和事件完美融入框架的架构之中。6.3 打包与部署考量对于正式项目你需要考虑打包。使用Webpack或Vite等工具将你的代码和框架代码打包优化。注意Tree Shaking确保你的打包工具能剔除框架中未使用的代码。这要求框架源码必须采用ES6模块化导出。资源加载对于模型和纹理使用Three.js的GLTFLoader、TextureLoader等并考虑使用加载管理器LoadingManager来显示进度条。生产环境优化关闭调试模式压缩JavaScript代码可能的话将物理引擎的精度从高精度模式调整为平衡模式。这个框架的源码提供了一个坚实的起点但它不是终点。它定义了一套清晰的规则和模式让你在构建自己的三维世界时能专注于创造性的工作而不是在底层技术的泥潭中挣扎。当你熟悉了实体、组件、系统和事件的协作方式后你会发现添加新的特性、调试问题、甚至优化性能都变得有迹可循。这正是设计一个良好框架的意义所在它不限制你的想象力而是为你实现想象力提供了最可靠的工具。本文还有配套的精品资源点击获取
简介本资源是一个基于three.js与cannon.js构建的开放世界基础框架源码面向具备前端开发基础、希望快速入门3D场景与物理交互开发的中高级开发者。它解决了从零搭建可运行、可扩展3D开放世界的技术门槛问题覆盖场景渲染、刚体物理模拟、模型加载、UI控制及性能优化等核心环节。压缩包共237个文件含181个TypeScript主逻辑模块保障类型安全与工程可维护性、9个GLB三维模型、9个CSS样式表如loadingScreen.css、welcomeScreen.css等用于交互界面与视觉反馈、5个PNG纹理资源、4个JSON配置及2个WebAssembly模块用于高性能物理或渲染计算整体大小为66.09MB。已有284人学习下载。读者可直接复用其模块化架构、标准化资源配置方式与完整构建流程含webpack、tsconfig.json、package.json等快速启动个人3D项目并基于现有19个JS脚本兼容层、2个Markdown文档说明及清晰目录结构进行二次开发与功能拓展。1. 项目缘起为什么我们需要一个“开放世界”基础框架最近在捣鼓一些3D互动项目从简单的产品展示到复杂的模拟场景我发现很多需求最终都指向了同一个方向一个能跑、能跳、能交互的“小世界”。你可能想做一个多人在线的虚拟展厅或者一个物理模拟的科普应用又或者是一个带有简单游戏逻辑的互动故事。这些项目听起来五花八门但底层需求惊人地一致它们都需要一个三维场景来承载内容需要物理规则让物体“活”起来还需要一套清晰的代码结构来管理这个日益复杂的世界。这就是我动手搭建这个基于 three.js 和 cannon.js 的开放世界基础框架的初衷。我不想每次启动新项目都从零开始复制粘贴一堆散乱的代码然后花大量时间去解决相机控制、物理同步、对象管理这些重复性问题。我需要一个“地基”——一个经过验证的、模块化的、易于扩展的起点。它不追求实现某个特定游戏的完整玩法而是专注于解决构建一个可交互三维世界时最通用、最棘手的那些基础问题如何高效地组织场景图如何让视觉渲染和物理模拟和谐共处如何设计一个清晰的事件和状态管理系统这个框架的源码就是我对于这些问题交出的一份答卷。简单来说这个框架的目标是让你能快速搭建一个具备基础物理交互和对象管理能力的三维场景并把主要精力集中在创造独特的业务逻辑和内容上而不是反复调试相机碰撞或者物体穿透。2. 核心架构设计渲染与物理的“双线程”协同一个稳定的开放世界框架其核心在于如何处理渲染three.js与物理cannon.js这两个独立体系之间的关系。它们就像两个并行的线程一个负责计算物体的位置、旋转、碰撞物理线程另一个负责将这些计算结果美观地绘制到屏幕上渲染线程。设计不当就会出现物体抖动、穿透、或者性能低下等问题。2.1 实体-组件模式一切对象的基石我放弃了传统的继承层次结构转而采用了更灵活的实体-组件Entity-Component模式。在这个框架里世界中的每一个物体玩家、箱子、地面、子弹都是一个“实体”Entity它本身只是一个空壳一个唯一的ID标识。所有功能都以“组件”Component的形式挂载到这个实体上。// 示例创建一个带有渲染和物理功能的箱子 import { Entity } from ‘./core/Entity’; import { MeshComponent } from ‘./components/MeshComponent’; import { RigidBodyComponent } from ‘./components/RigidBodyComponent’; const boxEntity new Entity(‘crate_01’); // 添加视觉组件一个Three.js网格 const meshComp new MeshComponent(); meshComp.setGeometry(new THREE.BoxGeometry(1, 1, 1)); meshComp.setMaterial(new THREE.MeshStandardMaterial({ color: 0x8B4513 })); boxEntity.addComponent(meshComp); // 添加物理组件一个Cannon.js刚体 const physicsComp new RigidBodyComponent(); physicsComp.setShape(new CANNON.Box(new CANNON.Vec3(0.5, 0.5, 0.5))); physicsComp.setMass(5); // 5公斤重 boxEntity.addComponent(physicsComp); // 将实体添加到世界管理器 world.addEntity(boxEntity);这种设计的好处显而易见解耦与复用MeshComponent只关心如何渲染RigidBodyComponent只关心物理属性。我可以轻松创建一个只有视觉没有物理的装饰物如云朵或者一个只有物理没有视觉的触发器区域。动态组合运行时可以动态添加或移除组件。比如一个物体被击中后我可以移除它的RigidBodyComponent使其变成静态装饰同时添加一个ParticleComponent来播放爆炸特效。数据驱动实体的配置可以很容易地从JSON等数据文件加载便于关卡设计和内容管理。2.2 世界管理器中枢调度与生命周期World类是这个框架的绝对核心它扮演着管理员的角色职责包括实体管理维护所有实体的注册表负责它们的添加、移除、查询和遍历。通过实体ID可以快速找到任何对象。组件系统更新它维护着一个组件类型的列表如PhysicsSystem,RenderSystem。在每一帧的更新循环中World会依次调用这些系统的update(deltaTime)方法。例如PhysicsSystem会步进物理世界RenderSystem会更新所有需要每帧变化的材质或动画。渲染与物理桥接这是最关键的部分。框架内部实现了一个PhysicsSyncSystem。在物理系统更新后这个同步系统会遍历所有同时拥有RigidBodyComponent和MeshComponent的实体将Cannon.js刚体的position和quaternion四元数用于旋转复制给Three.js网格的对应属性。注意一定是“复制”而非引用以避免直接修改物理引擎的内部数据。// 简化的同步系统核心逻辑 class PhysicsSyncSystem { update(deltaTime) { const entities world.getEntitiesWith(‘RigidBodyComponent’, ‘MeshComponent’); for (const entity of entities) { const rigidBody entity.getComponent(‘RigidBodyComponent’).body; const mesh entity.getComponent(‘MeshComponent’).mesh; // 同步位置 mesh.position.copy(rigidBody.position); // 同步旋转使用四元数避免万向节锁 mesh.quaternion.copy(rigidBody.quaternion); } } }2.3 事件总线松耦合的通信机制在开放世界中对象间的交互错综复杂。玩家捡起物品、子弹击中目标、触发器被激活……如果让这些对象直接互相引用并调用方法代码会迅速变成一团乱麻“面条代码”。我引入了一个全局的、轻量级的事件总线Event Bus来解决这个问题。当一个事件发生时如“碰撞”发起者只需要向事件总线发布一个事件对象而不需要知道谁会对这个事件感兴趣。其他系统或实体可以订阅它们关心的事件类型。// 在物理系统中检测到碰撞时发布事件 eventBus.publish(‘COLLISION’, { entityA: entityAId, entityB: entityBId, contactPoint: contact.point, impulse: contact.getImpactVelocityAlongNormal() }); // 在音效系统中订阅碰撞事件来播放声音 eventBus.subscribe(‘COLLISION’, (eventData) { const materialA getMaterialOf(entityAId); const materialB getMaterialOf(entityBId); const volume calculateVolumeFromImpulse(eventData.impulse); playCollisionSound(materialA, materialB, volume); }); // 在游戏逻辑系统中订阅碰撞事件来判断是否击毁目标 eventBus.subscribe(‘COLLISION’, (eventData) { if (isBullet(eventData.entityA) isEnemy(eventData.entityB)) { world.destroyEntity(eventData.entityB); // 销毁敌人实体 increasePlayerScore(100); } });这种方式实现了极致的解耦。音效系统不知道物理系统如何工作游戏逻辑系统也不直接操作实体它们都只与事件总线对话。添加新功能比如一个碰撞火花特效系统变得非常简单只需订阅相应事件即可。3. 物理与渲染集成详解从“穿透”到“严丝合缝”将Cannon.js整合进Three.js场景远不止是同步位置那么简单。这里面充满了陷阱也是框架价值最集中的体现。3.1 形状匹配与视觉偏移最常见的坑是视觉网格与物理形状不匹配。Three.js的BoxGeometry默认以几何中心为原点且尺寸是“宽度”。而Cannon.js的Box形状参数是“半扩展”half-extents即从中心到各面的距离。// 创建一个1x2x3的盒子 const visualWidth 1, visualHeight 2, visualDepth 3; // Three.js 网格 const geometry new THREE.BoxGeometry(visualWidth, visualHeight, visualDepth); const mesh new THREE.Mesh(geometry, material); // 网格的原点默认在几何中心 // Cannon.js 刚体形状 (正确匹配) const halfExtents new CANNON.Vec3(visualWidth / 2, visualHeight / 2, visualDepth / 2); const boxShape new CANNON.Box(halfExtents); // 错误示例直接使用视觉尺寸 // const wrongShape new CANNON.Box(new CANNON.Vec3(visualWidth, visualHeight, visualDepth)); // 这会导致物理盒子比视觉盒子大一倍对于更复杂的模型比如一个角色其视觉网格的原点可能在脚底便于站立但物理胶囊体的原点应该在几何中心。这时就需要在RigidBodyComponent中引入一个offset属性用于存储物理体相对于视觉网格的偏移量并在同步位置时进行补偿计算。3.2 静态与动态物体优化物理世界中的物体分为静态、动态和运动学Kinematic几种。对它们的处理方式直接影响性能和效果。静态物体质量0如地面、墙壁。它们在物理世界中永不移动。框架在初始化时会将所有静态物体的物理体添加到一个静态集合中。物理引擎内部会对这类物体做大量优化如宽相位检测的优化因此不要滥用。一个常见的错误是给每一片草或每一粒石子都加一个静态刚体这会导致物理世界初始化极其缓慢。正确的做法是使用一个大的静态碰撞体如一个高度图或一个大的组合形状来代表整个地面。动态物体质量0受重力影响会因碰撞而运动。框架需要确保每一帧都同步它们的位置和旋转。运动学物体由代码而非物理引擎控制其运动但能影响动态物体。比如移动的平台。框架需要将代码设置的位置反向同步给物理引擎。在Cannon.js中可以通过设置刚体的type为Body.KINEMATIC并手动更新其position和velocity来实现。3.3 碰撞过滤与分组不是所有物体都应该相互碰撞。玩家不应该和自己发射的子弹碰撞幽灵应该穿透墙壁。Cannon.js提供了碰撞过滤组collisionFilterGroup和掩码collisionFilterMask机制。框架对此进行了封装允许通过组件属性来定义实体的碰撞类别。// 定义碰撞分组常量 export const COLLISION_GROUPS { DEFAULT: 1, PLAYER: 2, ENEMY: 4, PROJECTILE: 8, TRIGGER: 16, // ... 使用2的幂次方便于按位操作 }; // 在RigidBodyComponent中配置 const rbComp new RigidBodyComponent(); rbComp.collisionGroup COLLISION_GROUPS.PLAYER; // 玩家只与ENEMY, DEFAULT地面碰撞不与PROJECTILE自己的子弹碰撞 rbComp.collisionMask COLLISION_GROUPS.ENEMY | COLLISION_GROUPS.DEFAULT; // 在PhysicsSystem中创建刚体时应用这些设置 const body new CANNON.Body({ mass: 1 }); body.collisionFilterGroup component.collisionGroup; body.collisionFilterMask component.collisionMask;这样复杂的碰撞关系可以通过简单的位运算来管理既高效又清晰。4. 核心系统实现输入、相机与场景管理有了稳定的物理-渲染基础接下来需要构建与世界交互的通道。4.1 输入抽象层统一桌面与移动端开放世界需要复杂的输入控制。框架实现了一个InputManager它抽象了键盘、鼠标、触摸甚至游戏手柄的输入提供统一的查询接口。class InputManager { constructor(domElement) { this.keyStates new Map(); this.mouse { x: 0, y: 0, button: 0 }; this.touches new Map(); // ... 初始化事件监听 domElement.addEventListener(‘keydown’, this._onKeyDown.bind(this)); domElement.addEventListener(‘mousemove’, this._onMouseMove.bind(this)); // 对于触摸将多个触点映射为虚拟的“鼠标”或自定义手势 } isKeyPressed(keyCode) { return this.keyStates.get(keyCode) true; } getMouseDelta() { /* 返回上一帧到这一帧的鼠标移动量 */ } getPinchScale() { /* 处理双指缩放手势 */ } // 在World的每一帧更新中调用用于计算差值等 update() { this._lastMouseX this.mouse.x; // ... 其他逻辑 } }更重要的是InputManager也作为动作的映射层。你可以定义如“MoveForward”、“Jump”、“PrimaryFire”等虚拟动作然后绑定到不同的物理按键或触摸区域上。这样改变控制方案时只需修改映射关系而不需要改动游戏逻辑代码。4.2 智能相机控制器Three.js自带的OrbitControls适合查看模型但不适合用于角色控制。一个开放世界框架需要一个更强大的相机控制器。我实现了一个ThirdPersonCameraController它包含几个核心功能弹簧延迟跟随相机不是死死贴在角色身后而是像用一根弹簧拉着一样有一个平滑的延迟跟随效果。这能避免急停急转时镜头剧烈晃动提升舒适感。实现上我们使用线性插值Lerp或更复杂的阻尼弹簧算法来计算相机每一帧的目标位置。// 简化的弹簧跟随逻辑 const currentCameraPos camera.position; const targetPos player.position.clone().add(new THREE.Vector3(0, 5, -10)); // 假设目标在玩家后方上方 const smoothTime 0.1; // 平滑时间系数 // 使用 THREE.MathUtils.lerp 或自定义的阻尼函数 camera.position.lerp(targetPos, smoothTime);碰撞检测与规避当相机和玩家之间出现墙壁或树木时不能让它穿模。解决方案是从玩家头部向相机目标位置发射一条射线Raycast。如果检测到碰撞就将相机位置拉近到碰撞点前方一点的位置。同时当障碍物移开后相机再平滑地回到原位。鼠标/触摸控制视角将鼠标移动或单指拖拽的位移转换为相机围绕玩家的旋转角度偏航Yaw和俯仰角度Pitch并设置合理的上下限防止镜头穿到地面以下或天上。4.3 动态场景加载与LOD对于“开放世界”即使基础框架不直接实现大地形流式加载也需要为这种可能性设计接口。一个核心概念是“场景区块”Chunk管理。框架中的SceneManager负责管理一个主场景THREE.Scene但它也维护着一个以空间坐标如[chunkX, chunkZ]为键的区块地图。每个区块可以包含一组实体并可以独立加载和卸载。class SceneManager { constructor() { this.mainScene new THREE.Scene(); this.loadedChunks new Map(); // Map‘x,z’, { entities: Entity[], meshGroup: THREE.Group } this.playerChunkCoord null; } update(playerPosition) { // 1. 根据玩家位置计算当前所在区块坐标 const newChunkCoord this._calculateChunkCoord(playerPosition); // 2. 如果区块发生变化触发加载/卸载逻辑 if (!this._compareCoords(newChunkCoord, this.playerChunkCoord)) { this._onPlayerChunkChanged(newChunkCoord, this.playerChunkCoord); this.playerChunkCoord newChunkCoord; } // 3. 更新当前已加载区块内可能需要更新的内容如LOD this._updateActiveChunks(); } _onPlayerChunkChanged(newCoord, oldCoord) { // 计算需要加载的新区块和需要卸载的旧区块 const toLoad this._getChunksInRadius(newCoord, RENDER_DISTANCE); const toUnload this._getChunksInRadius(oldCoord, RENDER_DISTANCE); // 异步加载新区块的资源并实例化实体 this._loadChunksAsync(toLoad); // 卸载旧区块销毁实体释放资源 this._unloadChunks(toUnload); } }配合区块管理可以很容易地集成细节层次LOD系统。对于远处的物体使用面数少的简化模型当玩家靠近时再切换为高精度模型。Three.js本身提供了THREE.LOD对象框架可以将其封装到MeshComponent中根据实体与相机的距离自动管理不同层级的模型切换。5. 性能优化与调试实践一个框架如果性能低下或难以调试就失去了实用价值。以下是框架中内置的几个关键优化和调试手段。5.1 物理引擎的性能陷阱与规避Cannon.js是一个纯JavaScript实现的物理引擎在复杂场景下可能成为性能瓶颈。控制刚体数量这是最重要的原则。尽可能减少动态刚体的数量。能用少量复杂形状如CANNON.Trimesh或CANNON.ConvexPolyhedron就不要用大量简单形状堆砌。合理设置步长物理世界的更新频率world.step(fixedTimeStep)通常独立于渲染帧率。fixedTimeStep一般设为1/60约0.0167秒。即使游戏帧率掉到30帧物理世界也以60Hz的固定频率模拟这能保证物理行为的稳定性和可重现性。但步长越小计算越频繁。需要在精度和性能间权衡。使用“睡眠”机制静止的物体如落在地上不再滚动的球应该让其“睡眠”。Cannon.js的刚体有allowSleep和sleepSpeedLimit属性。当刚体速度低于某个阈值一段时间后引擎会将其置为睡眠状态不再参与每帧的碰撞和运动计算直到被其他物体碰撞唤醒。框架应在RigidBodyComponent中默认开启此选项。5.2 渲染侧的优化策略合并绘制调用对于大量静态且材质相同的小物体如草地、碎石使用THREE.InstancedMesh进行实例化渲染。它能将成千上万个物体的绘制合并为一次GPU调用性能提升是数量级的。框架可以提供InstancedMeshComponent来简化这一过程。视锥体剔除Three.js的渲染器默认会进行视锥体剔除Frustum Culling不渲染相机视野外的物体。但我们的SceneManager在区块层面进行的加载/卸载是更粗粒度、更有效的剔除避免了不必要的内存占用和CPU处理。着色器与材质优化避免在每一帧动态创建或编译着色器。尽量复用材质。对于需要大量重复但参数略有不同的物体如不同颜色的箱子考虑使用顶点颜色或纹理图集而不是为每个箱子创建独立的材质实例。5.3 强大的调试可视化调试物理世界是噩梦因为你看不到碰撞体。框架必须集成一个可开关的调试渲染器。物理调试渲染遍历物理世界中的所有刚体根据其形状Box, Sphere, Cylinder等用Three.js的线框几何体THREE.LineSegments在对应的位置、旋转和尺寸上绘制出来。这能让你清晰地看到每一个碰撞体的边界。射线检测可视化当进行射线检测如拾取物体、相机碰撞检测时可以将射线的路径和命中点用一条彩色的线实时绘制出来。性能面板在屏幕一角创建一个简单的THREE.Sprite或使用CSS叠加层显示当前帧率FPS、实体数量、三角形数量、物理步进时间等关键指标。这能帮助你快速定位性能热点。class DebugRenderer { constructor(physicsWorld, scene) { this.physicsWorld physicsWorld; this.debugScene new THREE.Scene(); this.meshes new Map(); // 存储刚体ID到线框网格的映射 } update() { // 清除上一帧的调试网格 // ... // 遍历所有刚体创建或更新对应的线框网格 this.physicsWorld.bodies.forEach(body { if (!body.shapes.length) return; const debugMesh this._createDebugMeshForBody(body); this.debugScene.add(debugMesh); }); // 最后用另一个渲染通道或叠加渲染器将debugScene画出来 } }将这些调试工具集成到框架中并通过一个全局配置变量如window.DEBUG true来控制开关能极大提升开发效率。6. 从框架到项目构建你的第一个世界理论说了这么多我们来看看如何用这个框架快速启动一个项目。6.1 项目初始化与配置假设你已经通过npm或直接引入的方式获得了框架源码。项目结构可能如下your-project/ ├── src/ │ ├── main.js # 应用入口 │ ├── systems/ # 自定义系统可选 │ ├── components/ # 自定义组件可选 │ └── entities/ # 自定义实体定义可选 ├── assets/ # 模型、纹理等资源 └── public/ └── index.html在main.js中你需要进行标准化的初始化import { World } from ‘./framework/core/World’; import { RenderSystem } from ‘./framework/systems/RenderSystem’; import { PhysicsSystem } from ‘./framework/systems/PhysicsSystem’; import { InputManager } from ‘./framework/core/InputManager’; import { ThirdPersonCameraController } from ‘./framework/controllers/ThirdPersonCameraController’; // 1. 初始化三大核心 const world new World(); const renderer new THREE.WebGLRenderer({ antialias: true }); const inputManager new InputManager(document.body); // 2. 创建并添加核心系统 world.registerSystem(new RenderSystem(renderer, document.getElementById(‘app’))); world.registerSystem(new PhysicsSystem()); // ... 注册其他系统如PhysicsSyncSystem, InputSystem等 // 3. 设置相机和控制器 const camera new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000); const cameraController new ThirdPersonCameraController(camera); world.registerSystem(cameraController); // 相机控制器本身也可以作为一个系统 // 4. 创建基础场景地面、灯光、天空盒 const groundEntity createGroundEntity(); // 一个辅助函数创建带物理的静态地面 world.addEntity(groundEntity); // ... 创建灯光、天空盒等环境实体 // 5. 创建玩家实体 const playerEntity createPlayerEntity(inputManager, cameraController); world.addEntity(playerEntity); // 6. 启动游戏循环 function gameLoop(timestamp) { const deltaTime (timestamp - lastTime) / 1000; // 转换为秒 lastTime timestamp; // 更新输入状态 inputManager.update(); // 更新世界这会驱动所有已注册系统的update方法 world.update(deltaTime); // 渲染系统会在其update中执行渲染 requestAnimationFrame(gameLoop); } let lastTime 0; requestAnimationFrame(gameLoop);6.2 扩展框架创建一个自定义“拾取”组件框架的威力在于易于扩展。假设你想实现一个“拾取物品”的功能。创建新组件在src/components/下创建PickableComponent.js。它可能包含属性如itemType物品类型、pickupRadius拾取半径等。创建新系统在src/systems/下创建PickupSystem.js。这个系统会在每帧更新中检查所有带有PickableComponent的实体与玩家实体之间的距离。如果距离小于拾取半径则发布一个PICKUP_AVAILABLE事件。响应事件在玩家控制逻辑中或另一个专门的PlayerInteractionSystem中订阅PICKUP_AVAILABLE事件。当玩家按下“拾取”键由InputManager映射时检查最近的可用拾取物然后发布ITEM_PICKED事件。处理拾取一个InventorySystem可以订阅ITEM_PICKED事件更新玩家的背包数据并调用world.destroyEntity来销毁或隐藏被拾取的实体。通过这种方式一个复杂的交互功能被清晰地分解为组件、系统和事件完美融入框架的架构之中。6.3 打包与部署考量对于正式项目你需要考虑打包。使用Webpack或Vite等工具将你的代码和框架代码打包优化。注意Tree Shaking确保你的打包工具能剔除框架中未使用的代码。这要求框架源码必须采用ES6模块化导出。资源加载对于模型和纹理使用Three.js的GLTFLoader、TextureLoader等并考虑使用加载管理器LoadingManager来显示进度条。生产环境优化关闭调试模式压缩JavaScript代码可能的话将物理引擎的精度从高精度模式调整为平衡模式。这个框架的源码提供了一个坚实的起点但它不是终点。它定义了一套清晰的规则和模式让你在构建自己的三维世界时能专注于创造性的工作而不是在底层技术的泥潭中挣扎。当你熟悉了实体、组件、系统和事件的协作方式后你会发现添加新的特性、调试问题、甚至优化性能都变得有迹可循。这正是设计一个良好框架的意义所在它不限制你的想象力而是为你实现想象力提供了最可靠的工具。本文还有配套的精品资源点击获取
