一个基于 TypeScript、Three.js 和 Vite 开发的浏览器版 Minecraft。

在线演示: 在浏览器中打开

注意: 本项目全部由 Kimi K2.5 AI 模型通过 Vibe Coding 迭代开发和优化完成。

• 第一人称探索: 鼠标视角控制 + WASD 移动
• 方块交互: 左键挖掘方块，右键放置方块
• 9格快捷栏: 3D 方块图标，支持数字键 1-9 或鼠标滚轮切换
• 物理系统: 重力、跳跃、AABB 碰撞检测
• 飞行模式: 双击空格切换飞行状态
• 疾跑模式: 双击 W 键疾跑（1.5倍速度）

• 程序化地形生成: 使用 Simplex Noise 算法
• 生物群系支持: 草地、泥土、石头、沙子、木头、树叶
• 树木生成: 随机位置生成
• 多世界支持: 创建和管理多个世界

• 区块渲染: 每个区块 16x16x16 个方块
• 面剔除: 只渲染暴露在空气中的方块面
• 自定义雾效着色器: 基于距离渐变的雾效
• 区块淡入动画: 平滑加载效果
• 纹理图集: 所有方块纹理集成在单张图片中

• IndexedDB 持久化存储: 世界数据保存在浏览器本地
• 自动保存:
  • 玩家位置每 30 秒保存一次
  • 修改后的区块在 5 秒后自动保存
  • 退出游戏时立即保存所有数据
• 多世界管理: 列表、加载、删除世界

• Minecraft 风格像素风 UI: 自定义字体
• 主菜单: 单人游戏、选项、退出游戏
• 世界列表: 创建、加载、编辑、删除世界
• 暂停菜单: 回到游戏、选项、保存并回到标题画面
• 设置面板:
  • 渲染距离（2-16 个区块）
  • 缓存距离（>= 渲染距离）
  • 视野角度（30-110°）
  • 鼠标灵敏度
  • 主音量
  • 玩家速度
• 调试信息显示: FPS、位置、偏航/俯仰角、目标方块

• 背景音乐: 循环播放系统
• 音量控制: 与设置面板集成
• 浏览器自动播放策略兼容: 首次用户交互后启动

• 语言: TypeScript 5.3
• 构建工具: Vite 5.0
• 包管理器: pnpm
• 3D 引擎: Three.js 0.160
• 地形生成: Simplex Noise
• 存储: IndexedDB（通过自定义 SaveManager）
• 代码质量: ESLint + Prettier

src/
├── core/           # 核心引擎
│   ├── Game.ts     # 游戏主控制器
│   ├── Renderer.ts # Three.js 封装
│   ├── World.ts    # 世界状态与雾效管理
│   └── Camera.ts   # 相机工具类
├── world/          # 世界系统
│   ├── Chunk.ts           # 16x16x16 方块存储
│   ├── ChunkManager.ts    # 区块生命周期管理
│   ├── BlockType.ts       # 方块类型定义
│   ├── MeshBuilder.ts     # 带自定义着色器的几何体生成
│   └── TerrainGenerator.ts # 程序化地形生成
├── player/         # 玩家系统
│   ├── Player.ts   # 玩家实体与移动
│   └── Physics.ts  # 方块交互射线检测
├── input/          # 输入处理
│   └── InputHandler.ts # 键盘、鼠标、指针锁定
├── ui/             # 用户界面
│   ├── UIManager.ts           # 菜单系统与 HUD
│   └── styles/minecraft-ui.css # 像素风 UI 样式
├── save/           # 持久化存储
│   └── SaveManager.ts # IndexedDB 操作
└── utils/          # 工具类
    ├── Constants.ts        # 游戏常量
    ├── Settings.ts         # 设置管理（localStorage）
    ├── AudioManager.ts     # 背景音乐系统
    ├── TextureLoader.ts    # 纹理图集加载
    ├── GeometryCache.ts    # 共享几何体实例
    └── BlockIconRenderer.ts # 3D 图标生成

• Node.js 18+
• pnpm

# 克隆仓库
git clone https://github.com/wzh656/MinecraftWebNew
cd MinecraftWebNew

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

# 在浏览器中打开 http://localhost:3000

pnpm build

构建输出将在 dist/ 目录中。

游戏设置保存在 localStorage 中，包括：

• 渲染距离: 渲染的区块数量（2-16）
• 缓存距离: 内存中保留的区块数量（>= 渲染距离）
• 视野: 视野角度（30-110°）
• 鼠标灵敏度: 相机旋转速度
• 音量: 背景音乐主音量（0-100%）
• 玩家速度: 基础移动速度（疾跑和飞行按比例计算）

设置可在游戏内通过选项菜单修改。

• 每个区块为 16x16x16 个方块，使用 Uint8Array 存储（4096 字节）
• 可见区块只渲染暴露在空气中的面
• 三级区块管理：
  • 渲染区块: 在渲染距离内，完全可见
  • 缓存区块: 在缓存距离内，保留数据但不渲染
  • 未加载区块: 超出缓存距离，从内存中移除

1. 自定义着色器材质，带距离雾效
2. 区块透明度动画（约 200ms 淡入）
3. 方块变化时动态更新网格
4. 跨区块边缘更新，实现无缝面

• AABB（轴对齐边界框）碰撞检测
• 三轴分离，实现沿墙壁平滑滑动
• 基于射线检测的方块交互（DDA 算法）
• 边缘情况处理（相机在方块内时挖掘）

• 区块: 键名为 ${worldName}:${chunkX},${chunkZ}
• 元数据: 世界创建时间、最后游玩时间、玩家位置/旋转
• 数据库: MinecraftWebDB，包含 chunks 和 metadata 对象存储

本项目通过迭代式 AI 辅助开发完成：

1. 阶段 1-4: 核心引擎、区块系统、玩家物理、基础交互
2. 阶段 5-7: 物品栏 UI、存档系统、暂停菜单、Bug 修复
3. 阶段 8: 地形生成、飞行/疾跑、区块缓存
4. 阶段 9: 自定义雾效着色器、区块淡入效果
5. 阶段 11: 完整的 Minecraft 风格像素风 UI 重构

解决的关键技术挑战：

• 方块面剔除和网格优化
• 跨区块边界更新
• 射线检测边缘情况（方块内挖掘、对角面）
• 指针锁定状态与菜单系统管理
• IndexedDB 异步操作与 UI 同步

计划中的未来增强功能：

• Web Worker 地形生成（消除主线程卡顿）
• 昼夜循环与动态光照
• 更多方块类型和合成系统
• 基于 WebRTC 的多人联机支持
• 移动端触摸控制

用 ❤️ 由 AI 构建，为玩家服务