chore: initial commit

2026-05-08 11:04:00 +08:00
commit f55d2a57c3
6278 changed files with 866081 additions and 0 deletions
--- a/Docs/DesignSpec/09_ProgressionSystem.md
+++ b/Docs/DesignSpec/09_ProgressionSystem.md
@@ -0,0 +1,246 @@
+# 09 · 进程系统规范
+
+> **所属文档集** [← 返回索引](./README.md)  
+> **摘要**：能力解锁、门控系统、Geo 遗骸机制与游戏完成度追踪。
+
+---
+
+## 目录
+
+1. [进程设计原则](#1-进程设计原则)
+2. [能力系统](#2-能力系统)
+3. [门控系统](#3-门控系统)
+4. [Geo 遗骸机制](#4-geo-遗骸机制)
+5. [完成度追踪](#5-完成度追踪)
+6. [护符系统](#6-护符系统)
+7. [进程事件目录](#7-进程事件目录)
+
+---
+
+## 1. 进程设计原则
+
+| 原则 | 说明 |
+|------|------|
+| **有机探索** | 能力解锁带来新的区域通路，而非仅仅提升战斗数值 |
+| **无死门** | 不存在因获取顺序错误而无法继续的情况 |
+| **多路径** | 大多数门控有多种解锁方式（能力/密钥/支线）|
+| **数据驱动** | 所有解锁条件用数据定义，逻辑层不硬编码 |
+
+---
+
+## 2. 能力系统
+
+### 2.1 能力数据模型
+
+```
+DataModel AbilityData {
+    abilityId       : ID
+    displayName     : String
+    description     : String
+    ──────────────────────────────────
+    abilityType     : AbilityType        // 移动/战斗/探索/形态
+    unlockSource    : UnlockSource       // 如何获得（Boss掉落/收集品/商店）
+    ──────────────────────────────────
+    gatesUnlocked   : List<GateType>     // 该能力解锁哪些门控类型
+    movementFlags   : Flags<MovementAbilityFlag>  // 移动系统的能力开关
+    combatFlags     : Flags<CombatAbilityFlag>    // 战斗系统的能力开关
+}
+```
+
+### 2.2 核心能力列表
+
+| 能力 ID | 名称 | 获取方式 | 解锁内容 |
+|--------|------|---------|---------|
+| `DoubleJump` | 双跳 | 初始能力（教程）| 空中二段跳 |
+| `WallGrab` | 墙抓 | 区域 1 Boss | 抓墙/墙跳 |
+| `AerialDash` | 空中冲刺 | 区域 2 Boss | 8方向空中冲刺 |
+| `Plunge` | 下冲 | 区域 3 收集品 | 下冲攻击 |
+| `SwimAbility` | 游泳 | 区域 4 收集品 | 进入液体区域 |
+| `SkyFormUnlock` | 天魂解锁 | 剧情节点 | 天魂形态 |
+| `EarthFormUnlock` | 地魂解锁 | 剧情节点 | 地魂形态 |
+| `DeathFormUnlock` | 命魂解锁 | 剧情节点 | 命魂形态 |
+| `SoulSkillUpgrade` | 魂技能升级 | 特定 NPC | 魂技能二阶效果 |
+
+### 2.3 能力解锁流程
+
+```
+玩家获得 AbilityData（来源：Boss掉落/拾取/购买）
+  → 发出 OnAbilityUnlocked 事件（abilityId）
+  → 更新 SaveData.unlockedAbilities 集合
+  → 玩家系统注册新 movementFlags 和 combatFlags
+  → 门控系统重新评估所有已知门控状态
+  → 地图更新（若新能力打开了新路径）
+```
+
+---
+
+## 3. 门控系统
+
+### 3.1 门控数据模型
+
+```
+DataModel GateData {
+    gateId          : ID
+    roomId          : ID
+    displayName     : String
+    ──────────────────────────────────
+    conditions      : List<GateCondition>   // 解锁条件（满足任一即可，OR逻辑）
+    unlockMode      : GateUnlockMode        // 永久解锁 / 单次通过
+    ──────────────────────────────────
+    lockedVisual    : VisualState
+    unlockedVisual  : VisualState
+    tooltipText     : String                // 玩家尝试进入未解锁门时显示
+}
+
+DataModel GateCondition {
+    conditionType   : GateConditionType
+    targetId        : ID                    // 依条件类型：能力ID/密钥ID/任务ID
+    quantity        : Optional<Integer>     // 若需要数量（如 Geo 消耗）
+}
+```
+
+### 3.2 门控条件类型
+
+| 条件类型 | 说明 | 示例 |
+|---------|------|------|
+| `HasAbility` | 玩家已解锁某能力 | 需要双跳才能通过高台 |
+| `HasItem` | 玩家持有某关键道具 | 需要古城钥匙 |
+| `BossDefeated` | 某 Boss 已被击败 | 区域终 Boss 死后大门开启 |
+| `QuestComplete` | 某任务/剧情已完成 | NPC 认可后打开秘道 |
+| `PaidGeo` | 支付 Geo（商人/通行税）| 进入特定区域收费 |
+| `WorldFlag` | 某世界标记为真 | 触发了某机关后解锁 |
+
+---
+
+## 4. Geo 遗骸机制
+
+### 4.1 规则规范
+
+```
+玩家死亡:
+  → 当前持有的 Geo 全部转移为遗骸（GeoShade）
+  → 遗骸实体生成于死亡位置
+  → 玩家的 Geo 归零
+  → 若已有遗骸（上一次死亡未取回）:
+       → 旧遗骸永久消失（及其中的 Geo）
+       → 新遗骸替代旧遗骸
+
+玩家到达遗骸位置并触碰:
+  → 恢复遗骸中的全部 Geo
+  → 遗骸消失
+  → 发出 OnGeoShadeRecovered 事件
+```
+
+### 4.2 数据模型
+
+```
+DataModel GeoShadeState {
+    exists          : Boolean
+    geoAmount       : Integer
+    deathPosition   : Vector2
+    roomId          : ID                // 遗骸所在房间（跨房间持久存在）
+}
+```
+
+> **设计决策**：再次死亡前遗骸永久消失  
+> **原因**：来自 Hollow Knight 的核心惩罚机制。失去 Geo 的焦虑推动玩家谨慎前进，而非莽撞行事。
+
+---
+
+## 5. 完成度追踪
+
+### 5.1 完成度指标
+
+```
+DataModel CompletionData {
+    ──── 主线进程 ────────────────────
+    mainQuestStage  : Integer           // 当前主线阶段
+    endingUnlocked  : Optional<EndingType>
+    
+    ──── 探索进度 ────────────────────
+    roomsVisited    : Set<ID>           // 已访问房间
+    mapRevealPercent: Number            // 0.0~1.0
+    
+    ──── 收集进度 ────────────────────
+    maxHPUpCount    : Integer           // 已拾取 HP 上限碎片数
+    maxSoulUpCount  : Integer           // 已拾取灵力上限碎片数
+    maxSpiritUpCount: Integer           // 已拾取魄元上限碎片数
+    lorePiecesFound : Set<ID>
+    
+    ──── 挑战进度 ────────────────────
+    bossesDefeated  : Set<ID>
+    bossesParried   : Set<ID>           // 弹反过 Boss 至少一次
+    secretsFound    : Set<ID>
+}
+```
+
+### 5.2 三结局条件
+
+| 结局 | 触发条件 |
+|------|---------|
+| **结局 A**（普通结局）| 击败最终 Boss，未满足结局 B/C 条件 |
+| **结局 B**（完全结局）| 击败所有 Boss + 主线所有剧情节点 + 特定 NPC 任务完成 |
+| **结局 C**（隐藏结局）| 发现隐藏区域、触发特定世界标记序列 + 结局 B 条件 |
+
+---
+
+## 6. 护符系统
+
+### 6.1 护符数据模型
+
+```
+DataModel CharmData {
+    charmId         : ID
+    displayName     : String
+    description     : String
+    ──────────────────────────────────
+    notchCost       : Integer           // 装备槽位消耗
+    ──────────────────────────────────
+    effects         : List<CharmEffect>
+    comboCharms     : Optional<List<ID>> // 与哪些护符组合触发强化效果
+    comboEffects    : Optional<List<CharmEffect>>
+}
+
+DataModel CharmEffect {
+    effectType      : CharmEffectType
+    params          : Map<String, Number>
+}
+```
+
+### 6.2 护符槽位规则
+
+| 规则项 | 说明 |
+|--------|------|
+| 初始槽位 | 3 个 Notch |
+| 扩展方式 | 特定 NPC（付 Geo）增加 Notch |
+| 最大 Notch | 11 个（初始 3 + 最多可购买 8）|
+| 过量装备 | 可强行装备超过槽位（超出则 HP 上限临时减半）|
+
+### 6.3 护符效果类型
+
+| 类型 | 说明 | 参数 |
+|------|------|------|
+| `StatModifier` | 修改某资源上限/恢复量 | `statType`, `delta` |
+| `DamageModifier` | 修改某类攻击的伤害倍率 | `attackType`, `multiplier` |
+| `WeaponOverride` | 覆盖某形态的武器 | `formId`, `weaponId` |
+| `SkillModifier` | 修改技能效果参数 | `skillId`, `paramKey`, `newValue` |
+| `AerialDashCount` | 增加空中冲刺充能次数 | `additionalCharges` |
+| `ParryWindowExpand` | 扩大弹反时间窗口 | `addedSeconds` |
+| `OnHitEffect` | 命中时附加效果 | `effectType`, `chance` |
+
+---
+
+## 7. 进程事件目录
+
+| 事件 | 触发时机 | 载荷 |
+|------|---------|------|
+| `OnAbilityUnlocked` | 获得新能力 | `abilityId` |
+| `OnGateUnlocked` | 门控条件满足，门开启 | `gateId` |
+| `OnCharmEquipped` | 装备护符 | `charmId, slotIndex` |
+| `OnCharmUnequipped` | 卸下护符 | `charmId` |
+| `OnCharmComboActivated` | 护符组合效果触发 | `charmIds: List<ID>` |
+| `OnGeoShadeCreated` | 死亡创建遗骸 | `position, amount` |
+| `OnGeoShadeRecovered` | 拾取遗骸 | `amount` |
+| `OnGeoShadeLost` | 遗骸永久消失 | `amount` |
+| `OnEndingUnlocked` | 结局条件满足 | `endingType` |
+| `OnCompletionMilestone` | 完成度达到里程碑 | `milestoneId, percent` |