阶段小结

Nobody has claimed this yet.

▐▛███▜▌ Claude Code v2.1.62
▝▜█████▛▘ qwen3.5-plus · API Usage Billing
▘▘ ▝▝ ~/jayli/mc-lite

/model to try Opus 4.6

❯ /clear
⎿  (no content)

❯ 总结一下目前程序的架构设计，请至少涵盖地形（Terrain）、地图（Map）、实体(
entities)、操作者（actor）、特效(effects)、渲染分区（Chunk），性能手段（I
nstanecedMesh、background consolidation、face culling
等），渲染管线（多个
worker）、持久化（Persistence）、创作台（Playground）、全局配置（Game.js
）、操作界面（UI）、工具箱（utils）、方块和材质（blocks）、其中实体（enti
ties）包括了JSON加载的实体和程序渲染的实体，此外还有导入的外部实体比如
ModGunMan 之类...，我暂时想到这么多，还有哪些设计上的抽象和要点，请你一并
帮我总结下来，形成一个完整的设计架构。并给出这个设计未来可改进的地方。

⏺ 我来详细分析并总结 MC Lite 的完整架构设计。让我先阅读关键文件来获取准确信息。

⏺ Read 5 files (ctrl+o to expand)

⏺ 让我继续阅读更多关键文件：

⏺ Read 5 files (ctrl+o to expand)

⏺ 让我继续阅读更多关键文件：

⏺ Read 4 files (ctrl+o to expand)

⏺ 现在我已经阅读了所有关键文件，让我为你整理一份完整的架构设计总结：

---
MC Lite 架构设计总览

一、整体架构分层

┌─────────────────────────────────────────────────────────────┐
│ 表现层 (Presentation) │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ UIManager │ │ Engine.js │ │ HUD/Inventory│ │
│ │ (UI 系统) │ │ (Three.js 渲染)│ │ (界面组件) │ │
│ └─────────────┘ └──────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 业务逻辑层 (Game Logic) │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Game.js │ │ World.js │ │ EnemyManager │ │
│ │ (游戏主循环) │ │ (世界管理) │ │ (敌人管理) │ │
│ └─────────────┘ └──────────────┘ └──────────────┘ │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Player.js │ │ Chunk.js │ │ EntityManager│ │
│ │ (玩家控制) │ │ (区块渲染) │ │ (实体系统) │ │
│ └─────────────┘ └──────────────┘ └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ 数据层 (Data) │
│ ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │Persistence │ │ BlockData.js │ │ Skybox/Models│ │
│ │ (IndexedDB) │ │ (方块配置) │ │ (外部资源) │ │
│ └─────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────┘

---
二、核心系统详解

1. 地形系统 (Terrain)

文件: src/world/TerrainGen.js, src/workers/WorldWorker.js

- 高度生成: 使用叠加噪声 (Perlin/Simplex) 生成地形高度图
- 基础噪声：noise(x, z, 0.08) + noise(x, z, 0.02) * 3
- 生物群系判定基于温度和湿度噪声
- 生物群系: PLAINS, FOREST, DESERT, SWAMP, AZALEA, OCEAN, SNOW_LAND,
FROZEN_MOUNTAIN
- 结构生成: 使用确定性随机 (seededRandom) 确保相同位置生成相同结构

2. 地图系统 (Map)

文件: src/workers/maps/Pyramid.js, SnowLand.js, FrozenMountain.js

- 自定义地图生成器: 每个地图有独立的高度图修饰逻辑和结构生成规则
- 过渡区域处理: 使用 transitionFactor 实现平滑过渡
- 金字塔: 完整内部房间结构，宝箱生成
- 雪地: 积雪覆盖逻辑，带雪白桦树生成
- 冰封山峰: 特殊地形修饰，雪云生成

3. 实体系统 (Entities)

文件: src/world/entity-system/EntityManager.js

实体分类架构:

┌─────────────┬─────────────────────────────────────────┬─────────────────┐
│ 分类 │ 实体类型 │ 生成方式 │
├─────────────┼─────────────────────────────────────────┼─────────────────┤
│ │ tree_default, tree_big, tree_birch, │ CodeEntity / │
│ trees │ tree_realistic, tree_azalea, │ JsonEntity │
│ │ tree_swamp, tree_sky │ │
├─────────────┼─────────────────────────────────────────┼─────────────────┤
│ structures │ house, ugly_house, tank, ship, rover │ CodeEntity / │
│ │ │ JsonEntity │
├─────────────┼─────────────────────────────────────────┼─────────────────┤
│ decorations │ cloud, cloud_cluster, island, │ CodeEntity │
│ │ short_grass, flower, lilypad, cactus │ │
├─────────────┼─────────────────────────────────────────┼─────────────────┤
│ mods │ gun_man (ModGunMan) │ CodeEntity │
│ │ │ (外部 GLB 模型) │
└─────────────┴─────────────────────────────────────────┴─────────────────┘

实体生成框架:

- CodeEntity: 程序化生成实体（树木、云朵等）
- JsonEntity: 从 JSON 数据加载（房屋、坦克等）
- StructureLoader: 统一加载 JSON 结构数据
- 跨 Chunk 渲染: crossChunkDist 参数控制渲染距离

4. 操作者系统 (Actors)

文件: src/actors/player/Player.js, src/actors/enemy/

- 玩家: 物理模拟 (Physics.js)、背包系统 (Slots.js)、输入处理
- 丧尸: AI 决策在 Worker 中运行，主线程处理物理和渲染
- 敌人管理器: 使用实例化渲染 (ZombieInstancedRenderer)，支持最多 200 个实例

5. 特效系统 (Effects)

文件: src/world/effects/ParticleSystem.js

- 粒子系统:
- 挖掘粒子
- 爆炸粒子 (2D Billboard + 3D 球体扩张)
- 徒手破坏粒子
- 爆炸球体池: 对象池模式，最大 15 个同时爆炸

6. 渲染分区 (Chunk)

文件: src/world/Chunk.js

- 16x16 标准区块: 每区块独立管理
- 动态加载/卸载: 渲染距离 3 区块 (玩家周围 3x3)
- InstancedMesh: 同类型方块合并渲染
- 后台合并系统 (Background Consolidation):
- DIRTY_THRESHOLD = 50: 触发阈值
- CONSOLIDATION_DELAY = 1000ms: 防抖延迟
- 动态方块先使用单体 Mesh，达到阈值后合并到 InstancedMesh

7. 性能优化手段

InstancedMesh

- 每个方块类型一个 InstancedMesh
- 单次 Draw Call 渲染多个相同方块
- 使用 instanceMatrix 存储位置/旋转/缩放

Face Culling (隐藏面剔除)

文件: src/core/FaceCullingSystem.js, src/workers/FaceCullingWorker.js
- 6-bit 面掩码：每位表示一个面是否可见
- AO 计算：每顶点 2-bit，共 24 顶点 (6 面×4 顶点)
- Worker 异步处理

Background Consolidation

- 动态方块先使用独立 Mesh
- 延迟合并到 InstancedMesh
- 减少频繁重建 InstanceMatrix 的开销

LOD 策略

- 水面波浪：远距离减少计算
- 光源更新：玩家移动超过 5 格才更新

8. 渲染管线 (Workers)

┌─────────────────┬──────────────────────┬───────────────────────────────┐
│ Worker │ 职责 │ 文件 │
├─────────────────┼──────────────────────┼───────────────────────────────┤
│ WorldWorker │ 地形生成、区块创建、 │ src/workers/WorldWorker.js │
│ │ AO 计算 │ │
├─────────────────┼──────────────────────┼───────────────────────────────┤
│ FaceCullingWork │ 隐藏面剔除计算 │ src/workers/FaceCullingWorker │
│ er │ │ .js │
├─────────────────┼──────────────────────┼───────────────────────────────┤
│ EnemyWorker │ 丧尸 AI 决策 │ src/workers/EnemyWorker.js │
├─────────────────┼──────────────────────┼───────────────────────────────┤
│ ExplosionWorker │ 爆炸效果计算 │ src/workers/ExplosionWorker.j │
│ │ │ s │
├─────────────────┼──────────────────────┼───────────────────────────────┤
│ PersistenceWork │ IndexedDB 操作 │ src/workers/PersistenceWorker │
│ er │ │ .js │
└─────────────────┴──────────────────────┴───────────────────────────────┘

9. 持久化系统 (Persistence)

文件: src/services/PersistenceService.js

- 增量存储: 只存储修改过的方块 (delta)
- IndexedDB: 浏览器本地存储
- Worker 异步: 不阻塞主线程
- 快照模式: snapshot = { blocks: {...}, entities: {...} }
- 存档/读档: saveToDisk() / applySaveData()

10. 创造台 (Playground)

文件: src/services/PlaygroundService.js

- 40x40 平台: 在玩家附近自动生成
- 高度自适应: 自动搜索安全高度
- 模型导出: 导出为 JSON 格式，支持相对坐标和方向

11. 全局配置 (Game.js)

核心配置项:
{
canGunsDestroyBlocks: false, // 枪械破坏开关
maxActiveZombies: 20, // 最大丧尸数
showDebugInfo: false, // 调试模式
perfStats: {...} // 性能统计
}

12. 操作界面 (UI)

文件: src/ui/UIManager.js, HUD.js, Inventory.js

- HUD: FPS 显示、快捷栏、消息提示
- Inventory: 背包管理、物品选择
- Settings Modal: 分辨率、游戏设置
- 性能监控: Jank 计数、长任务追踪

13. 工具箱 (Utils)

┌─────────────────────┬───────────────────────────────┐
│ 工具 │ 职责 │
├─────────────────────┼───────────────────────────────┤
│ MathUtils.js │ 噪声生成、世界配置常量 │
├─────────────────────┼───────────────────────────────┤
│ OrientationUtils.js │ 方块方向转换、序列化/反序列化 │
├─────────────────────┼───────────────────────────────┤
│ ItemIconUtils.js │ 物品图标生成 │
├─────────────────────┼───────────────────────────────┤
│ FaceCullingUtils.js │ 面剔除辅助函数 │
├─────────────────────┼───────────────────────────────┤
│ BufferGeometryUtils │ 几何体合并 │
└─────────────────────┴───────────────────────────────┘

14. 方块和材质 (Blocks & Materials)

文件: src/constants/BlockData.js, src/core/MaterialManager.js

方块属性系统:

{
isSolid: true, // 碰撞检测
isTransparent: false, // 面剔除规则
isRendered: true, // 是否需要渲染
isAOEnabled: false, // 环境光遮蔽
isShadowEnabled: true, // 阴影投射
geometryType: 'box' // 几何体类型
}

特殊几何体:

- geoFlower: 十字交叉平面
- geoCactus: 多分支仙人掌
- geoHandrail: L 形栏杆
- geoPlanksStep: 台阶形状

---
三、设计亮点与抽象

1. 数据驱动实体系统

- 统一的 EntityDefinition 基类
- 支持程序化生成和 JSON 加载
- 生物群系感知生成决策

2. 跨 Chunk 实体渲染

- 结构中心点记录 (structureCenters)
- belongsToStructure() 判断方块归属
- 支持 UglyHouse 等 40x40 大型结构

3. 确定性随机生成

- seededRandom(wx, wz, seed) 确保一致性
- 支持存档后结构不变

4. 对象池模式

- 爆炸球体池
- InstancedMesh 实例池

5. 依赖注入设计

- globalThis._persistenceService 等覆盖点
- 便于测试环境模拟

---
四、未来可改进方向

短期优化

1. 纹理 Atlasing: 合并小纹理减少绑定次数
2. Frustum Culling: 视锥体剔除，只渲染可见区块
3. 实体池: 丧尸/物品对象池减少 GC

中期重构

1. ECS 架构: 引入真正的实体 - 组件 - 系统模式
2. GPU Instancing 升级: 使用 Compute Shader 处理矩阵更新
3. 流式加载: 后台渐进式区块加载

长期扩展

1. 多人联机: WebSocket 同步 + 服务器权威架构
2. Mod 系统: Lua/JS 脚本支持
3. 程序化动画: 树木摇摆、水面波浪 GPU 化

---
这份架构总结涵盖了 MC Lite 的核心设计要点。如果你有特定模块想深入了解，或者需
要针对某个改进方向制定具体计划，请告诉我！

✻ Crunched for 1m 13s

Start by verifying the architecture claims against the named entry points, including src/world/Chunk.js, src/world/entity-system/EntityManager.js, src/workers/WorldWorker.js, src/core/FaceCullingSystem.js, and src/services/PersistenceService.js. Done means producing a reviewed, maintainable architecture document with accurate module boundaries and clearly scoped future improvements.

Written by the indexing model from the issue text.