胎渊 3D（Birth 3D）

一款俯视角 Rogue-like 射击游戏：用像素精灵驱动 Three.js 体素风 3D 渲染，React 负责 UI 与菜单，游戏逻辑为可独立运行的“无头引擎”。支持本地单机与（当前为实验/原型态的）联机大厅与输入同步。

运行与构建

• 安装依赖：npm install
• 开发启动：npm run dev
• 构建：npm run build
• 预览：npm run preview

说明：

• vite.config.ts 会把 GEMINI_API_KEY 注入为 process.env.*，目前代码中未见实用入口；若不需要可忽略。
• 字体位于 fonts/，index.html 中通过 @font-face 引入。
• 3D 模型：位于 public/assets/models/，通过 GLTF/GLB 格式加载。

技术栈

• React + Vite
• Three.js / @react-three/fiber / @react-three/drei
• TypeScript
• Tailwind（CDN 形式，用于 UI）

项目结构（精简版）

.
├── App.tsx             # UI 入口与游戏循环驱动
├── Renderer3D.tsx      # Three.js 渲染器 (Voxel + GLB 模型)
├── game.ts             # 无头游戏引擎 (物理/AI/状态)
├── dungeon.ts          # 地牢生成算法 (BFS)
├── assets.ts           # 2D 资源加载与纹理生成
├── sprites.ts          # 16x16 像素矩阵定义
├── config/             # 游戏配置 (敌人/道具/角色)
│   ├── enemies.ts      # 敌人数据与 3D 模型绑定
│   └── ...
├── public/
│   └── assets/models/  # GLB 3D 模型文件
└── ...

架构与数据流

• App.tsx 负责 UI（菜单/设置/图鉴/ HUD）+ 输入采集 + 游戏主循环节拍。
• GameEngine（game.ts）是无头逻辑引擎：
  • 实体管理：玩家、敌人、子弹、掉落物。
  • 物理系统：简单的 AABB/Circle 碰撞检测（包含子弹碰撞与身体碰撞伤害）。
  • AI 系统：状态机驱动（Idle/Chase/Attack/Shooter等）。
• Renderer3D.tsx 用 @react-three/fiber 渲染场景：
  • Voxel 渲染：将 sprites.ts 定义的像素矩阵转换为 Instanced Mesh。
  • GLB 模型渲染：通过 AnimatedModel 组件加载骨骼动画模型。
  • 动画系统：自动映射 GLB 动画片段（如 Running_A, 1H_Melee_Attack_Chop）到游戏状态（Run, Attack）。

核心系统说明

1. 3D 动画系统

• 模型文件存放在 public/assets/models/。
• 在 config/enemies.ts 中通过 model 字段指定文件名。
• Renderer3D 会根据实体的 velocity 和 aiState 自动切换动画：
  • 移动 -> Run / Running_A
  • 攻击 (aiState=ATTACK) -> Attack / 1H_Melee_Attack_... / Spellcast_Shoot
  • 死亡 -> Death / Death_A

2. 碰撞机制

• 子弹碰撞：子弹 (PROJECTILE) 击中实体时造成伤害并消失。
• 身体碰撞：当玩家与敌人身体重叠时，玩家会受到接触伤害并被击退。

扩展建议

• 新增角色：在 config/characters.ts 增加配置并补充 sprites.ts 精灵。
• 新增道具或敌人：更新 config/items.ts / config/enemies.ts 并补充 sprite 或颜色。
• 新增主题：在 config/themes.ts 新增配色与材质组合。
• 联机完善：按 docs/ONLINE_PROTOCOL.md 补齐服务端权威模拟或快照同步。