# game

**Repository Path**: chjk/game

## Basic Information

- **Project Name**: game
- **Description**: 我的第一个游戏项目
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 远征 (YuanZheng) — 项目管理文档

## 项目概述

让玩家用零件拼装机器、载具和建筑来管理基地生存的模拟经营游戏。
DIY 拼装是核心差异化，物理模拟（温度/气体/液体/相变）是涌现玩法的来源。

## 技术栈

| 项 | 选择 | 版本 |
|----|------|------|
| 语言 | Java | 21 LTS |
| 构建 | Gradle | 8.4 |
| 引擎 | LibGDX | 1.13.1 |
| 架构 | OOP + 组合模式 | — |
| 数据 | JSON（Gson） | — |

## 设计文档

所有游戏设计文档在 `gdd/` 目录下，这是设计文档的副本。
原始文档在 `D:\claw\GDD\`。

### GDD 文件索引

| 文件 | 内容 |
|------|------|
| 00-index.md | 总索引 |
| 00-overview.md | 项目概述、核心差异化、设计支柱 |
| 01-core-gameplay.md | 核心循环、顾此失彼、失败设计 |
| 02-diy-system.md | 零件系统、分层网格、连接、验证、18种原型零件 |
| 02b-vehicle-system.md | 载具系统（壳体拼接、结构力学、全场景应用） |
| 03-duplicant-ai.md | 小人 AI（效用AI+行为树、需求、技能、社交） |
| 04-world-narrative.md | 世界观、机造一族、天工坊、机关岛、匠语术语 |
| 05-visual-ux.md | 视觉风格、信息分层、拼装界面 |
| 06-player-psychology.md | 认知偏差、功能固着、错误处理 |
| 07-levels-pacing.md | 玩家旅程、挑战展开、宝藏系统 |
| 08-tech-tree.md | 科技树（双线汇流、燃料科技线） |
| 09-gathering-crafting.md | 采集制造、天工台、废物循环 |
| 10-environment-sim.md | 环境模拟、相变、混合反应、昼夜季节 |
| 11-combat-defense.md | 蛮族、防御设施、环境武器 |
| 12-prototype-plan.md | 原型开发计划（三阶段） |

## 项目结构

```
game/
├── README.md                  ← You are here
├── DESIGN-DECISIONS.md        ← Design decision records (ADR)
├── MIGRATION-NOTES.md         ← Framework migration notes
├── gdd/                       ← Game design docs (reference)
├── spec/                      ← SPAC+TDD 规格文档 (实现契约)
│   ├── README.md              ←  方法论 + GDD↔SPEC 关系
│   ├── architecture.md        ←  架构总图 + 数据流
│   ├── 01-game.md             ←  Game.java SPAC+TDD
│   ├── 02-test-runner.md      ←  TestRunner SPAC+TDD
│   ├── 03-input-router.md     ←  InputRouter SPAC+TDD
│   └── 04-scenario-controller.md ← ScenarioController SPAC+TDD
├── core/src/main/java/game/
│   ├── Game.java              ← LibGDX 生命周期编排器 (998行, 重构后-35%)
│   ├── engine/
│   │   ├── TestRunner.java    ← 测试自动化 (463行)
│   │   ├── InputRouter.java   ← 输入路由+快捷键 (245行)
│   │   ├── ScenarioController.java ← 场景生命周期 (157行)
│   │   ├── renderer/          ← 渲染器
│   │   ├── input/             ← 网格输入处理
│   │   ├── simulation/        ← 模拟管理
│   │   └── ui/                ← UI面板
│   └── logic/                 ← 纯游戏逻辑 (无 LibGDX imports)
├── desktop/src/main/java/     ← Desktop launcher
├── assets/
│   ├── data/                  ← JSON data files (parts, recipes)
│   └── art/                   ← Art assets (msyh.ttc font, future textures)
├── tools/
│   ├── gamecodex-bridge.js    ← GameCodex 知识库查询桥接
│   └── node_modules/gamecodex← GameCodex 依赖 (957 docs, 29 engines)
├── build.gradle
├── core/build.gradle
├── desktop/build.gradle
└── settings.gradle
```

### 架构原则

**核心分离：** `game.logic` 包不 import 任何 LibGDX 类。
所有引擎相关的代码在 `game.engine` 包中。
如果将来换 Godot/Unity/其他框架，只需要重写 `engine/` 包。

**SPAC+TDD 规范：** 核心类使用 SPAC (Spec-Pattern-Architecture-Component) 
+ TDD (Test-Driven) 文档化。每份 SPEC 记录：单一职责、公开API、
设计模式、架构位置、依赖契约、测试用例矩阵。
详见 `spec/README.md`。

**重构记录 (2026-06-06):** Game.java 从 1530 行单体拆分为 4 文件
(998+463+245+157)，提取 TestRunner/InputRouter/ScenarioController。
详见 `spec/architecture.md`。

## 开发流程 — SPAC+TDD

> **SPAC** = Spec(规格) + Pattern(模式) + Architecture(架构) + Component(契约)  
> **TDD** = Test-Driven (测试驱动)  
> **核心规范**: `spec/convention.md`（所有开发/重构必须遵守）

### 流程

```
新任务
  ├─ 1. 创建 spec/YYYY-MM-DD_verb-object/     (任务 SPAC 目录)
  ├─ 2. 写 SPAC+TDD 草稿                      (每个变更模块一份)
  │      S: 做什么？API？契约？
  │      P: 用什么设计模式？为什么？
  │      A: 在架构哪里？和谁协作？
  │      C: 依赖什么？提供什么？
  │      T: 测试用例矩阵（精确的前置→操作→预期）
  ├─ 3. 杰总评审 SPAC 草案                     (先设计，再编码)
  ├─ 4. 编码                                   (严格按 SPAC 契约)
  ├─ 5. 验证 TDD 用例                          (更新每个用例的实际状态)
  ├─ 6. 更新 master/ 全局 SPAC                 (模块索引+覆盖率+依赖图)
  └─ 7. 更新 spec/README.md 总索引             (新增任务记录)
```

### 目录结构

```
spec/
├── convention.md               ← 核心规范（必读）
├── README.md                   ← 总索引
├── master/                     ← 全局 SPAC（持续维护，只存指针不存内容）
│   ├── 00-architecture.md      ←   架构分层图
│   ├── 01-module-index.md      ←   70模块索引（行数+职责+SPAC链接）
│   ├── 02-tdd-coverage.md      ←   全局 TDD 覆盖率矩阵
│   ├── 03-dependency-graph.md  ←   依赖关系图
│   └── 04-convention.md        ←   编码约定
└── 2026-06-06_refactor-game/   ← ✅ 已完成：重构任务
```

### 两个核心系统

| 系统 | 规则 | 文档 |
|------|------|------|
| **SPAC 版本管理** | 每个任务一个 `日期_动词-宾语/` 目录，独立 SPAC+TDD | `spec/convention.md §二-四` |
| **Master 高效策略** | 全局 SPAC 只存指针不存全文，按需加载，控制上下文消耗 | `spec/convention.md §五` |

### 纪律

- 🚨 **先 SPAC 后代码** — 不写无规格的代码
- 🚨 **代码改了什么，SPAC 就更新什么** — 不同步 = 债务
- 🚨 **TDD 用例写精确** — 不写"应该能工作"这类模糊描述

## 原型进度

| 阶段 | 状态 | 目标 |
|------|------|------|
| 原型1：技术验证 | ✅ 完成 | 网格+物理+拼装+管线+壳体 |
| 原型2：核心循环 | ✅ 完成 | 齿轮传动+爆炸+采集+蒸汽+场景+载具 |
| 原型3：系统交织 | ✅ 完成 | 装备系统+小人战斗+蛮族AI深化+工种体系 (2026-06-07) |
| SPAC 100% 覆盖 | ✅ 完成 | 75/75 模块全部文档化 (2026-06-08) |
| 内容扩充 | ✅ 完成 | Flyer入波次+食物零件+survival场景 (2026-06-08) |
| 玩法落地 P0-P4 | ✅ 完成 | 存储物理化+生存闭环+搬运+订单+蓝图+教程 |
| 生物群系 B1-B3 | ✅ 完成 | 4岛海洋隔离+6种植物+6种动物+生态链 (2026-06-10) |
| 重构：SPAC+TDD | ✅ 完成 | Game.java 单体→4文件, 90测试用例文档化 |
| AssetManager 拆分 | ✅ 完成 | 1357行→107行+5生成器 |
| SPAC 补课 | ✅ 完成 | 15/70模块已SPAC, 200 TDD, 0高风险 |

## 已实现功能（原型2）

| 系统 | 说明 |
|------|------|
| 齿轮传动 | 恒转轮动力源 → 齿轮啮合 → 方向交替旋转 |
| 耗能机制 | 全网统一转速 = 源头 − 总消耗，负载满停转 |
| 爆炸反馈 | 过热/过压 → 爆裂粒子 + 原因提示 + 零件销毁 |
| 资源采集 | 伐木锯刃 → 转速关联产出率 → HUD 木材计数 |
| 蒸汽动力链 | 铜釜加热 → GAS管道/管道桥 → 活塞/汽轮机 → 机械输出 |
| 蒸汽轮机 | 蒸汽驱动，120% 效率（vs 活塞 85%） |
| 管道桥 | ONI 式传送门，一根管跨过另一根不串气 |
| 验证设备 | 铜龙轮被齿轮驱动 → 成功提示 |
| 水务四件套 | 水泵/储罐/过滤器/蒸汽轮机 |
| 场景系统 | 5 个数据驱动场景，ESC 切换，partFilter 过滤 |
| 零件面板 | 9 槽热栏 + P 键弹窗 + 鼠标选择 + 交换替换 + 跨层持久 |
| 统一网格 | 三层 1m，ONI 式端口体内可视化 |
| 视觉升级 | 3D 斜边零件 + 辉光连接线 + 材质纹理外壳 + 温度微光 |
| 日志 | 控制台实时 + log.txt UTF-8 双写 |
| 调试 | F5 机械网络 dump |

## 架构特色

| 模式 | 说明 |
|------|------|
| Tag 驱动 | 零件行为由 JSON tags 声明（steam_source/driven/eff/rpm），零硬编码 ID |
| 双层 BFS | 蒸汽传播沿 Assembly 端口 + Pipe 网格双路径 BFS |
| 渲染器拆分 | WorldRenderer → 8 文件（编排器 + 7 子渲染器） |
| 统一转速 | 全网总消耗从源头减去，非逐跳递减 |
| 场景驱动 | 场景 = JSON（regions + partFilter），index.txt 索引 |

详见 `docs/design-patterns.md`

## 开发命令

```bash
# 构建项目
D:\gradle-8.4\bin\gradle.bat build --no-daemon

# 运行桌面版
D:\gradle-8.4\bin\gradle.bat desktop:run --no-daemon

# 自动化测试
runTest.bat

# 清理
D:\gradle-8.4\bin\gradle.bat clean --no-daemon
```

## 开发工具

### GameCodex 知识库

957+ 篇游戏开发文档，29 个引擎，AI 自动查询。

```
tools/gamecodex-bridge.js    ← 查询入口
tools/node_modules/gamecodex ← 依赖
```

```bash
# 查 libGDX 有什么文档
node tools/gamecodex-bridge.js list libgdx

# 搜索引擎 API
node tools/gamecodex-bridge.js search libgdx Scene2D

# 获取完整文档
node tools/gamecodex-bridge.js get libgdx-arch/R1

# 全引擎搜索（如 ECS、状态机等通用模式）
node tools/gamecodex-bridge.js search "state machine pattern"
```

AI 开发助手会在遇到引擎 API、架构模式、通用游戏系统问题时自动查询 GameCodex 作为参考。详见 `D:\claw\skills\gamecodex\SKILL.md`。

## 原型1 操作指南

### 视角控制

| 操作 | 功能 |
|------|------|
| 鼠标右键拖拽 | 平移视角 |
| 鼠标滚轮 | 缩放（0.2x - 3.0x） |

### 网格层切换

| 按键 | 功能 |
|------|------|
| Tab | 循环切换层：结构层 → 管线层 → 壳体层 |
| H | 切换操作帮助面板 |

### 结构层（1m 网格）

| 按键 | 功能 |
|------|------|
| 1-9 | 热栏快捷选择 |
| 0 / A-Z | 更多零件选择 |
| Q / E | 上一个 / 下一个 |
| R | 旋转 90° |
| P | 打开零件面板（鼠标悬停+按1-9替换热栏） |
| 左键拖拽 | 放置零件 |
| X | 删除模式 |

### 管道层（1m 网格，统一）

| 按键 | 功能 |
|------|------|
| 1-9 | 热栏快捷选择 |
| 左键拖拽 | 放置/移除管段 |
| X | 删除模式 |

### 通用

| 按键 | 功能 |
|------|------|
| Tab | 切换层级 |
| ESC | 返回场景选择 |
| 右键拖拽 | 平移视角 |
| 滚轮 | 缩放 |
| T / W / C | 测试：热源/水源/清除 |
| H | 帮助面板 |
| F5 | 机械网络自检dump |
| 左键点击 | 放置 / 删除管道 |
| X / ESC | 删除模式 |

### 壳体层（Shell）

| 按键 | 功能 |
|------|------|
| 1-5 | 选择外壳材质（木板/铁板/钢板/青铜/竹编） |
| Q / E | 上一个 / 下一个材质 |
| 左键点击 | 铺设 / 移除外壳（toggle） |

### 零件列表（结构层快捷键）

| 编号 | 零件 | 匠语名 | 尺寸 | 材质 |
|------|------|--------|------|------|
| 1 | 木板 | 坊板 | 1×1 | 木工 |
| 2 | 木齿轮 | 木齿 | 1×1 | 木工 |
| 3 | 木框 | 木骨架 | 2×1 | 木工 |
| 4 | 铜釜 | 铜釜 | 2×2 | 金属 |
| 5 | 铜管 | 铜脉管 | 1×1 | 金属 |
| 6 | 铁架 | 铁骨 | 1×2 | 金属 |
| 7 | 铁齿轮 | 铁齿 | 1×1 | 金属 |
| 8 | 活塞 | 推力柱 | 1×2 | 金属 |
| 9 | 钢板 | 百炼板 | 1×1 | 金属 |

### 物理模拟测试

| 按键 | 功能 |
|------|------|
| T | 在鼠标位置放置热源（岩浆，120°C） |
| W | 在鼠标位置放置水 |
| C | 清除鼠标位置的物质 |

### 视觉说明

- **棕色方块** = 木工零件
- **灰蓝色方块** = 金属零件
- **金色连线** = 机械端口连接
- **蓝色连线** = 液体端口连接
- **绿色连线** = 信号端口连接
- **红色底色** = 高温区域（温度可视化）
- **蓝色条纹** = 液态物质（水）
- **灰色半透明** = 气态物质
- **管线层绿色小格** = 已放置的管道
- **壳体层叠加色** = 外壳材质（带HP条）