# Quick Design Spec: Minion Formation Showcase Combat

**Type**: Addition
**System**: Combat Coordinator / Minion Encounter AI
**GDD Reference**: `design/gdd/game-concept.md`
**Date**: 2026-07-03

## Change Summary

将当前 `CoordinatorSubmodule` 的单一环绕式站位，扩展为可配置的 `FormationProfile` 阵型配置系统。Demo 阶段默认使用“前场展示阵型”，让杂兵战服务于清晰索敌、爽快压制和打击感展示；未来高难度内容可以切换到绕背、护卫、远程压制、Boss 辅助等其它阵型。

## Motivation

当前杂兵战最大问题不是难度不足，而是 `CoordinatorSubmodule` 会倾向于让多个杂兵从玩家前后左右形成包围。四个杂兵同时分布在玩家周围时，会造成以下体验问题：

- 玩家索敌与镜头阅读成本上升。
- 背后敌人会打断展示节奏，使杂兵战从“爽快缓冲期”变成不稳定的视野压力。
- Demo 阶段希望强调玩家压制敌人、连段命中、打断反馈和武器表现，而不是让杂兵承担主要难度。

因此，杂兵战的默认目标应调整为：**镜头友好、压制爽快、低伤害但有节奏的 Showcase Combat**。

## Design Delta

Current GDD says (`design/gdd/game-concept.md`, “敌人系统 / 杂兵”):

> 当前杂兵战斗设计存在较多缺陷，是优先改进方向。

This spec changes that to:

杂兵战在 Demo 阶段不是主要难度来源，而是 Boss 战之间的节奏缓冲和战斗展示空间。`CoordinatorSubmodule` 不应固定追求全方位包围，而应根据当前 `FormationProfile` 决定站位扇区、攻击令牌、敌人职责和镜头友好程度。默认 Demo 配置必须避免敌人主动绕背，使大多数敌人保持在玩家和摄像机容易观察的前场区域。

## New Rules / Values

### 1. FormationProfile

新增可配置阵型概念：`FormationProfile`。

`FormationProfile` 是 `CoordinatorSubmodule` 的运行时配置来源，用于决定敌人如何围绕玩家站位、何时进攻、哪些敌人等待、哪些敌人施加远程压力。

建议用 `ScriptableObject` 实现，命名示例：

- `DemoShowcaseFormationProfile`
- `FlankingFormationProfile`
- `BossSupportFormationProfile`
- `RangedPressureFormationProfile`

### 2. FormationProfile 参数

| Knob | Default: DemoShowcase | Range / Options | Category | Rationale |
|------|------------------------|-----------------|----------|-----------|
| `allowedSectorMode` | `CameraForwardArc` | `CameraForwardArc`, `PlayerForwardArc`, `FullRing`, `CustomWeightedSectors` | readability | Demo 默认只允许前场或镜头友好扇区 |
| `frontArcDegrees` | `160` | `90-220` | readability | 控制敌人可站在玩家/镜头前方的角度范围 |
| `allowBackstabSectors` | `false` | bool | difficulty | Demo 禁止绕背；高难度可开启 |
| `maxMeleeAttackTokens` | `1` | `1-4` | pressure | 同时只有一个近战杂兵真正进攻 |
| `maxRangedAttackTokens` | `1` | `0-3` | pressure | 允许轻量远程压力，但不形成弹幕压迫 |
| `maxActiveThreats` | `2` | `1-5` | pacing | 同时威胁源数量上限 |
| `idleRoleWhenNoToken` | `ShowcaseVictim` | `ShowcaseVictim`, `Reposition`, `Taunt`, `Guard`, `HoldDistance` | flow | 无令牌敌人不绕背偷袭，而是服务展示节奏 |
| `preferLockTargetVicinity` | `true` | bool | camera | 玩家锁定目标时，其它敌人优先分布在锁定目标左右可见区域 |
| `sectorReassignmentCooldown` | `2.0s` | `0.5-5.0s` | stability | 防止敌人因玩家小幅移动频繁换位 |
| `backSectorWeight` | `0` | `0-1` | difficulty | Demo 为 0；高难度可提升 |
| `sideSectorWeight` | `0.7` | `0-1` | readability | 允许侧前方敌人参与，但避免正背后 |
| `frontSectorWeight` | `1.0` | `0-1` | readability | 正前方/侧前方优先 |

### 3. Enemy Tactical Roles

`CoordinatorSubmodule` 应为敌人分配临时战术职责，而不是只分配扇区。

| Role | Behavior | Demo Usage |
|------|----------|------------|
| `ActiveMelee` | 持有 `MeleeAttack` token，允许主动近战攻击 | 同时最多 1 个 |
| `ActiveRanged` | 持有 `RangedAttack` token，允许远程射击或轻量压迫 | 同时最多 1 个 |
| `ShowcaseVictim` | 靠近玩家前场，抗打断低，容易被连段压制 | Demo 常用 |
| `Reposition` | 移动到可见扇区，不攻击 | 用于填补站位 |
| `Taunt` | 仅播放待机/威吓/轻微移动，不制造威胁 | 若已有动画则使用；否则等同 `Reposition` |
| `Guard` | 保护指定目标或区域 | 未来 Boss 辅助配置使用 |
| `Flanker` | 允许绕背或侧后方攻击 | Demo 默认禁用，高难度配置使用 |

### 4. DemoShowcaseFormationProfile

Demo 阶段默认配置：

- 阵型目标：玩家爽快压制，镜头清晰，低受伤率。
- 允许扇区：镜头前方或玩家前方约 `160°`。
- 禁止绕背：`allowBackstabSectors = false`。
- 近战攻击令牌：`maxMeleeAttackTokens = 1`。
- 远程攻击令牌：`maxRangedAttackTokens = 1`。
- 同时威胁源：`maxActiveThreats = 2`。
- 无令牌敌人：进入 `ShowcaseVictim` 或 `Reposition`，不主动从背后攻击。
- 4 杂兵场景推荐分工：
  - 1 个 `ActiveMelee`
  - 1 个 `ActiveRanged`
  - 1 个 `ShowcaseVictim`
  - 1 个 `Reposition`

### 5. Future Formation Examples

这些配置不要求本次实现全部完成，但 `FormationProfile` 结构必须支持：

#### FlankingFormationProfile

用于未来高难度房间。

- `allowedSectorMode = FullRing`
- `allowBackstabSectors = true`
- `backSectorWeight > 0`
- 允许 `Flanker` role
- 近战 token 可提高到 2 或 3

#### BossSupportFormationProfile

用于未来 Boss + 杂兵混合战。

- 杂兵优先避开 Boss 主攻击扇区。
- `Guard` 和 `ActiveRanged` 权重提高。
- 杂兵不抢 Boss 的镜头中心。
- Boss 战难度仍由 Boss 负责，杂兵只制造轻量干扰或补充节奏。

#### RangedPressureFormationProfile

用于远程敌人主题房间。

- `maxRangedAttackTokens` 可高于 `maxMeleeAttackTokens`。
- 远程敌人优先占据前侧方或中距离区域。
- 禁止远程敌人全部分散到背后。

## Minion Feel Rules

### L1_Assault_Pawn

Demo 定位：近战爽感沙包。

- 抗打断能力应低，玩家能持续压制。
- 近战进攻时只在持有 `ActiveMelee` role 时主动攻击。
- 未持有攻击 role 时，优先作为 `ShowcaseVictim` 进入玩家前侧可见区域。
- 被 `Medium / Heavy / Disruption` 命中时，应提供明显硬直、击退或 Feedback。

### L2_Assault_Stinger

Demo 定位：远程轻压迫目标。

- 只在持有 `ActiveRanged` role 时射击。
- 弹体压力应低于 Boss 战，不应形成高密度弹幕。
- 弹体被 `Perfect Dodge / Perfect Block / Reflection` 处理时，应给予玩家明显收益，例如 `Passion`、能量或反击窗口。
- 站位应优先保持在前侧方或中距离，不应默认绕到玩家背后。

## Affected Systems

| System | Impact | Action Required |
|--------|--------|-----------------|
| `CoordinatorSubmodule` | 从固定扇区/令牌逻辑扩展为 profile-driven 阵型协调 | 添加 `FormationProfile` 数据入口、扇区权重、role 分配 |
| Behavior Designer AI | 行为树需要读取当前 tactical role / token 状态 | 增加或调整条件节点，避免无令牌敌人强行攻击 |
| `L1_Assault_Pawn` | 默认承担近战爽感沙包职责 | 按 role 控制主动攻击、防御、靠近行为 |
| `L2_Assault_Stinger` | 默认承担远程轻压迫职责 | 按 role 控制射击频率与站位 |
| `PassionSystem` | 可用于强化完美处理杂兵攻击的奖励 | 视实现决定是否增加额外奖励钩子 |
| `SLSUtilities/Feedback` | 用于放大杂兵被打断/被压制反馈 | 优先复用现有 Feedback，不新增 VFX |
| Encounter / Wave 配置 | 不同房间可指定不同阵型配置 | 后续为房间或波次挂载 profile |

## Acceptance Criteria

- [ ] `CoordinatorSubmodule` 不再只使用单一固定环绕逻辑，至少支持一个可配置 `FormationProfile` 输入。
- [ ] Demo 默认配置下，4 个杂兵不会主动形成玩家前后左右完整包围。
- [ ] Demo 默认配置下，玩家背后扇区不会被普通杂兵优先占用。
- [ ] Demo 默认配置下，同时主动近战攻击的杂兵数量不超过 1。
- [ ] Demo 默认配置下，同时主动远程攻击的杂兵数量不超过 1。
- [ ] 无攻击 token 的杂兵不会继续强行攻击，而是进入 `ShowcaseVictim`、`Reposition` 或等价低威胁行为。
- [ ] `L1_Assault_Pawn` 在杂兵战中更容易被玩家压制和打断，不承担主要难度压力。
- [ ] `L2_Assault_Stinger` 的远程攻击提供轻量节奏压力，但不破坏 Demo 的爽快压制体验。
- [ ] 配置结构允许未来启用绕背阵型，不需要重写 `CoordinatorSubmodule` 的核心算法。
- [ ] No regression: `C1_Axe` Boss 战不因 Demo 杂兵阵型配置而被削弱或改变核心难度职责。

## GDD Update Required?

Yes.

建议后续更新 `design/gdd/game-concept.md` 的“敌人系统 / 杂兵”与“战斗系统”部分，加入以下原则：

> Demo 阶段杂兵战承担“爽快缓冲期”和“战斗展示”职责，而非主要难度来源。杂兵阵型由 `CoordinatorSubmodule` 的 `FormationProfile` 配置驱动；默认 Demo 阵型强调镜头友好、前场可见、低绕背压力和高受击反馈。未来高难度内容可以通过其它 `FormationProfile` 启用绕背、护卫、远程压制或 Boss 辅助职责。

本 quick spec 先作为实现依据；GDD 正文可在实现方案确定后再同步。