胎渊 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 引入。

技术栈

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

项目结构（精简版）

.
├── App.tsx
├── Renderer3D.tsx
├── game.ts
├── dungeon.ts
├── assets.ts
├── sprites.ts
├── constants.ts
├── types.ts
├── utils.ts
├── config/
│   ├── characters.ts
│   ├── enemies.ts
│   ├── items.ts
│   ├── obstacles.ts
│   └── themes.ts
├── docs/
│   ├── FRONTEND_OVERVIEW.md
│   ├── ONLINE_PROTOCOL.md
│   └── backend/server.ts
├── fonts/
│   ├── en.ttf
│   └── zh.ttf
├── index.tsx
├── index.html
├── vite.config.ts
└── tsconfig.json

架构与数据流

• App.tsx 负责 UI（菜单/设置/图鉴/ HUD）+ 输入采集 + 游戏主循环节拍。
• GameEngine（game.ts）是无头逻辑引擎：房间生成、敌人 AI、弹道、掉落、碰撞、进房间与层数推进等。
• Renderer3D.tsx 用 @react-three/fiber 渲染场景：房间、门、角色/敌人/道具的体素网格、粒子/爆炸特效等。
• AssetLoader（assets.ts）用 sprites.ts 的 16x16 像素矩阵生成 Canvas 纹理与 THREE 纹理，供 UI 预览与 3D 渲染复用。
• constants.ts 提供全局常量、颜色/调色板与多语言文案。

简化流程：

InputManager -> GameLoop (App.tsx) -> GameEngine.update()
                         |                     |
                         |                     -> UI stats 回传
                         v
                   Renderer3D.tsx 读取引擎状态渲染

核心模块拆解

• App.tsx

  • UI 组件（血量、属性条、虚拟摇杆、设置、图鉴、联机菜单等）。
  • 驱动游戏主循环、输入融合（键盘 + 触摸摇杆）。
  • 管理本地/联机状态、WebSocket 消息、大厅与房间流程。

• game.ts

  • 引擎核心：角色/敌人/道具/投射物的实体系统。
  • 房间进入/离开、门控制、碰撞、AI 行为、掉落、统计等。
  • 支持单机与联机差异逻辑（如死亡判定、掉落归属等）。

• Renderer3D.tsx

  • 将精灵矩阵转换为体素 instanced mesh。
  • 绘制房间地板/墙体/门/机关/背景，以及粒子、爆炸、弹道轨迹。
  • 负责不同主题的材质与光照变化。

• dungeon.ts

  • 使用 BFS/随机扩展生成房间图。
  • 处理特殊房间：START / ITEM / BOSS / CHEST / DEVIL / HIDDEN。
  • 生成可通达的地形布局与门洞。

• assets.ts

  • 生成像素纹理（Canvas + THREE.CanvasTexture）。
  • 处理主题墙/地/岩石与角色/敌人/道具的图块。

• sprites.ts

  • 16x16 像素矩阵定义（墙体、地板、角色、敌人、道具等）。
  • Sigil 系列精灵使用伪随机图案生成器。

• config/*

  • characters.ts：角色与基础属性。
  • enemies.ts：普通敌人 + Boss 定义。
  • items.ts：道具/掉落配置与属性修正。
  • obstacles.ts：障碍物与破坏规则。
  • themes.ts：房间主题配色与材质。

• docs/*

  • FRONTEND_OVERVIEW.md：前端结构与玩法摘要。
  • ONLINE_PROTOCOL.md：联机协议设计（WebSocket）。
  • backend/server.ts：示例 WebSocket 服务端（大厅/输入转发/心跳）。

玩法与规则摘要

• 地牢按层生成，房间类型包含普通/物品/宝箱/Boss/恶魔/隐藏。
• 敌人配置随楼层解锁，Boss 有多个变体与特殊弹幕模式。
• 物品提供属性加成/弹道形态/连锁/爆炸/追踪等效果。
• 炸弹可破坏障碍并开启隐藏房间入口。
• 小地图会隐藏未探索或隐藏房间。

扩展建议（基于现有结构）

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