# 迷你世界

**Repository Path**: song-junyi/mini-world

## Basic Information

- **Project Name**: 迷你世界
- **Description**: Jy版迷你世界
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-17
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MiniCraft · 网页版我的世界

一个用纯 JavaScript + Three.js 实现的 Minecraft 风格体素沙盒游戏。
无需安装任何依赖，打开浏览器即可游玩。

## ✨ 功能特性

- **程序化世界生成**：基于 Perlin 噪声的地形（草原 / 丘陵 / 雪山 / 海洋 / 沙滩），自动生长树木
- **256 × 48 × 256 体素世界**：16×16 区块化管理，隐藏面剔除 + 雾效，流畅渲染
- **方块系统**：13 种方块（草方块、泥土、石头、沙子、原木、树叶、木板、水、基岩、圆石、玻璃、雪块）
- **挖矿与建造**：左键挖掘、右键放置，破坏方块获得掉落物（自动入快捷栏），基岩不可破坏
- **完整物理**：重力、跳跃、碰撞检测、游泳（水中减速/下沉/上浮）、飞行模式（F 键）
- **昼夜循环**：日出日落、天空渐变、日月运行、夜晚星空、云朵飘动
- **水下效果**：潜水时视野变蓝、雾变浓
- **第一人称操作**：鼠标视角（Pointer Lock）、WASD 移动、Shift 疾跑、空格跳跃
- **程序化贴图**：全部方块贴图由代码生成（16×16 像素风图集），无需任何图片资源
- **音效系统**：WebAudio 实时合成挖掘/放置音效（M 键静音）
- **挖掘粒子效果**：破坏方块时迸发彩色粒子
- **HUD 界面**：准星、快捷栏（带数量）、物品名、FPS/坐标/时间显示（F3 详细调试面板）
- **新世界**：按 R 键随机生成全新世界（不同种子）

## 🚀 如何运行

**方式一（推荐，离线可用）**：直接双击 `index.html` 在浏览器中打开。

**方式二**：本地静态服务器（可选）：

```bash
cd minecraft
python3 -m http.server 8000
# 浏览器访问 http://localhost:8000
```

> 需要支持 WebGL 的现代浏览器（Chrome / Edge / Firefox / Safari）。
> 首次打开若提示加载失败，请检查网络，或将 three.min.js（v0.149.0）下载到 `js/` 目录即可完全离线运行：
> `https://cdnjs.cloudflare.com/ajax/libs/three.js/0.149.0/three.min.js`

## 🎮 操作说明

| 按键 | 功能 |
| --- | --- |
| 鼠标 | 视角控制（macOS 触摸板兼容：锁定不可用时按住拖动转视角） |
| 鼠标左键 | 挖掘方块 |
| 鼠标右键 | 放置方块 |
| W / A / S / D | 前后左右移动 |
| 空格 | 跳跃（飞行时上升） |
| Shift | 疾跑（飞行时下降） |
| F | 切换飞行模式 |
| 1 ~ 9 / 滚轮 | 选择快捷栏方块 |
| F3 | 调试信息面板 |
| M | 静音开关 |
| R | 生成新世界（随机种子） |
| Esc | 暂停 / 释放鼠标 |

## 📁 项目结构

```
minecraft/
├── index.html          # 入口页面（UI + Three.js 加载器）
├── js/
│   ├── logic.js        # 核心逻辑：噪声/世界生成/方块/网格/物理/射线（纯 JS，可测试）
│   ├── main.js         # 渲染、输入、UI、音频、昼夜循环
│   └── three.min.js    # （可选）本地 Three.js，放这里可离线运行
├── tests/
│   └── test_logic.js   # Node.js 单元测试（验证核心逻辑）
└── README.md
```

## 🧪 运行测试

核心逻辑（世界生成、物理、碰撞、射线检测）与 Three.js 完全解耦，可在 Node 中验证：

```bash
cd minecraft
node tests/test_logic.js   # 163 项断言：确定性/地形/网格/射线/物理/性能
```

> 附加调试模式：在 URL 后加 `?autostart=1` 可直接进入游戏（跳过点击开始，
> 供无头浏览器自动化测试使用），游戏状态与画布像素会写入浏览器标题栏。

## 🏗️ 技术要点

- **世界生成**：3 层 Perlin 噪声（起伏 + 细节 + 山脊）合成高度图；整数哈希决定树木位置，保证确定性
- **网格构建**：逐区块遍历方块，仅生成暴露在空气/水中的面（隐藏面剔除），烘焙顶/侧/底明暗色
- **透明渲染**：水使用半透明材质（关闭深度写入 + polygonOffset 防 z-fighting），玻璃/树叶用 alphaTest 裁剪
- **碰撞**：按轴分离移动 + AABB 重叠检测，逐轴解析，避免斜向卡墙
- **交互**：DDA 体素射线步进算法，6 格交互距离，命中面法线用于决定放置位置
- **贴图**：程序化生成 16×16 像素风贴图（噪点抖动 + 结构特征），打包为 4×4 图集，最近邻采样保持像素风格
- **性能**：256 个区块按玩家位置懒加载（渲染距离 5 区块），方块修改只重建受影响区块

## 🚧 可扩展方向

- 生存模式（饥饿值 / 血量 / 合成系统 / 工具耐久）
- 洞穴与矿石（3D 噪声挖洞、铁矿/钻石矿）
- 世界存档（localStorage / IndexedDB 保存修改的方块）
- 红石电路、动物生物、昼夜生物生成
- 多人联机（WebSocket 同步区块）