PROJECT-v M4：关卡原型与 Boss 压力验证

Posted on

M4 的目标不是继续给 M3 战斗链堆更多孤立功能，而是把已经接通的移动、攻击、闪避、技能、武器倍率和反馈链放进连续房间、难度缩放、Boss 弱点和镜像 Boss 的压力环境里验证。换句话说，M4 关心的是：PROJECT-V 是否已经从“单场景战斗能跑通”推进到“关卡和 Boss 语境下仍能形成可玩构成”。

除注明 docs 仓库的文档外，本文所有工程路径均以 PROJECT-V 项目根目录为基准；docs 路径均以 PROJECT-V-game-docs 根目录为基准。

关联提交和依据

M4 功能主体提交：

commit 用途
6baacf6 feat(levels): deliver M4 level and boss prototype，关卡原型与 Boss 里程碑实现

分支状态：

分支 说明
develop M4 实施分支
origin/develop 已推送

主要参考产物：

类型 路径
交付报告 reports/M4_delivery_report.html
QA 报告 qa/reports/M4_test_report.md
完整关卡测试用例 qa/test_cases/M4_full_level.md
Boss 行为矩阵 qa/test_cases/M4_boss_matrix.md
T-DEV30 回归结果 qa/results/M4_Pre_TDEV30_PlayMode.xml
EditMode 结果 qa/results/M4_EditMode_TestResults.xml
PlayMode 结果 qa/results/M4_PlayMode_TestResults.xml
60s Runtime Probe qa/results/M4_RuntimeProbe_60s.json
Sprint 状态，docs 仓库 project/sprints/SPRINT_04.md
Project State，docs 仓库 project/PROJECT_STATE.md
M4 关卡 spec，docs 仓库 design/feature_specs/M4_levels.md
M4 Boss 行为，docs 仓库 design/boss_behavior/M4_boss_behaviors.md
M4 难度缩放，docs 仓库 design/difficulty_scaling/M4_difficulty_scaling.md

M4 的目标和边界

M4 只做关卡原型和 Boss 压力验证。它不改变 M3 的主角战斗边界，也不进入 M5 的程序生成算法。

M4 纳入实现的内容：

  • 3 个异世界手工关卡原型：废土、赛博、生化。

  • 27 个房间配置：每个异世界 9 个房间。

  • LevelManager / RoomManager 关卡与房间状态流。

  • LevelConfigSO / RoomConfigSO 数据化房间序列、清理条件、奖励、商店、休息点和 Boss 房。

  • 怪物火车式难度缩放：升级强度、房间进度和世界观压力共同影响 HP、伤害、数量、冷却和 telegraph。

  • 3 个 Boss：废土军阀、机关头领、变异母体。

  • Boss telegraph、招式激活、弱点暴露、弱点破坏和阶段切换事件。

  • 镜像 Boss 参数化系统。

  • T-DEV30 接地稳定性修复。

  • M4 runtime probe：P50/P95/P99 FPS、GC collections、Mono memory delta、房间/Boss/镜像 Boss 检查。

  • EditMode、PlayMode、T-DEV30 回归、Windows Development Build 和 60s probe 验证。

M4 明确不做：

  • 程序生成路线。M4 用手工房间控制变量，M5 再做 seed、强约束生成和回归验证。

  • 正式美术与正式音频。视觉、BGM、SFX 仍为占位资源。

  • 自定义关卡编辑器。

  • 联网、云存档、排行榜或远程资源下载。

  • 新的主角玩法边界，不引入枪械、魔法、光剑、火球、召唤物或能量武器玩法。

这个边界比“多做几个功能”更重要。M4 如果同时做程序生成、最终美术、正式 Boss 表现和复杂 UI，任何问题都无法判断到底来自生成算法、战斗手感、内容节奏还是表现资源。先用手工关卡压测战斗链，是更稳的顺序。

工程生成入口

M4 的工程入口是 unity-project/Assets/_Project/Editor/M4ProjectBuilder.cs。

SetupM4() 首先调用 M3ProjectBuilder.SetupM3()，再生成 M4 资源。这说明 M4 是对 M3 的增量验证，而不是另起一套关卡或 Boss 框架。

核心生成物：

类别 路径
难度缩放配置 unity-project/Assets/_Project/Levels/SO/Difficulty/DifficultyScaling_M4.asset
Boss 配置目录 unity-project/Assets/_Project/Combat/SO/Bosses/
Level 配置目录 unity-project/Assets/_Project/Levels/SO/Levels/
Room 配置目录 unity-project/Assets/_Project/Levels/SO/Rooms/
M4 测试场景 unity-project/Assets/Scenes/TestScenes/M4_FullLevel.unity
废土关卡场景 unity-project/Assets/Scenes/Levels/Wasteland/Wasteland_Level1.unity
赛博关卡场景 unity-project/Assets/Scenes/Levels/Cyberpunk/Cyberpunk_Level1.unity
生化关卡场景 unity-project/Assets/Scenes/Levels/Biohazard/Biohazard_Level1.unity

VerifyM4Setup() 的验收点包括：

  • M4 难度配置存在。

  • 镜像 Boss 配置存在。

  • 3 个 Boss 配置存在且名称正确。

  • 3 个 Level 配置存在，世界观和 Boss id 对齐。

  • 3 个正式关卡场景和 M4_FullLevel.unity 存在。

  • M4 full level scene 包含可运行的关卡、Boss、镜像 Boss 和 runtime probe harness。

这套 builder 延续了 M1-M3 的工程路线：阶段交付不是靠某次手工 Unity 场景状态，而是靠可重建、可验证的 Editor tooling。

Level 和 Room 数据结构

M4 新增 Levels 模块：

文件 职责
unity-project/Assets/_Project/Levels/Scripts/LevelTypes.cs 定义房间类型、清理条件、奖励、商店、休息、Boss 房和难度上下文
unity-project/Assets/_Project/Levels/Scripts/LevelConfigSO.cs 定义一整关的世界观、章节、Boss、房间序列、奖励池和过渡参数
unity-project/Assets/_Project/Levels/Scripts/RoomConfigSO.cs 定义单个房间的类型、场景 key、门、清理条件、刷怪、奖励、商店、休息点和 Boss 配置
unity-project/Assets/_Project/Levels/Scripts/LevelManager.cs 管一整关的开始、房间推进、房间清理统计、Boss 房进入和章节完成事件
unity-project/Assets/_Project/Levels/Scripts/RoomManager.cs 管单个房间的进入、清理、敌人死亡监听、Boss 死亡监听和出口请求

房间类型：

1
2
3
4
5
6
7
8
Start
Combat
Elite
Reward
Shop
Rest
Boss
MirrorBoss

房间清理条件：

1
2
3
4
5
6
7
None
DefeatAllEnemies
DefeatElite
ClaimReward
LeaveShop
UseRestPoint
DefeatBoss

M4 每个异世界关卡当前是 9 房间路线：

1
Start -> Combat -> Reward -> Elite -> Combat -> Shop -> Rest -> Combat -> Boss

实际落地的 Level 配置：

世界观 Level 配置 房间数 Boss
Wasteland unity-project/Assets/_Project/Levels/SO/Levels/Level_Wasteland_Chapter1.asset 9 boss_wasteland_warlord
Cyberpunk unity-project/Assets/_Project/Levels/SO/Levels/Level_Cyberpunk_Chapter1.asset 9 boss_mechanism_chief
Biohazard unity-project/Assets/_Project/Levels/SO/Levels/Level_Biohazard_Chapter1.asset 9 boss_mutation_matriarch

LevelManager 的关键职责是只管关卡推进，不接管敌人 AI 和 Boss 招式：

1
2
3
4
5
6
7
8
9
10
11
BeginLevel()
  -> OnLevelStarted
  -> AdvanceToRoom(0)
  -> OnRoomEntered
  -> RoomManager.MarkCleared()
  -> OnRoomCleared
  -> RequestAdvanceFrom()
  -> OnRoomTransitionStarted
  -> OnRoomTransitionCompleted
  -> Boss room: OnBossRoomEntered
  -> Boss defeated: OnLevelCompleted

QA 中发现的一个真实运行时问题是：生成场景中的 RoomManager.owner 不会被 Unity 序列化。现在 LevelManager.Awake() 会调用 Configure(config, rooms, purity)，遍历所有 RoomManager 并重绑 owner 和对应 RoomConfigSO。这个修复很关键，否则 PlayMode 里房间能被清理，但出口推进会因为 owner 为空而失败。

难度缩放

M4 的难度缩放不是简单沿用 M2 的敌人数量/HP 公式，而是升级成三类压力输入：

输入 含义
upgradeIntensity 本局升级强度归一化，来自通用升级、世界观被动、主动技能、武器世界观修饰和协同
roomProgress 当前房间在整条路线中的进度
worldPressure 武器世界观修饰、build 涉及的世界观数量、跨世界观协同、房间/主 build 世界观不匹配

核心实现位于：

  • unity-project/Assets/_Project/Levels/Scripts/DifficultyScalingConfigSO.cs

  • unity-project/Assets/_Project/Levels/Scripts/DifficultyScaler.cs

DifficultyScaler.Evaluate() 会计算：

输出 用途
enemyHpMultiplier 敌人 HP 倍率
enemyDamageMultiplier 敌人伤害倍率
enemyCountMultiplier spawn budget / 目标敌人数压力
enemyCooldownMultiplier 攻击冷却倍率，越低越频繁
enemyTelegraphMultiplier telegraph 压缩倍率，但有下限
targetEnemyCount 当前房间目标敌人数

这套公式的重点是“房间越靠后、build 越强、世界观压力越高，敌人压力越高”，但所有数值都经过 clamp。它避免了两个极端：玩家 build 强到后半局无脑碾压，或者系统为了追压力直接生成不可读、不可反应的攻击。

Boss 压力也独立评估：

1
2
3
4
bossPressure =
  levelOrder pressure
  + upgrade intensity pressure
  + world pressure

M4 没有把难度和程序生成绑定死。它先让手工房间能被数值公式评估，为 M5 的 seed route 和强约束生成保留入口。

Boss 系统

Boss 系统由配置、控制器和弱点三个核心层组成：

文件 职责
unity-project/Assets/_Project/Combat/Scripts/BossConfigSO.cs Boss 基础数值、招式、weakpoint、phase 和资源字段
unity-project/Assets/_Project/Combat/Scripts/BossController.cs 配置 HP、运行招式 coroutine、发布 telegraph/activation/defeated/phase 事件
unity-project/Assets/_Project/Combat/Scripts/BossWeakpoint.cs 管弱点暴露、破坏槽、弱点击中、弱点破坏和阶段触发

M4 的三个 Boss 配置：

Boss 世界观 HP 招式数 弱点数 验证重点
Wasteland Warlord / 废土军阀 Wasteland 850 5 3 慢起手、重压迫、绕背惩罚
Mechanism Chief / 机关头领 Cyberpunk 760 5 3 中高速节奏、机关、短窗口打点
Mutation Matriarch / 变异母体 Biohazard 950 5 2 大体型控场、召出压力、清场优先级

Boss 招式是数据化的 BossMoveConfig，字段包括：

  • moveType

  • telegraphLevel

  • telegraphDuration

  • activeDuration

  • recoveryDuration

  • cooldown

  • damageMultiplier

  • hitboxShape

  • dodgeRule

  • exposedWeakpointId

  • weakpointExposeDuration

  • weight

BossController.BeginMove() 会启动招式流程：

1
2
3
4
5
OnBossMoveTelegraphStarted
  -> wait telegraphDuration
  -> OnBossMoveActivated
  -> expose configured weakpoint
  -> wait activeDuration + recoveryDuration

这意味着 Boss 攻击不是瞬时扣血，而是有可测试的预警、激活、恢复和弱点窗口。PlayMode 可以断言 telegraph 事件、activation 事件和弱点暴露，而不是只看 Boss 有没有动。

弱点系统负责把“打 Boss”变成更具体的战斗目标。BossWeakpoint.RegisterHit() 在弱点暴露时扣破坏槽，发布 OnBossWeakpointHit，破坏后发布 OnBossWeakpointDestroyed，并可调用 BossController.ForcePhase() 推进阶段。

镜像 Boss

镜像 Boss 实现位于：

  • unity-project/Assets/_Project/Combat/Scripts/MirrorBossConfigSO.cs

  • unity-project/Assets/_Project/Combat/Scripts/MirrorBossController.cs

M4 的镜像 Boss 不直接复制玩家数值。它只读取纯度、build 强度和关卡序号，输出一组参数化结果：

输出 含义
shouldSpawn 是否触发镜像 Boss
mirrorForm pure / corrupted / none
hpMultiplier 镜像 Boss HP 倍率
attackMultiplier 攻击倍率
skillCount 镜像技能数量
passiveUpgradeRate 被动升级比例
cooldownMultiplier 冷却倍率
telegraphMultiplier telegraph 倍率

触发规则：

纯度 行为
< 30% 触发 pure 镜像形态
30%-70% 不触发
> 70% 触发 corrupted 镜像形态

这个设计避免了一个常见错误：把镜像 Boss 做成“玩家 build 的数值复制体”。复制玩家数值很容易制造无解情况，尤其是 cooldown、无敌帧和技能堆叠。M4 的做法是抽取 build 强度，再通过配置上下界约束。

T-DEV30 接地稳定性修复

M4 开始前处理了一个影响关卡体验的 P1 问题：角色在平台边缘、墙边或实体边界悬空时，可能因为接地检测误判而不自然下落。

修复涉及：

文件 变化
unity-project/Assets/_Project/Player/Scripts/GroundCheckHelper.cs 新增多点 raycast 接地检测
unity-project/Assets/_Project/Player/Scripts/PlayerController.cs 接入新检测、跳跃后接地 lockout、碰撞退出后重查接地

GroundCheckHelper.IsGrounded() 的关键规则：

  • 上升速度大于 0.01 时直接判定未接地。

  • 从 collider 左脚、中脚、右脚三个点向下 raycast。

  • 命中的 surface normal 必须 normal.y >= 0.55，避免墙面/侧边误判为地面。

  • raycast 起点略微抬高，减少 collider 边缘浮动误差。

PlayerController 还增加了 GroundingLockoutAfterJump = 0.08s，跳起后短时间内强制不接地。这能防止刚起跳的物理接触残留把角色立刻拉回 grounded 状态。

这个修复对 M4 很实际。关卡里开始有更多平台、边缘、墙体和 Boss arena，M1/M2 测试场景里不显眼的接地误判会在 M4 被放大。

Runtime Probe 增强

M3 已经有 60s probe，但只有平均 FPS、min/max 和系统就绪字段。M4 的 probe 解决了 M3 留下的一个问题：单个 min FPS outlier 不能说明整体帧稳定性。

实现位于 unity-project/Assets/_Project/Levels/Scripts/M4RuntimeProbe.cs。

M4 probe 的运行逻辑：

  1. 识别 -m4Probe 参数。

  2. 设置 Application.targetFrameRate = 60，关闭 vSync。

  3. 记录 GC collection 起始计数和 Mono memory。

  4. 自动 BeginLevel()。

  5. warmup 后触发脚本动作：闪避、U 技能、Boss 招式、清理前三个房间、镜像 Boss 评估。

  6. 收集每帧 FPS 样本。

  7. 输出 average/min/max、P50/P95/P99、GC、memory delta 和系统就绪字段。

60s 结果：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "warmupSeconds": 3,
  "totalElapsedSeconds": 63.006,
  "measuredSeconds": 60.006,
  "frameCount": 3600,
  "averageFps": 59.994,
  "minFps": 56.584,
  "maxFps": 75.133,
  "p50Fps": 60,
  "p95Fps": 59.996,
  "p99Fps": 59.793,
  "gcCollections": 0,
  "monoMemoryDeltaBytes": 8192,
  "m4SystemsReady": true,
  "roomsTotal": 9,
  "roomsCleared": 3,
  "dodgeStarted": true,
  "skillUActivated": true,
  "bossMoveStarted": true,
  "mirrorSpawned": true
}

这组结果比 M3 的 probe 更有解释力。平均 FPS 59.994 只是表层结果，真正重要的是 P95/P99 仍贴近 60、gcCollections 为 0，并且 probe 实际触发了房间推进、闪避、技能、Boss move 和镜像 Boss。

验证结果

M4 当前验证结果如下：

验证项 证据 结果
M4 setup generation ProjectV.EditorTools.M4ProjectBuilder.SetupM4 Passed
M4 setup verification ProjectV.EditorTools.M4ProjectBuilder.VerifyM4Setup Passed
T-DEV30 grounding precheck qa/results/M4_Pre_TDEV30_PlayMode.xml 14 / 14 passed
EditMode qa/results/M4_EditMode_TestResults.xml 25 / 25 passed
PlayMode qa/results/M4_PlayMode_TestResults.xml 19 / 19 passed
Windows Development Build unity-project/Builds/Windows/PROJECT-V.exe exit 0
Runtime Probe 60s qa/results/M4_RuntimeProbe_60s.json Avg 59.994 FPS，P95 59.996 FPS，GC 0

EditMode 的 25 个测试包含：

  • M1 setup 回归：5 个。

  • M2 combat 回归：8 个。

  • M3 full combat 回归：7 个。

  • M4 full level：5 个。

PlayMode 的 19 个测试包含：

  • M2 combat 回归：4 个。

  • M3 full combat 回归：6 个。

  • M4 full level / Boss：5 个。

  • M4 grounding：4 个。

M4 full level 测试覆盖：

  • 三个世界观 LevelConfig。

  • 6-12 房间范围、首房和 Boss 终房。

  • LevelManager 开局、房间清理和推进。

  • 早期低 build 与后期高 build 的难度缩放差异。

  • Boss telegraph 和 activation 事件。

  • 暴露弱点被玩家攻击命中。

  • 弱点破坏推动 Boss phase。

  • 纯度极端时触发镜像 Boss。

这说明 M4 不是只生成场景资产，而是把关卡、Boss、镜像 Boss、难度、玩家修复和性能探针都纳入自动化验证。

已知风险和限制

M4 已完成玩法/系统闭环，但仍有明确限制：

  • 视觉资源仍是占位质量。Boss、房间、弱点提示和章节结束 UI 还不是最终美术。

  • 音频仍为占位或沿用 M3 placeholder，正式 BGM、Boss SFX、弱点破坏音效和混音留到后续阶段。

  • M4 是手工关卡原型，不验证程序生成质量；M5 才需要种子复现、非法路线防回归和房间原型库抽象。

  • Addressables-style 异步房间加载目前主要通过配置 key 和 scene-level room managers 表达，生产级 streaming 可以在 M5/M7 扩展。

  • 当前 probe 是 60s 工程验证，不等于完整发布前 soak。后续仍需要更长时段、更多场景和真实硬件覆盖。

这些限制不阻止 M4 验收，因为 M4 的目标是工程原型闭环，不是内容生产收口。

M5 方向

docs 仓库的 project/PROJECT_STATE.md 已将状态推进到 M4 完成、准备 M5。M5 的重点应该建立在 M4 的 LevelConfig / RoomConfig / DifficultyScaler 之上，而不是重做关卡框架。

M5 的合理方向：

  • 从 M4 的 27 个 RoomConfigSO 抽象房间原型库。

  • 引入 seed 生成，保证路线可复现。

  • 做强约束生成：Boss 终房、休息房位置、精英房间隔、商店/奖励频率、不可达路线防护。

  • 建立生成覆盖率和非法路线回归矩阵。

  • 将 M4 的 runtime probe 扩展到多 seed、多世界观和更长窗口。

M4 的阶段价值在这里：PROJECT-V 已经有一条从手工房间、难度缩放、Boss telegraph、弱点、镜像 Boss 到 runtime probe 的可验证关卡链路。M5 可以专注于“如何生成好路线”，而不是补 M4 应该完成的关卡基础设施。