# 地图回合与技能状态伪代码规范

## 1. 目标与范围

本规范用于在当前项目中引入“地图时间（Map Turn）”和“四类技能状态”机制，确保：

- 规则口径唯一，避免实现歧义。
- 变量命名可直接映射到代码实现。
- 与现有流程兼容：移动、战斗、道具、捕捉、存读档。
- 先支持玩家侧，后续可平滑扩展到“敌方技能”。

## 2. 规则优先级（冻结版）

当规则冲突时，按以下优先级从高到低执行：

1. 死亡流程优先：战斗失败或致死效果触发后，立即进入死亡清理。
2. 战斗成功后扣层：只有成功结算的战斗才扣除“按战斗次数持续”的状态层数。
3. 时间推进来源：仅由推进时间的行为触发（移动/拾取/tools/战斗/远程/恢复）。
4. 状态技能时间固定：状态技能 `timeCost = 0`，开启/关闭不直接推进地图时间。
5. 战斗耗时结算：`battleFinalTimeCost = max(baseBattleTimeCost, statusBattleTimeCostMax)`。
6. 多战逐场结算：同一帧内多场战斗（如多怪捕捉）逐场独立结算。
7. 存读档一致：状态容器完整写入 `flags`，读档恢复后行为一致。
8. 切楼不清状态：切楼、读档不影响状态持续；死亡按机制清临时状态。
9. 事件默认不打断状态：除非事件显式调用清理接口。

## 2.1 时间增量（`timeCost` / `deltaTime`）与地图回合（`mapTurn`）

| 概念 | 含义 | 典型变化 |
|------|------|----------|
| **时间增量** | 一次玩家行为产生的「要结算的时间单位」总数，记为 `deltaTime`（与道具/战斗等配置的 `timeCost` 或 `battleFinalTimeCost` 一致）。 | 可一次从 `0` 跳到 `3`（例如 `consumeTime(3, ...)`）。 |
| **`mapTurn`（离散 tick）** | 每完成 **1** 个时间单位的完整地图回合结算，记数 `+1`。 | 必须 **逐一** 经历 `… → k → k+1 → k+2 → …`，不可把 3 个 tick 合并成一次模糊批处理。 |

**结算顺序（写死）**：对外入口 `consumeTime(deltaTime, reason)` 在单帧内收到 `deltaTime = n` 时：

1. 先将累计量一次性加上：`flags.mapTurnState.clock += n`（表示「时间池」或总经过时间，允许与 `mapTurn` 不同步增长策略见下）。
2. 再 **循环 `n` 次** 调用 `advanceMapTurnOne(reason)`：每次只做 **一个** tick——`mapTurn += 1`，并在该 tick 内完成敌人槽位/行动等（见 §6）。

**推荐关系**：若采用「整数时间模型」，也可令 `clock` 仅在循环内每 tick `+1`，与 `mapTurn` 同步递增；**无论 `clock` 是一次 `+=n` 还是分 `n` 次 `+=1`，`advanceMapTurnOne` 必须被调用恰好 `n` 次**，以保证「0→3 的时间变化」对应「mapTurn 连续三步」的语义。

**实现落点**：调度函数挂在 [project/plugins.js](project/plugins.js) 的 `core.plugin.mapTurn`（或等价模块名）；`items.js` / `enemys.js` 仅提供数值字段 `timeCost` 等，不在图块脚本里写复杂循环。

## 3. 统一字段与运行时数据模型

### 3.1 技能定义（items 扩展）

```js
// project/items.js 每个可用技能道具（tools类）建议字段
{
  skillType: "battle" | "status" | "recover" | "ranged",
  timeCost: number,              // 统一时间消耗，状态技能固定为0
  canCancel: boolean,            // 可否取消（主要用于status）
  exclusiveGroup: string | null, // 战斗技能互斥组，例如 "battleSkill"
  durationBattles: number | null,// 状态技能持续战斗次数；null表示非按战斗计数
  stackPolicy: "refresh" | "stack" | "replace" // 后续扩展
}
```

### 3.2 怪物定义（enemys/enemy48 扩展）

```js
// project/enemys.js + enemy48 对应定义建议字段
{
  timeCost: number,               // 0=不参与地图时间调度；>0=参与
  actType: "chase" | "patrol" | "skill" | "idle",
  contactBattleOnly: boolean,     // Boss可设true：单次接触仅一场战斗
  actArgs: object | null
}
```

### 3.3 运行时状态（flags）

```js
flags.mapTurnState = {
  // 累计时间单位（可与 mapTurn 同步策略二选一，见 §2.1）
  clock: 0,
  // 已完成的离散地图回合 tick 数；仅能通过 advanceMapTurnOne 每次 +1
  mapTurn: 0,
  enemyActionGauge: {
    // [floorId]: { [enemyRuntimeId]: gaugeValue }
  },
  // 仅收录「怪物定义 timeCost > 0」的实例；按楼层缓存，供每 tick 遍历，避免全图 extractBlocks
  activeEnemiesByFloor: {
    // [floorId]: [
    //   { runtimeId, x, y, enemyId, blockIndex?, ... }  // runtimeId 实现阶段约定，如 "floorId:x:y:enemyId"
    // ]
  },
  // 可选：每次 rebuild / patch 后自增，便于调试与断言缓存有效
  activeEnemiesVersion: 0
}

flags.skillState = {
  activeStatusSkills: {
    // [skillId]: {
    //   remainBattles: number,
    //   battleTimeCost: number, // 对战斗耗时影响值，状态技能可为0或设计值
    //   sourceItemId: string
    // }
  },
  activeBattleSkillId: null, // 当前战斗技能（互斥）
  temp: {
    // 临时运行态，死亡可清空
    inBattle: false
  }
}
```

### 3.4 插件模块职责（`project/plugins.js`）

- 实现 `core.plugin.mapTurn`（名称可调整，全文保持一致），至少包含：
  - `consumeTime(deltaTime, reason)`
  - `advanceMapTurnOne(reason)`
  - `rebuildActiveEnemies(floorId)`、`patchActiveEnemiesForBlockChange(...)`（见 §6.6）
  - `resolveEnemyActionsForSingleTick(reason)`（仅遍历当前层 `activeEnemies`）
- 可选：`__enable` 总开关，关闭时上述函数为空操作，便于分步接入游戏。

## 4. 行为触发矩阵（是否推进地图时间）

- 移动一格（含事件强制移动）：推进，默认 `+1`。
- 轻按拾取（不移动）：推进，默认 `+1`。
- 使用 tools 类道具（如 bigKey）：按道具 `timeCost` 推进。
- 单场战斗：推进，按 `battleFinalTimeCost`。
- 远程技能（不可撤回）：立即按技能 `timeCost` 推进。
- 恢复技能：视同远程技能，立即按 `timeCost` 推进。
- 状态技能：`timeCost=0`，不推进地图时间。
- 纯 UI 操作（菜单、手册、预览模拟）：不推进。

**说明**：矩阵中的「推进 `+n`」均指调用 `consumeTime(n, ...)`；引擎内部必须把 `n` 拆成 `n` 次 `advanceMapTurnOne`（§2.1）。

## 5. 核心状态机

```mermaid
flowchart TD
    playerAction[PlayerAction] --> classifyAction[ClassifyActionType]
    classifyAction -->|move/getItem/tool/ranged/recover| consumeTime[consumeTime_delta]
    classifyAction -->|statusSkillToggle| updateStatus[upsertStatusSkillState]
    classifyAction -->|battleTrigger| settleBattleTime[settleBattleTimeCost]
    settleBattleTime --> consumeTime
    consumeTime --> loopTicks["loop_delta_times"]
    loopTicks --> advanceOne[advanceMapTurnOne]
    advanceOne --> resolveEnemy[resolveEnemyActionsForSingleTick]
    resolveEnemy --> maybeBattle[maybeTriggerBattles]
    maybeBattle -->|battleSuccess| afterBattle[applyStatusAfterBattle]
    maybeBattle -->|battleFail| deathClear[clearOnDeath]
    afterBattle --> persist[saveStateToFlags]
    updateStatus --> persist
    deathClear --> persist
```

## 6. 伪代码规范（变量名级别）

### 6.1 时间推进入口（一次可变多格，tick 逐一结算）

```js
function consumeTime(deltaTime, reason) {
  if (!deltaTime || deltaTime <= 0) return;

  // 累计时间可一次加上 deltaTime（与 §2.1 一致）；若采用「clock 与 mapTurn 同步每 tick +1」则改为在 advanceMapTurnOne 内 +1
  flags.mapTurnState.clock += deltaTime;

  for (let i = 0; i < deltaTime; i++) {
    advanceMapTurnOne(reason); // 内部 mapTurn += 1，且只处理单 tick
  }
}

function advanceMapTurnOne(reason) {
  flags.mapTurnState.mapTurn = (flags.mapTurnState.mapTurn || 0) + 1;
  resolveEnemyActionsForSingleTick(reason);
}
```

### 6.2 怪物行动调度（单 tick；只遍历 `activeEnemies`）

```js
function resolveEnemyActionsForSingleTick(reason) {
  const floorId = core.status.floorId;
  const list = flags.mapTurnState.activeEnemiesByFloor[floorId] || [];

  for (const enemyRef of list) {
    const runtimeId = enemyRef.runtimeId;
    const enemyDef = enemyRef.def;

    // 每 mapTurn tick：行动槽 +1；达到怪物 timeCost（怪物参与调度阈值）则行动一次
    addEnemyGauge(floorId, runtimeId, 1);

    while (getEnemyGauge(floorId, runtimeId) >= enemyDef.timeCost) {
      subEnemyGauge(floorId, runtimeId, enemyDef.timeCost);
      performEnemyAction(enemyRef); // chase/patrol/skill/idle
    }
  }
}
```

**注意**：列表中的怪物已保证 `enemyDef.timeCost > 0`（见 §6.3）；此处 **禁止** 每 tick 调用 `extractBlocks` 全图扫描。

### 6.3 `activeEnemies` 维护契约（性能）

1. **建表**：进入某楼层且地图块就绪后，调用 `rebuildActiveEnemies(floorId)`，扫描该层 `blocks`（或等价 API），仅加入「怪物图块且对应 `core.material.enemys[id].timeCost > 0`」的项，写入 `flags.mapTurnState.activeEnemiesByFloor[floorId]`，并 `activeEnemiesVersion++`。
2. **局部更新**：当 **地图上的怪物集合或坐标** 发生变化时（如 `removeBlock`、`setBlock`、怪物 `moveBlock` 结束、`hideBlock` 等），调用 `patchActiveEnemiesForBlockChange(...)` 增删或更新对应条目，**不** 全量重建（除非实现成本过高，可退化为对该层 `rebuildActiveEnemies`）。
3. **遍历**：`resolveEnemyActionsForSingleTick` **仅** 遍历当前层缓存列表；`deltaTime > 1` 时，重复 `deltaTime` 次单 tick 调度，等价于 mapTurn 从 `k` 逐步走到 `k+deltaTime`。
4. **换层**：`core.status.floorId` 切换后，下一 tick 使用新层的 `activeEnemiesByFloor[floorId]`；未访问过的楼层可无列表，首次结算前 `rebuild`。
5. **读档**：`activeEnemiesByFloor` 为派生缓存，**允许** 在读档结束、当前楼层已 `drawMap` 就绪后执行一次 `rebuildActiveEnemies(currentFloorId)`；`enemyActionGauge` 等需持久化的数据仍放在 `flags.mapTurnState` 内随存档走。

### 6.4 战斗耗时结算

```js
function settleBattleTimeCost() {
  const baseBattleTimeCost = 1;

  // 仅统计当前生效状态技能中的“战斗耗时影响”
  let statusBattleTimeCostMax = 0;
  for (const skillId in flags.skillState.activeStatusSkills) {
    const state = flags.skillState.activeStatusSkills[skillId];
    statusBattleTimeCostMax = Math.max(statusBattleTimeCostMax, state.battleTimeCost || 0);
  }

  return Math.max(baseBattleTimeCost, statusBattleTimeCostMax);
}
```

### 6.5 战斗后状态扣减

```js
function applyStatusAfterBattle(battleResult) {
  if (battleResult !== "success") return; // 失败走死亡流程

  for (const skillId in flags.skillState.activeStatusSkills) {
    const state = flags.skillState.activeStatusSkills[skillId];
    if (typeof state.remainBattles === "number") {
      state.remainBattles -= 1;
      if (state.remainBattles <= 0) {
        delete flags.skillState.activeStatusSkills[skillId];
      }
    }
  }
}
```

### 6.6 死亡清理

```js
function clearOnDeath() {
  // 预留：后续可细分清理范围
  flags.skillState.temp = {};
  flags.skillState.activeBattleSkillId = null;
  flags.skillState.activeStatusSkills = {};
}
```

## 7. 关键业务分支

### 7.1 多怪捕捉导致多场战斗

- 逐场调用战斗结算。
- 每场成功后都执行一次 `applyStatusAfterBattle("success")`。
- 任一场失败则进入死亡流程并终止后续结算。

### 7.2 Boss 单次接触

- `contactBattleOnly=true` 时，每次接触仅触发一场战斗。
- 该场战斗仍视作 1 场独立结算，按 `settleBattleTimeCost()` 推进时间。
- 不做“连战自动推进”，给玩家留操作窗口。

### 7.3 战斗技能互斥

```js
function activateBattleSkill(skillId) {
  const skill = getSkillDef(skillId);
  if (skill.exclusiveGroup === "battleSkill") {
    flags.skillState.activeBattleSkillId = skillId;
  }
}
```

## 8. 工程接入点映射

- `project/plugins.js`：实现 `core.plugin.mapTurn`（§3.4），包含 `consumeTime`、`advanceMapTurnOne`、`resolveEnemyActionsForSingleTick`、`rebuildActiveEnemies`、`patchActiveEnemiesForBlockChange`、`clearOnDeath` 等；**所有「推进多少时间就结算多少次 tick」的逻辑集中于此**。
- `project/functions.js` -> `moveOneStep`：移动完成后调用 `core.plugin.mapTurn.consumeTime(1, "move")`（或封装名一致即可）。
- `project/functions.js` -> `afterBattle`：成功结算后先 `consumeTime(settleBattleTimeCost(), "battle")`（内部按 §2.1 拆 tick），再 `applyStatusAfterBattle("success")`。
- `project/functions.js` -> `afterChangeFloor`（或 `changingFloor` 结束、楼层已绘制后）：**一行** `core.plugin.mapTurn.rebuildActiveEnemies(core.status.floorId)`，建立当前层 `activeEnemies`（§6.3）。
- `libs/items.js` -> `useItem`（或道具 `useItemEffect` 末尾）：恢复/远程/tools 按 `item.timeCost` 调用 `consumeTime(item.timeCost, ...)`；状态技能只更新 `flags.skillState`，不调用 `consumeTime`。
- `project/enemys.js`（及 enemy48）：按需为参与地图回合的怪物设置 `timeCost > 0` 与 `actType`；`timeCost === 0` 的怪不得进入 `activeEnemies`。
- **地图变更挂钩（实现时择优）**：在会改变怪物位置/存亡的 API 之后调用 `patchActiveEnemiesForBlockChange`（若短期无法统一挂钩，可退化为每次变更后对该层 `rebuildActiveEnemies`）。

## 9. 存读档一致性要求

- 所有运行态必须在 `flags.mapTurnState` 与 `flags.skillState` 下可序列化。
- 读档后不重置状态层数、不重置时间计量（`clock` / `mapTurn` / `enemyActionGauge`）、不重置技能状态。
- 切楼不触发状态清空，仅切换当前楼层；换层后须使用对应 `activeEnemiesByFloor[floorId]`。
- `activeEnemiesByFloor` 为派生缓存：读档后若列表缺失或与地图不一致，在楼层就绪时 **重建一次**（§6.3），不依赖旧缓存跨版本兼容。

## 10. 最小验收清单

- 使用状态技能后不立即推进时间，战斗成功后层数 `-1`。
- 远程/恢复技能释放立即推进时间，怪物按时间响应。
- 战斗耗时按 `max` 规则而不是累加。
- 多怪捕捉触发多场战斗时，状态层数逐场扣减。
- Boss `contactBattleOnly=true` 时单次接触仅结算一场。
- 死亡后状态与临时态清理符合预期。
- 存档读档后状态层数与地图时间连续。
- 设置怪物 `timeCost=0` 时，该怪不参与调度，性能无明显回退。
- **`consumeTime(3, ...)` 触发恰好 3 次 `advanceMapTurnOne`**：`mapTurn` 连续 `+3`，且敌人行动槽/行为按 **3 个独立 tick** 结算（可用日志或计数器断言）。
- **`activeEnemies` 路径**：每 tick 不调用全图 `extractBlocks`；进楼 `rebuild` 后，增删怪仅 `patch` 或单次 `rebuild`；`timeCost=0` 的怪不在列表中。