diff --git a/GameConfig/README.md b/GameConfig/README.md index 3aa7b3a..403219e 100644 --- a/GameConfig/README.md +++ b/GameConfig/README.md @@ -37,6 +37,20 @@ marble_large,大弹珠,2.5,20,80,25 } ``` +## 弹珠小游戏配置（v0.2） + +| 文件 | 格式 | 用途 | 关键单位 | +|------|------|------|----------| +| `marble-types.csv` | CSV | 弹珠属性（玻璃/陶瓷/铁 + 目标弹珠 + 兜底弹珠） | radius_m（米）、mass（相对值）、frictionAdd/restitution（无量纲 0-1） | +| `marble-venues.csv` | CSV | 场地配置（水泥地/泥土地） | friction（无量纲） | +| `marble-npc.csv` | CSV | NPC 对手配置（死党B/小霸王） | angleError_deg（度）、powerError/basePower（%）、distComp（%/m） | +| `marble-config.json` | JSON | 画圈弹规则、操作、物理、库存、时序等键值参数 | 见各字段 unit | + +> CSV 列名后缀表示单位（`_m` 米、`_deg` 度、`_pct` 百分比、`_pctPerM` 每米百分比、`_mps` 米/秒、`_hz` 赫兹）。JSON 每个参数为 `{value, min, max, unit, note}` 对象，value 为建议值（程序导入用），min/max 为可调范围。 +> 来源：`docs/design/弹珠小游戏-执行案.md` v0.2.1。摩擦组合规则：最终摩擦 = 场地摩擦 + 弹珠摩擦加成。 + +--- + ## 工作流 1. 策划 Agent 创建/更新配置文件 diff --git a/GameConfig/marble-config.json b/GameConfig/marble-config.json new file mode 100644 index 0000000..f7444c0 --- /dev/null +++ b/GameConfig/marble-config.json @@ -0,0 +1,41 @@ +{ + "_meta": { + "doc": "弹珠小游戏配置（v0.2）", + "source": "弹珠小游戏-执行案.md v0.2.1", + "field_note": "value=建议值（程序导入用），min/max=可调范围（调参参考），unit=单位，note=说明" + }, + "circleRule": { + "circleRadius_m": { "value": 1.0, "min": 0.8, "max": 1.5, "unit": "m", "note": "弹出判定圈半径" }, + "targetCount": { "value": 5, "min": 3, "max": 8, "unit": "颗", "note": "圈中央目标弹珠数" }, + "popTolerance_m": { "value": 0.01, "min": 0.005, "max": 0.02, "unit": "m", "note": "弹出判定容差，统一带容差阈值" }, + "boundaryExpand_m": { "value": 0.5, "min": 0.3, "max": 1.0, "unit": "m", "note": "场地隐形反弹边界外扩" }, + "betMarbleCount": { "value": 1, "min": 1, "max": 3, "unit": "颗", "note": "胜负流转的对赌弹珠数" }, + "turnOrder": { "value": "player_first", "note": "v0.2 固定玩家先手" } + }, + "operation": { + "maxDragScreenRatio": { "value": 0.15, "min": 0.08, "max": 0.25, "unit": "屏幕高度占比", "note": "力度100%对应的拖拽距离，相对屏幕高度" }, + "minValidPower": { "value": 0.10, "min": 0.05, "max": 0.20, "unit": "比例", "note": "低于此松开视为取消" }, + "predictionLineLength_m": { "value": 3.0, "min": 2.0, "max": 5.0, "unit": "m", "note": "轨迹预测线最大显示长度" }, + "maxLaunchSpeed_mps": { "value": 8.0, "min": 5.0, "max": 12.0, "unit": "m/s", "note": "100%力度弹射初速度，对所有弹珠相同" }, + "shooterHighlightFreq_hz": { "value": 1.0, "min": 0.5, "max": 2.0, "unit": "Hz", "note": "PlayerAim 射手弹珠脉冲发光频率" } + }, + "physics": { + "stopSpeedThreshold_mps": { "value": 0.05, "min": 0.02, "max": 0.10, "unit": "m/s", "note": "判定弹珠停止的速度阈值" }, + "stableTime_s": { "value": 1.0, "min": 0.5, "max": 2.0, "unit": "秒", "note": "低于阈值持续至此判定停止" }, + "simulateTimeout_s": { "value": 15, "min": 10, "max": 30, "unit": "秒", "note": "物理结算超时强制停止" }, + "boundaryRestitution": { "value": 0.5, "min": 0.3, "max": 0.7, "unit": "系数", "note": "弹珠-场地边界反弹系数" }, + "frictionCombineRule": { "value": "venue_friction + marble_frictionAdd", "note": "最终摩擦=场地摩擦+弹珠摩擦加成" } + }, + "inventory": { + "initialCount": { "value": 5, "min": 3, "max": 10, "unit": "颗", "note": "玩家初始对战库存" }, + "guaranteeFloor": { "value": 3, "min": 2, "max": 5, "unit": "颗", "note": "保底下限，玩家败时库存不低于此" } + }, + "timing": { + "readyDuration_s": { "value": 0.8, "min": 0.5, "max": 1.2, "unit": "秒", "note": "进入就位表现（原位转向+蹲下）" }, + "enterCameraDuration_s": { "value": 0.6, "min": 0.4, "max": 1.0, "unit": "秒", "note": "第三人称→斜俯视相机切换" }, + "exitCameraDuration_s": { "value": 0.6, "min": 0.4, "max": 1.0, "unit": "秒", "note": "斜俯视→第三人称相机切换" }, + "standupDuration_s": { "value": 0.8, "min": 0.5, "max": 1.2, "unit": "秒", "note": "退出站起表现" }, + "resultDisplayDuration_s": { "value": 2.0, "min": 1.5, "max": 3.0, "unit": "秒", "note": "胜负结果显示时长" }, + "npcThinkDelay_s": { "value": 1.0, "min": 0.5, "max": 2.0, "unit": "秒", "note": "NPC 思考延迟" } + } +} diff --git a/GameConfig/marble-npc.csv b/GameConfig/marble-npc.csv new file mode 100644 index 0000000..183950a --- /dev/null +++ b/GameConfig/marble-npc.csv @@ -0,0 +1,3 @@ +id,displayName,angleError_deg,angleErrorMin_deg,angleErrorMax_deg,powerError_pct,powerErrorMin_pct,powerErrorMax_pct,basePower_pct,basePowerMin_pct,basePowerMax_pct,distComp_pctPerM,distCompMin_pctPerM,distCompMax_pctPerM,strategyNote,marbleType +friend_b,死党B（默认）,3,1,10,10,5,25,50,30,70,15,10,25,瞄准最近目标弹珠,glass +bully,小霸王（备选）,8,1,10,20,5,25,60,30,70,15,10,25,瞄准距圈边缘最近易弹出目标,iron diff --git a/GameConfig/marble-types.csv b/GameConfig/marble-types.csv new file mode 100644 index 0000000..bbb4a7c --- /dev/null +++ b/GameConfig/marble-types.csv @@ -0,0 +1,6 @@ +id,displayName,radius_m,radiusMin_m,radiusMax_m,mass,massMin,massMax,frictionAdd,frictionAddMin,frictionAddMax,restitution,restitutionMin,restitutionMax,strategyNote +glass,玻璃弹珠（标准）,0.015,0.01,0.02,1.0,0.8,1.2,0.0,0.0,0.2,0.5,0.4,0.7,滚得远走线精准远距主力 +ceramic,陶瓷弹珠（粗糙）,0.015,0.01,0.02,1.0,0.8,1.2,0.3,0.2,0.5,0.8,0.7,0.9,滚得近碰撞利落近距强撞 +iron,铁弹珠（重）,0.012,0.008,0.015,2.5,2.0,3.0,0.1,0.0,0.3,0.6,0.5,0.8,质量大撞散目标警惕贪力反噬 +target,目标弹珠（等同玻璃）,0.015,0.01,0.02,1.0,0.8,1.2,0.0,0.0,0.2,0.5,0.4,0.7,圈中央中立目标弹珠 +fallback,系统基础弹珠（等同玻璃）,0.015,0.01,0.02,1.0,0.8,1.2,0.0,0.0,0.2,0.5,0.4,0.7,库存异常兜底用 diff --git a/GameConfig/marble-venues.csv b/GameConfig/marble-venues.csv new file mode 100644 index 0000000..f6bc99d --- /dev/null +++ b/GameConfig/marble-venues.csv @@ -0,0 +1,3 @@ +id,displayName,friction,frictionMin,frictionMax,behaviorNote +concrete,水泥地,0.3,0.2,0.5,摩擦低滚动均匀距离远走线可预测适合精准操作 +dirt,泥土地,0.6,0.4,0.8,摩擦高减速快滚动距离明显短需更大力度到达圈心 diff --git a/docs/design/README.md b/docs/design/README.md index d637539..2a5a2f1 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -1,7 +1,7 @@ # docs/design/ — 策划文档索引 > 策划 Agent 的输出目录。所有玩法设计、系统机制、剧情叙事文档存放于此。 -> 最后更新：2026-06-08 +> 最后更新：2026-06-15 --- @@ -20,7 +20,7 @@ | [玩家控制器.md](玩家控制器.md) | 玩家角色控制——移动、摄像机、动画蓝图 | v0.1 ✅ | | [交互系统.md](交互系统.md) | 环境交互系统——交互组件、检测、UI 提示 | v0.1 ✅ | | [收集系统.md](收集系统.md) | 收集系统——拾取、进度追踪、图鉴（v0.1 基础版 → v0.4 完整版） | v0.1 ✅ v0.2+ 待补 | -| [小游戏系统.md](小游戏系统.md) | 小游戏体系——弹珠、拍洋画、四驱车等千禧年童年游戏 | v0.2 待补执行案 | +| [小游戏系统.md](小游戏系统.md) | 小游戏体系——弹珠、拍洋画、四驱车等千禧年童年游戏 | v0.2 弹珠执行案已产出 | | [叙事框架.md](叙事框架.md) | 叙事框架——暑假结构、事件设计、角色系统 | v0.3-v0.4 待补 | --- @@ -43,6 +43,8 @@ | [交互系统-执行案.md](交互系统-执行案.md) | 交互系统 | v0.1.2 | 📝 设计中 | | [收集系统-执行案.md](收集系统-执行案.md) | 收集系统 | v0.1.1 | 📝 设计中 | | [关卡-v01-城郊小街-执行案.md](关卡-v01-城郊小街-执行案.md) | 关卡（城郊小街白盒） | v0.1 | 📝 设计中 | +| [弹珠小游戏-执行案.md](弹珠小游戏-执行案.md) | 弹珠小游戏（v0.2 核心） | v0.2.1 | 📝 设计中 | +| [蹲下系统-执行案.md](蹲下系统-执行案.md) | 蹲下系统（玩家控制器扩展） | v0.2.0 | 📝 设计中 | --- @@ -51,6 +53,7 @@ | 文档 | 说明 | |------|------| | [v01-范围.md](v01-范围.md) | v0.1 功能边界、验收标准、开发优先级 | +| [v02-范围.md](v02-范围.md) | v0.2 功能边界、验收标准、开发优先级 | --- @@ -69,6 +72,7 @@ | [头脑风暴-2026-06-01-愿景支柱与世界观.md](头脑风暴-2026-06-01-愿景支柱与世界观.md) | 2026-06-01 | 愿景三大支柱 + 世界观确认 | | [头脑风暴-2026-06-04-时代与科技灵感.md](头脑风暴-2026-06-04-时代与科技灵感.md) | 2026-06-04 | 千禧年时代技术灵感（随身听、小霸王、街机等） | | [头脑风暴-2026-06-05-怀旧文化.md](头脑风暴-2026-06-05-怀旧文化.md) | 2026-06-05 | 千禧年怀旧文化灵感（电视剧、广播体操、广场舞等） | +| [头脑风暴-2026-06-15-弹珠操作手感与系统决策.md](头脑风暴-2026-06-15-弹珠操作手感与系统决策.md) | 2026-06-15 | v0.2 弹珠操作手感方案 + 系统决策 | --- diff --git a/docs/design/v02-范围.md b/docs/design/v02-范围.md new file mode 100644 index 0000000..c745f6f --- /dev/null +++ b/docs/design/v02-范围.md @@ -0,0 +1,166 @@ +# v0.2 范围定义 — 弹珠小游戏 + +> 本文档明确 v0.2 原型的功能边界，作为程序和美术的需求基准。 +> 最后更新：2026-06-15 + +--- + +## v0.2 目标 + +**验证核心问题**：弹珠小游戏的操作手感成立吗？策略深度够让人玩十几把不腻吗？ + +**体验目标**： +1. 弹弓式拖拽操作直觉流畅，方向与力度一步到位 +2. 三维策略（场地 × 弹珠属性 × 规则）让每局体验不同 +3. 蹲下探索增加场景的层次感 +4. 弹珠与收集系统联动，赢弹珠有获得感 + +**一句话**："在空地蹲下来，选一颗弹珠，和死党 B 来一局画圈弹。" + +--- + +## In Scope（v0.2 包含） + +### 弹珠小游戏（核心） +- [ ] 弹弓式拖拽操作（方向力度合一 + 轨迹预测线） +- [ ] 斜俯视视角（45° 俯瞰场地） +- [ ] 回合制对战（玩家 / NPC 轮流） +- [ ] 画圈弹规则（1 种） +- [ ] 2 种场地（水泥地 / 泥土地，摩擦差异） +- [ ] 3 种弹珠属性（玻璃 / 陶瓷 / 铁） +- [ ] 弹珠物理表现（摩擦 / 碰撞 / 停止判定） +- [ ] 1 个 NPC 对手（死党 B）+ 弹射 AI +- [ ] 对战库存管理（初始 5 颗） +- [ ] 保底机制（库存不低于 3 颗） +- [ ] 胜负判定与弹珠流转 + +### 蹲下系统 +- [ ] C 键切换站 / 蹲姿态 +- [ ] 蹲伏移动（2.0 m/s） +- [ ] 蹲伏有效高度（1.0m，可钻低矮空间） +- [ ] 蹲伏视角降低 +- [ ] 弹珠入场由系统强制蹲下 + +### 收集系统扩展 +- [ ] 弹珠作为收集品（稀有花色弹珠进图鉴的通知链路打通） +- [ ] 对战库存 / 收藏图鉴分离 + +### NPC +- [ ] 1 个 NPC 对手静态站位（死党 B） +- [ ] 弹射 AI 决策（瞄准 + 力度估算 + 准度偏差） + +### 场景 +- [ ] 空地弹珠场地（2 个：水泥地 + 泥土地） +- [ ] 弹珠场地标识（圈 / 大树下区域标记） +- [ ] 低矮空间（供蹲下探索，如桌下 / 矮洞） + +### 视觉 +- [ ] 弹珠用颜色区分属性（白盒阶段） +- [ ] 弹珠场地白盒表现（圈、起点、目标弹珠） + +--- + +## Out of Scope（v0.2 不包含） + +### 明确排除 +- ❌ 多规则（打坑 / 靠墙 / 斜坡）→ v0.3+ +- ❌ 手法系统（拇指法 / OK 法）→ v0.3+ +- ❌ 手柄操作 → 后续版本 +- ❌ 收藏图鉴完整 UI → v0.4（收集系统完整版） +- ❌ 多 NPC 对手切换 → v0.2 固定 1 个对手 +- ❌ NPC 日常 AI / 移动 / 对话树 → v0.3 +- ❌ 拍洋画 / 四驱车 / FC 街机等其他小游戏 → 后续版本 +- ❌ 弹珠花色外观美术差异 → v0.2 白盒，用颜色区分 +- ❌ 玩家投入稀有弹珠对战 → v0.3+ +- ❌ 回合数上限 / 主动认输 → v0.2 弹完即结束 +- ❌ 音效（弹射 / 碰撞 / 结算）→ v0.3 +- ❌ 蹲下静音 / 潜行机制 → v0.3+ +- ❌ 匍匐 / 滑铲 → 后续版本 +- ❌ 时间循环系统 → v0.3 +- ❌ 经济系统（零花钱）→ v0.4 +- ❌ 存档 / 读档 → 后续版本 + +--- + +## 验收标准 + +### 操作手感 +- [ ] 弹弓式拖拽的方向与力度直观，松手弹射符合预期 +- [ ] 轨迹预测线清晰，玩家能据此预判弹珠路径 +- [ ] 连续玩 5 把以上不觉得操作别扭 + +### 策略深度 +- [ ] 不同弹珠属性（玻璃 / 陶瓷 / 铁）在游戏中能感知到差异 +- [ ] 水泥地 vs 泥土地表现明显不同，需要调整策略 +- [ ] 玩家想主动尝试不同弹珠 / 场地组合 + +### 物理表现 +- [ ] 弹珠滚动、碰撞、停止的表现合理 +- [ ] 不同场地的摩擦差异可感知 + +### 蹲下体验 +- [ ] C 键切换蹲 / 站过渡自然 +- [ ] 蹲伏移动速度降低、视角降低 +- [ ] 蹲下能钻过低矮空间，发现站立时进不去的区域 + +### 收集联动 +- [ ] 赢弹珠增加对战库存，输弹珠减少（有保底不归零） +- [ ] 稀有弹珠进入收藏图鉴（通知链路打通） + +### NPC 对战 +- [ ] 死党 B 作为对手能正常弹射，体现准度差异 +- [ ] NPC 弹射决策合理（瞄准目标弹珠、估算力度） + +### 可重复性（主观） +- [ ] 连续玩十几把不觉得无聊 +- [ ] 整体体验让人觉得弹珠小游戏"好玩"——游戏三大支柱之一成立 + +--- + +## 与 v0.3 的衔接点 + +v0.2 完成后，v0.3 将在以下基础上扩展： + +1. **时间循环系统**：四时段（上午 / 下午 / 傍晚 / 夜晚）推进 + 光影联动 +2. **NPC 日常 AI**：从静态站位升级为按时段移动、有自己的生活 +3. **对话系统**：NPC 从"弹珠对手"升级为可交谈（v0.2 仅有弹射交互） +4. **多规则弹珠**：在画圈弹基础上增加打坑 / 靠墙 / 斜坡 +5. **音效**：弹射 / 碰撞 / 环境音 / 时段过渡音 + +--- + +## 开发优先级（供程序 Agent 参考） + +1. **P0 — 弹珠操作手感 Throwaway 原型**（2-3 天）：先用最简实现验证弹弓式拖拽 + 物理参数的可行性，**验证不通过则调整方案**（路线图标注的最大风险，必须前置） +2. **P0 — 弹珠物理系统 + 画圈弹规则**：摩擦 / 碰撞 / 停止判定 / 弹出判定 +3. **P0 — 弹弓式操作完整流程 + 斜俯视视角 + 状态机**：弹珠小游戏核心框架 +4. **P1 — 三维策略数据**：规则 / 场地 / 弹珠属性配置 +5. **P1 — NPC 对手 + 弹射 AI**：死党 B 的弹射决策 +6. **P1 — 对战库存 + 保底 + 收集联动** +7. **P1 — 蹲下系统**：玩家控制器姿态扩展 +8. **P2 — 场地差异调优 + 场景扩展 + 参数打磨** + +--- + +## 预估工作量（粗略） + +| 模块 | 预估 | 说明 | +|------|------|------| +| 弹珠操作手感原型 | 2-3 天 | Throwaway，验证操作方案（风险前置） | +| 弹珠物理系统 | 3-5 天 | 摩擦 / 碰撞 / 参数调优 | +| 弹弓操作 + 斜俯视 + 状态机 | 3-5 天 | 弹珠小游戏核心框架 | +| 三维策略数据 | 2-3 天 | 规则 / 场地 / 弹珠属性配置 | +| NPC 对手 + AI | 3-4 天 | 死党 B 弹射决策 | +| 蹲下系统 | 1-2 天 | 玩家控制器姿态扩展 | +| 对战库存 + 保底 + 收集联动 | 2-3 天 | | +| 场地 + 场景扩展 | 1-2 天 | 空地弹珠场地 + 低矮空间 | +| 调试打磨 | 3-5 天 | 含物理调参 | +| **合计** | **18-28 天** | 与路线图一致 | + +--- + +## 关键风险 + +1. **操作手感**（已通过头脑风暴化解方向）：弹弓式拖拽方案已明确（见 `头脑风暴-2026-06-15-弹珠操作手感与系统决策.md`），但仍需 Throwaway 原型验证物理参数的实际手感 +2. **弹珠物理对微小物体数值敏感**（弹珠半径约 0.015m）：摩擦 / 碰撞参数需反复调参 +3. **轨迹预测线与实际物理的一致性**：预测线不显示碰撞后路径，需让玩家理解预测线只反映直线路径 diff --git a/docs/design/头脑风暴-2026-06-15-弹珠操作手感与系统决策.md b/docs/design/头脑风暴-2026-06-15-弹珠操作手感与系统决策.md new file mode 100644 index 0000000..c3d75bc --- /dev/null +++ b/docs/design/头脑风暴-2026-06-15-弹珠操作手感与系统决策.md @@ -0,0 +1,154 @@ +# 头脑风暴 — 2026-06-15 — 弹珠操作手感与系统决策 + +> v0.2 弹珠小游戏设计的方向确认会议。 +> 参与者：用户（starmen1265）+ 策划 Agent +> 状态：核心共识已确认 ✅，作为弹珠执行案的起草基准 + +--- + +## 背景 + +v0.1 策划设计已收口，启动 v0.2 设计准备。v0.2 核心是**弹珠小游戏**，验证假设： + +> 弹珠四维策略系统（规则 × 场地 × 弹珠 × 手法）操作手感成立吗？策略深度够让人玩十几把不腻吗？ + +路线图标注的**最大风险**：操作手感。必须先验证操作方案，验证不通过可能增加 5-10 天。 + +**本次头脑风暴目标**：在起草弹珠执行案前，确认操作手感方案和关键系统决策，化解核心风险。 + +--- + +## 共识 1：操作取向 — 简化上手，策略为主 + +**决策**：操作简化易上手，重复可玩性来自四维策略组合（换弹珠/场地/规则/手法）。 + +**理由**： +- 符合"十几把不腻靠策略而非操作精度"的设计意图 +- 降低开发风险（操作方案验证更容易通过） +- 弹珠属性差异（大小/材质）已提供足够策略变化空间 + +**否决的备选**： +- 手感至上偏写实（类似台球/高尔夫拟真手感）— 学习曲线陡，验证风险最高 +- 折中（易上手 + 进阶深度）— 设计与实现复杂度最高 + +--- + +## 共识 2：摄像机视角 — 斜俯视 + +**决策**：45° 斜俯视，俯瞰整个弹珠场地。 + +**理由**： +- 能看到全局（场地、弹珠、规则标记如圈/坑），瞄准与轨迹直观 +- 最契合"简化上手" +- 场景美术保持真实感（千禧年空地、泥地），仅相机抬高方便操作（呼应系统设计"真实感在视觉，玩法不必完全拟真"） + +**代价**：略损失"小孩蹲着弹"的代入感（可接受，美术真实感弥补）。 + +--- + +## 共识 3：操作模式 — 回合制 + +**决策**：玩家与 NPC 轮流弹，每人一回合。 + +**理由**： +- 节奏清晰，策略思考空间大 +- 契合 v0.2 唯一规则"画圈弹"（轮流把对方弹珠弹出圈） + +--- + +## 共识 4：瞄准 + 力度操作 — 弹弓式拖拽（核心） + +**决策**：鼠标按住自己弹珠，往反方向拖拽。 + +``` +拖拽方向 = 弹射方向（反向） +拖拽距离 = 力度 +实时显示轨迹预测线（虚线弧） +松开鼠标 = 弹珠按预测轨迹弹出 +``` + +**理由**： +- 一步到位完成瞄准 + 力度，最直觉（愤怒小鸟/弹珠台经典交互） +- 轨迹预测线让策略完全可预期，降低操作不确定性 +- 方向力度合一，操作极简 + +**操作循环（玩家回合）**： +1. 鼠标悬停自己的弹珠 → 显示可拖拽提示 +2. 按住 + 反向拖拽 → 实时更新轨迹预测线 + 力度指示（百分比） +3. 松开 → 弹珠弹射，物理模拟结算 +4. 结算完成 → 进入 NPC 回合 + +--- + +## 共识 5：输入设备 — 键鼠为主 + +**决策**：键鼠为主，手柄作为后续加分项（v0.2 不强求）。 + +**理由**：PC 单人独立开发，键鼠是合理默认。 + +--- + +## 共识 6：手法维度 — v0.2 不做 + +**决策**：v0.2 不实现"手法"（大拇指扣打法 / OK 手弹法）差异。手法作为四维策略之一，留后续版本。 + +**理由**： +- 弹珠属性（大小/材质）已提供足够策略变化 +- 手法仅 2 种且差异小，v0.2 聚焦验证基础手感 +- 避免范围蔓延（每个版本验证一个核心假设） + +**影响**：四维策略在 v0.2 实际降为三维（规则 × 场地 × 弹珠属性），手法维度在执行案中标注为"v0.3+ 预留"。 + +--- + +## 共识 7：弹珠库存 / 图鉴分离 + +**决策**：弹珠分两层管理： +- **对战库存**：普通弹珠，参与对赌输赢，有保底机制 +- **收藏图鉴**：稀有花色弹珠，拾取即永久拥有，不参与输赢 + +**理由**： +- 避免"辛苦收集的稀有弹珠在对战中输掉"的糟糕体验 +- 对战库存的输赢不影响收集成就 + +**影响保底机制**：保底针对"对战库存"（不会输到无法继续玩）。 + +--- + +## 推论：保底机制（待执行案细化数值） + +基于共识 7，保底机制：玩家对战库存不低于某下限（建议 3 颗），低于则不再输弹珠（或获得基础补给）。具体数值在执行案给建议范围（标注"可调"）。 + +--- + +## 路线图既定项（本次未讨论，直接沿用） + +- **规则范围**：v0.2 只做"画圈弹"1 种规则 +- **NPC**：静态站位 + 简单 AI 决策作为弹珠对手（取死党 B 或小霸王） +- **场地**：v0.2 做 1-2 种场地（水泥地 + 泥土地） +- **蹲下系统**：角色控制器扩展（另出执行案） + +--- + +## 待弹珠执行案细化的设计点（不需用户预先拍板，执行案给方案 + 建议值） + +- 物理参数范围（弹珠半径、质量、摩擦、反弹系数） +- 三维策略 DataAsset 结构（规则/场地/弹珠属性的配置字段） +- NPC AI 决策规则（如何选规则/场地、弹射决策） +- 保底机制具体数值 +- "画圈弹"规则的具体判定（圈大小、弹出判定、回合上限） +- 局流程与胜负判定（一局的开始 → 进行 → 结算 → 退出） +- 进入/退出小游戏的流程（场景探索 → 弹珠小游戏的视角/状态切换） +- 跨系统交互（收集系统、交互系统、玩家控制器蹲下） + +--- + +## 下一步 + +1. 落盘本共识（本文档）✅ +2. 加载 `design-execution` 技能，了解执行案规范 +3. 起草 `弹珠小游戏-执行案.md`（含上述设计点的完整方案 + 建议值） +4. 同步产出配置表（弹珠属性 / 场地 / 规则参数） +5. 起草 `蹲下系统-执行案.md`（玩家控制器扩展） +6. 产出 `v02-范围.md`（版本边界汇总） +7. 质量门审查 diff --git a/docs/design/弹珠小游戏-执行案.md b/docs/design/弹珠小游戏-执行案.md new file mode 100644 index 0000000..fbe28f2 --- /dev/null +++ b/docs/design/弹珠小游戏-执行案.md @@ -0,0 +1,532 @@ +# 弹珠小游戏执行案（v0.2 原型） + +## 迭代记录 + +| 迭代版本 | 修改日期 | 状态 | 说明 | +|----------|----------|------|------| +| v0.2.0 | 2026-06-15 | 📝 设计中 | 初版执行案，覆盖画圈弹规则、弹弓式操作、NPC对手、对战库存保底的完整行为规则。基于头脑风暴-2026-06-15 共识 | +| v0.2.1 | 2026-06-15 | 📝 设计中 | 对抗性审查修订（25 项确认问题）：补全物理参数语义（摩擦组合规则、弹射初速度、目标弹珠属性、碰撞恢复系数）；泥土地去随机偏差改确定性差异；陶瓷补碰撞传递优势并加策略矩阵；统一平局/容差/射手弹出代价逻辑；明确 Interacting 内不位移；量化 NPC 力度参数；修正稀有弹珠归类与术语；新增平衡性验收标准 | + +> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步 + +--- + +## 系统概述 + +弹珠小游戏是 v0.2 的核心，验证游戏三大支柱之一"好玩"是否成立。 + +**验证假设**：弹珠小游戏的操作手感成立吗？策略深度够让人玩十几把不腻吗？ + +**体验目标**：操作手感直觉流畅，策略深度来自弹珠属性选择与场地差异的组合，而非操作精度。 + +**v0.2 范围**：1 种规则（画圈弹）、2 种场地（水泥地 / 泥土地）、3 种弹珠属性（玻璃 / 陶瓷 / 铁）、1 个 NPC 对手、与对战库存联动。 + +### 核心设计决定（基于头脑风暴共识，已确认） + +1. **简化上手，策略为主** — 力度与方向用弹弓式拖拽一步完成，重复可玩性来自策略组合，不靠操作精度 +2. **斜俯视视角** — 45° 俯瞰场地，全局可见，瞄准直观 +3. **回合制** — 玩家与 NPC 轮流弹射 +4. **弹弓式拖拽操作** — 按住弹珠反向拖拽，方向与力度合一，配轨迹预测线 +5. **键鼠为主** — 手柄 v0.2 不做 +6. **手法维度 v0.2 不做** — 头脑风暴原定的四维策略在 v0.2 降为"弹珠属性选择 + 场地差异"两个玩家可感知维度，手法（拇指法 / OK 法）留 v0.3+ +7. **库存 / 进度追踪分离** — 对战库存（输赢流转）与收集系统进度追踪（永久记录）分开管理 + +--- + +## 系统边界 + +| 弹珠小游戏负责 | 弹珠小游戏不负责 | +|----------------|------------------| +| 弹珠小游戏的进入 / 退出流程 | 弹珠场地的场景美术搭建（关卡） | +| 弹弓式操作的交互与反馈 | 弹珠作为收集品的进度展示（收集系统） | +| 画圈弹规则判定与物理结算 | NPC 的日常行为 AI（v0.3） | +| NPC 对手的弹射决策 | 多规则 / 多场地的扩展（v0.2 仅 1 规则 2 场地） | +| 对战库存的输赢流转与保底 | 手法系统（v0.3+） | +| 胜负判定与奖励结算 | 拍洋画、四驱车、FC 家用机、街机厅、包机房等其他小游戏品类（详见 `小游戏系统.md` 品类架构） | + +--- + +## 进入与退出（与交互系统衔接） + +弹珠小游戏作为交互系统的 **SubSystem**（交互系统执行案 v0.1 已预留该状态与 `postAction: minigame` 分叉）。 + +> **关键约束**：交互系统的 Interacting 状态规定"所有移动输入被忽略，角色不移动"。因此弹珠小游戏的进入流程**不依赖 Interacting 状态内的角色位移**——玩家触发交互时必须已站在场地边缘的触发范围内，进入流程只做转向 + 蹲下表现，不发生位移。 + +### 进入流程 + +| 步骤 | 行为 | +|------|------| +| 1 | 玩家在空地弹珠场地附近自由走动 | +| 2 | 玩家**自行走动**到弹珠场地边缘的触发范围内（交互系统的触发半径覆盖场地边缘就位点） | +| 3 | 交互系统显示提示 `[E] 来一局弹珠` | +| 4 | 玩家按 E → 触发"弹珠场地"交互，进入 Interacting 状态 | +| 5 | 角色原位转向场地并蹲下（就位表现，时长 0.8 秒，建议值，可调，范围 0.5-1.2 秒）。**角色不发生位移**，仅在原地完成转向 + 下蹲 | +| 6 | 交互结束，postAction 为 minigame → 角色进入 SubSystem 状态 | +| 7 | 进入过渡：相机从第三人称平滑切换到斜俯视（俯瞰场地），切换时长 0.6 秒（建议值，可调，范围 0.4-1.0 秒） | +| 8 | 显示弹珠场地全貌：圈、中立目标弹珠、玩家射手弹珠、NPC 射手弹珠 | +| 9 | 进入 MatchInit（局准备）状态 | + +### 退出流程 + +| 步骤 | 行为 | +|------|------| +| 1 | MatchEnd 结算完成，玩家确认 → 相机从斜俯视切回第三人称，切换时长 0.6 秒（建议值，可调，范围 0.4-1.0 秒） | +| 2 | 角色原位站起（站起表现时长 0.8 秒，建议值，可调，范围 0.5-1.2 秒） | +| 3 | 弹珠小游戏 SubSystem 退出 → 回到交互系统 Free 状态，玩家恢复自由移动 | +| 4 | 玩家可再次走近场地交互，开启新一局 | + +--- + +## 状态定义 + +弹珠小游戏内部状态机（在交互系统 SubSystem 顶层状态之下）： + +| 状态 | 说明 | +|------|------| +| MatchInit | 局准备：生成场地弹珠，玩家选择射手弹珠 | +| PlayerAim | 玩家瞄准：等待玩家按住射手弹珠开始拖拽 | +| PlayerCharge | 玩家蓄力：拖拽中，实时更新方向 / 力度 / 预测线 | +| Simulating | 物理结算：弹珠运动中，等待全部停止 | +| NpcThink | NPC 思考：短暂延迟后 NPC 决策并弹射 | +| RoundEnd | 回合结算：判定弹出弹珠，更新射手弹珠位置 | +| MatchEnd | 局结束：胜负判定、弹珠流转、显示结果 | + +### 状态转换 + +``` +MatchInit ──(玩家选好射手弹珠 + 按空格)──→ PlayerAim（玩家先手） +PlayerAim ──(按住射手弹珠)──→ PlayerCharge +PlayerCharge ──(松开 + 力度 ≥ 最小有效值)──→ Simulating +PlayerCharge ──(松开 + 力度 < 最小有效值 或 按 ESC / 右键)──→ PlayerAim +Simulating ──(所有弹珠停止)──→ RoundEnd +RoundEnd ──(圈内仍有目标弹珠)──→ 切换回合：下一方 PlayerAim 或 NpcThink +RoundEnd ──(圈内目标弹珠全部弹出)──→ MatchEnd +NpcThink ──(思考延迟结束 + NPC 弹射)──→ Simulating +MatchEnd ──(结算完成 + 玩家确认)──→ 退出流程 +``` + +**回合顺序**：v0.2 固定玩家先手。每局均由玩家先弹。 + +--- + +## 行为规则 + +### 一、局准备（MatchInit） + +**触发**：进入弹珠小游戏 SubSystem、相机过渡完成后。 + +**表现**： +- 圈中央生成 5 颗中立目标弹珠（建议值，可调，范围 3-8 颗），按紧凑圆形排列于圈心周围。目标弹珠的物理属性等同于"玻璃弹珠（标准）"（见"弹珠物理属性"） +- 玩家射手弹珠生成于圈外"玩家起点"位置 +- NPC 射手弹珠生成于圈外"NPC 起点位置"（与玩家起点关于圈心对称，位于圈的对侧） +- 屏幕显示"选择你的射手弹珠"界面：列出玩家对战库存中所有弹珠，标注每颗的属性（玻璃 / 陶瓷 / 铁）与一句话策略定位 +- 玩家点选一颗 → 该弹珠属性应用到场上玩家射手弹珠，界面收起 +- 显示提示 `按 空格 开始` + +**结束条件**：玩家按空格 → 进入 PlayerAim。 + +**边界**：玩家对战库存因保底机制保证 ≥ 3 颗，始终能选择射手弹珠。若因异常库存为空，强制使用系统基础弹珠（属性等同于"玻璃弹珠（标准）"），不阻断游戏。 + +--- + +### 二、玩家瞄准（PlayerAim） + +**触发**：从 MatchInit 或 RoundEnd（轮到玩家）进入。 + +**表现**： +- 玩家射手弹珠高亮（脉冲发光，频率 1Hz，建议值，可调，范围 0.5-2Hz） +- 鼠标悬停射手弹珠 → 鼠标显示"可拖拽"提示光标 +- 屏幕底部显示操作提示：`按住弹珠拖拽瞄准　ESC 放弃本局` + +**结束条件**： +- 玩家在射手弹珠上按下鼠标左键 → 进入 PlayerCharge +- 玩家按 ESC → 弹出确认"放弃本局？将判负" → 确认则按"玩家放弃"处理进入 MatchEnd（见 MatchEnd 弹珠流转），取消则留在 PlayerAim + +**边界**：此状态无超时，玩家可无限思考。Simulating / PlayerCharge 中按 ESC 无效（操作不可中断）。 + +--- + +### 三、玩家蓄力（PlayerCharge）— 弹弓式拖拽核心 + +**触发**：PlayerAim 中玩家按住射手弹珠（鼠标左键按下）。 + +**表现**： +- 锁定瞄准原点为射手弹珠当前位置 +- 显示力度指示器（射手弹珠旁，0%-100%） +- 显示轨迹预测线：从射手弹珠沿"拖拽反方向"延伸的虚线弧，长度按力度比例（最长显示 3m 路径，建议值，可调，范围 2-5m） + +**拖拽规则**： +- **弹射方向** = 射手弹珠 → 鼠标当前位置 的反方向（鼠标向左下拖，弹珠向右上飞） +- **力度** = 拖拽距离的线性映射：拖拽距离 0 → 力度 0%；拖拽距离达到最大值 → 力度 100% +- **最大拖拽距离**：以屏幕高度的百分比衡量，拖拽距离达到屏幕高度的 15%（建议值，可调，范围 8%-25%）时力度为 100%。使用屏幕高度百分比保证不同分辨率下手感一致 +- 鼠标移动时，方向 / 力度 / 预测线实时刷新，无延迟 + +**轨迹预测线规则**： +- 预测线反映弹珠弹出后的直线路径，考虑场地摩擦导致的减速（预测线随摩擦大小呈现不同长度与弧度） +- 预测线**不显示碰撞后的路径变化**（碰撞后路径不可预测） +- 预测线长度随力度增加而延长，达到最大显示长度后封顶 +- 预测线在所有场地都如实反映摩擦差异（见"场地"章节），泥土地的预测线因高摩擦而明显更短 + +**取消蓄力**： +- 玩家按 ESC 或鼠标右键 → 回到 PlayerAim（不消耗回合） +- 玩家松开鼠标左键 且 力度 < 最小有效值（建议 10%，可调，范围 5%-20%）→ 视为取消，回到 PlayerAim + +**结束条件（确认弹射）**： +- 玩家松开鼠标左键 且 力度 ≥ 最小有效值 → 进入 Simulating，弹珠按当前方向与力度弹射，预测线消失 + +**边界**： +- 拖拽距离超过最大值时，力度封顶 100%，预测线不再延长 +- 鼠标拖至屏幕边缘，方向与力度按实际拖拽向量计算（拖拽距离仍以屏幕高度百分比为基准） + +--- + +### 四、物理结算（Simulating） + +**触发**：玩家或 NPC 弹射后。 + +**表现**： +- 弹射手弹珠按弹射方向与初速度开始物理运动。初速度 = 力度百分比 × 最大弹射初速度（见"可调参数"）。初速度对所有弹珠相同，弹珠属性差异体现在后续的滚动（摩擦）与碰撞（质量、恢复系数）阶段 +- 预测线在弹射瞬间消失 + +**运动规则**： +- **摩擦减速**：弹珠受摩擦持续减速，摩擦数值越大减速越快。最终摩擦 = 场地摩擦 + 弹珠摩擦加成（见"场地"与"弹珠物理属性"） +- **弹珠碰撞**：弹珠碰撞其他弹珠时按物理规律传递动量，产生反弹与位移。碰撞中目标弹珠被弹飞的程度取决于射手弹珠的碰撞恢复系数（陶瓷高，传递能量多） +- **场地边界反弹**：弹珠碰撞场地隐形边界时反弹，反弹程度由反弹系数决定（见"可调参数"） +- **目标弹珠与射手弹珠一视同仁参与碰撞**：停在圈内的射手弹珠作为物理实体，会与目标弹珠和对方射手弹珠发生碰撞 + +**结束条件**： +- 场上所有运动弹珠的速度低于停止阈值（建议 0.05m/s，可调，范围 0.02-0.1m/s）且持续稳定时间 1 秒（建议值，可调，范围 0.5-2 秒）→ 判定全部停止，进入 RoundEnd +- **超时保护**：物理结算超过 15 秒（建议值，可调，范围 10-30 秒）仍有弹珠未停止 → 强制停止所有弹珠，进入 RoundEnd + +--- + +### 五、回合结算（RoundEnd） + +**触发**：Simulating 结束（全部弹珠停止）。 + +**结算内容**： + +| 结算项 | 规则 | +|--------|------| +| 弹出判定 | 逐颗检查目标弹珠位置。弹珠中心点到圈心距离 > 圈半径 + 弹出判定容差 → 判定为"被弹出"。**弹出判定始终使用带容差的阈值**（与边界情况"弹珠停在圈边界"一致） | +| 弹出归属 | 被弹出的目标弹珠归本回合弹射方所有，计入本局收获 | +| 射手弹珠位置（停在圈内） | 保持当前位置，下一回合从该位置继续弹射。停在圈内的射手弹珠作为物理障碍有双向影响：既可能阻挡对方弹珠（防守收益），也可能挡住自己的后续弹道（位置风险）——这是策略的一部分 | +| 射手弹珠位置（弹出圈外） | **贪力反噬**：本回合该方弹出的目标弹珠全部作废（不计入本局收获），射手弹珠放回圈外该方起点位置。此规则防止"大力清场而无代价"的漏洞 | +| 收获记录 | 本回合实际计入的收获 = 弹出的目标弹珠数（若触发贪力反噬则为 0） | + +**结束条件**： +- 圈内仍有目标弹珠 → 切换回合：刚才是玩家回合 → NpcThink；刚才是 NPC 回合 → PlayerAim +- 圈内目标弹珠全部被弹出（剩余 0 颗）→ 进入 MatchEnd + +--- + +### 六、NPC 回合（NpcThink） + +**触发**：RoundEnd 后轮到 NPC。 + +**表现**： +- NPC 射手弹珠高亮 +- NPC"思考"延迟 1.0 秒（建议值，可调，范围 0.5-2.0 秒），期间无操作（模拟思考） +- 思考结束后，NPC 按决策规则自动弹射 → 进入 Simulating + +**NPC 决策规则**： +1. 按策略倾向选择目标弹珠（死党 B：选距离 NPC 射手弹珠最近的目标弹珠） +2. 计算瞄准方向（NPC 射手弹珠 → 目标弹珠） +3. 按距离估算力度：力度 = 基础力度 + 距离补偿系数 × 距离。基础力度 50%（建议值，可调，范围 30%-70%），距离补偿系数每米 +15%（建议值，可调，范围 10%-25%/m）。估算结果截断在 0%-100% +4. 加入准度偏差与力度误差（取自 NPC 属性配置，死党 B：角度偏差 ±3°、力度误差 ±10%，详见"NPC 对手"章节） +5. 弹射，进入 Simulating + +NPC 的射手弹珠属性同样影响物理表现（死党 B 用玻璃弹珠标准属性）。 + +--- + +### 七、局结束与结算（MatchEnd） + +**触发**：RoundEnd 判定圈内目标弹珠全部弹出，或玩家放弃本局。 + +**结算内容**： + +| 步骤 | 规则 | +|------|------| +| 1. 胜负判定 | 比较双方本局实际收获的目标弹珠数。玩家 > NPC → 玩家胜；玩家 < NPC → NPC 胜；玩家 = NPC → 由本局最后弹出目标弹珠的一方胜（"最后弹出方"由状态机记录的最近一次 Simulating 触发方唯一确定，不存在无法判定的情形） | +| 2. 玩家放弃的特殊处理 | 若本局因玩家按 ESC 放弃而结束 → 跳过收获比较，直接判定为玩家败。玩家放弃前已收获的目标弹珠全部作废（不计入收集、不参与流转） | +| 3. 弹珠流转（玩家胜） | 玩家对战库存 +对赌弹珠数（从 NPC 处赢得） | +| 4. 弹珠流转（玩家败） | 触发保底：当前库存 > 保底下限 → 库存 -对赌弹珠数；当前库存 ≤ 保底下限 → 库存不变（仅本局不计收获） | +| 5. 稀有弹珠奖励 | 若本局实际收获中包含稀有弹珠，通知物品系统（见"跨系统交互"），计入收集系统进度 | +| 6. 结果显示 | 屏幕中央显示结果 2.0 秒（建议值，可调，范围 1.5-3.0 秒） | + +**结果显示文本**： +- 胜：`你赢了！获得 1 颗弹珠` +- 败（正常扣减）：`你输了…失去 1 颗弹珠` +- 败（触发保底）：`你输了…好在没失去弹珠` +- 玩家放弃：`你放弃了这局` + +**结束条件**：结果显示后玩家按空格 / E 确认 → 进入退出流程。 + +> **设计说明**：v0.2 采用"恒有胜负"（收获相等时由最后弹出方决胜），不设真实平局终态。理由：画圈弹弹完全部目标弹珠时，必然存在最后弹出一颗的一方，状态机可唯一确定，无需平局分支。 + +--- + +## 画圈弹规则配置 + +| 配置项 | 建议值 | 可调范围 | 说明 | +|--------|--------|----------|------| +| 圈半径 | 1.0m | 0.8-1.5m | 弹珠被弹出圈的判定边界 | +| 目标弹珠数 | 5 颗 | 3-8 颗 | 圈中央初始放置 | +| 目标弹珠排列 | 紧凑圆形 | — | 圈心周围小范围 | +| 对赌弹珠数 | 1 颗 | 1-3 颗 | 胜负结算时的流转单位 | +| 回合顺序 | 玩家先手 | — | v0.2 固定 | +| 弹出判定容差 | 0.01m | 0.005-0.02m | 圈边界判定容差，避免抖动误判。**所有弹出判定统一使用 圈半径 + 容差 阈值** | +| 场地边界外扩 | 0.5m | 0.3-1.0m | 场地周围隐形反弹边界 | + +--- + +## 三维策略系统（v0.2 实现） + +> **如实说明**：v0.2 中玩家可感知的策略维度有两个——**弹珠属性选择**（玩家在 MatchInit 选射手弹珠）与**场地差异**（玩家进入哪个场地就用哪个场地的物理参数）。原四维策略中的"规则"维度 v0.2 冻结（仅画圈弹，无选择空间），"手法"维度 v0.2 不做，二者作为系统结构预留，待 v0.3+ 增加内容后激活。本章节沿用"三维策略系统"标题指代系统结构上的三个配置维度（规则 / 场地 / 弹珠属性），但明确 v0.2 玩家策略实际来自弹珠属性与场地两个维度。 + +### 维度一：规则（v0.2 冻结） + +v0.2 仅"画圈弹"一种规则，NPC 无规则选择空间，玩家也无规则选择。此维度在 v0.2 不产生策略变化，结构上预留，v0.3+ 增加规则类型后激活。 + +### 维度二：场地 + +v0.2 提供 2 种场地，通过**确定性的摩擦差异**影响弹珠滚动表现（不使用随机偏差，保证预测线如实反映场地特性）。场地由关卡决定（v0.2 空地有 2 个弹珠场地，分别使用水泥地与泥土地参数）。 + +| 场地 | 场地摩擦（建议值） | 可调范围 | 滚动表现 | 策略影响 | +|------|---------------------|----------|----------|----------| +| 水泥地 | 0.3 | 0.2-0.5 | 摩擦低，弹珠滚动均匀、距离远、走线可预测 | 适合远距离精准操作，玻璃弹珠的射程优势充分发挥 | +| 泥土地 | 0.6 | 0.4-0.8 | 摩擦高，弹珠减速更快、滚动距离明显更短，需要更大力度才能到达圈心 | 玻璃弹珠射程被压缩，需贴近距离；陶瓷的碰撞优势更易发挥 | + +**摩擦组合规则**：弹珠在场地上的最终摩擦 = 场地摩擦 + 弹珠摩擦加成。摩擦数值越大，弹珠减速越快、滚动距离越短。具体衰减计算由技术方案定义，本执行案只定义摩擦的语义、组合规则与数值。 + +### 维度三：弹珠属性（玩家选择） + +玩家在 MatchInit 选择射手弹珠，不同属性影响物理表现。v0.2 提供 3 种基础属性组合。**目标弹珠统一使用"玻璃弹珠（标准）"属性**。 + +| 弹珠类型 | 半径（建议值） | 质量（相对值） | 摩擦加成 | 碰撞恢复系数 | 策略定位 | +|----------|----------------|----------------|----------|--------------|----------| +| 玻璃弹珠（标准） | 0.015m（可调，范围 0.01-0.02m） | 1.0（可调，范围 0.8-1.2） | 0.0（可调，范围 0.0-0.2） | 0.5（可调，范围 0.4-0.7） | 摩擦低、滚得远、走线精准，远距离射程的主力选择 | +| 陶瓷弹珠（粗糙） | 0.015m（可调，范围 0.01-0.02m） | 1.0（可调，范围 0.8-1.2） | 0.3（可调，范围 0.2-0.5） | 0.8（可调，范围 0.7-0.9） | 摩擦高、滚得近，但碰撞恢复系数高，碰撞时把目标弹珠弹得更远，适合近距离把目标撞出圈 | +| 铁弹珠（重） | 0.012m（可调，范围 0.008-0.015m） | 2.5（可调，范围 2.0-3.0） | 0.1（可调，范围 0.0-0.3） | 0.6（可调，范围 0.5-0.8） | 质量大、碰撞动量大，能把多颗目标弹珠撞散，适合清场；注意贪力反噬规则，射手弹出会作废本回合收获 | + +**碰撞恢复系数语义**：弹珠碰撞目标弹珠时，目标弹珠被弹飞的位移程度与射手弹珠的碰撞恢复系数正相关。陶瓷最高（0.8，碰撞传递能量多）、铁次之（0.6）、玻璃最低（0.5）。这是陶瓷相对玻璃的核心差异化优势，补偿其滚动距离近的劣势。 + +**碰撞推力**：弹珠碰撞的总动量由质量决定（铁弹珠质量大，碰撞推力强），按物理规律自动计算。 + +### 策略矩阵（3 种弹珠 × 2 种场地） + +| 弹珠 ＼ 场地 | 水泥地（摩擦 0.3，滚得远） | 泥土地（摩擦 0.6，滚得近） | +|--------------|----------------------------|----------------------------| +| 玻璃 | 摩擦叠加 0.3，射程最远，精准弹出远距目标，**主力场景** | 摩擦叠加 0.6，射程压缩，需更大力度，精准优势仍在 | +| 陶瓷 | 摩擦叠加 0.6，滚得近，靠高碰撞恢复系数近距离把目标撞出 | 摩擦叠加 0.9，滚得最近，必须贴近目标，碰撞优势最大化发挥 | +| 铁 | 摩擦叠加 0.4，质量大清场，大力撞散目标群，警惕贪力反噬 | 摩擦叠加 0.7，减速快，需贴近距离发挥质量碰撞，警惕贪力反噬 | + +> 矩阵中"摩擦叠加"= 场地摩擦 + 弹珠摩擦加成，数值越小弹珠滚得越远。 + +--- + +## 平衡性验收标准 + +用于白盒调参阶段判断三维策略是否成立。所有数值为建议值，调参时以此为目标逼近： + +| 验收项 | 判据 | +|--------|------| +| 无死选项 | 3 种弹珠在 2 种场地共 6 种组合下，每种组合都存在一个"最优力度区间"使玩家能弹出至少 1 颗目标弹珠，无任何组合完全无法弹出 | +| 策略可感知 | 换弹珠后，玩家弹出同等距离目标所需的"最优力度"应有可感知差异（建议玻璃最优力度明显低于陶瓷，陶瓷低于铁） | +| 场地可感知 | 同一弹珠在水泥地与泥土地，玩家应感知到需要明显更大的力度才能达到相同射程 | +| 无碾压选项 | 3 种弹珠对同一 NPC 的胜率分布应落在合理区间（建议目标 40%-60%，通过白盒调参逼近，无某种弹珠胜率显著碾压） | +| 弹珠定位成立 | 玻璃的远距精准、陶瓷的近距强撞、铁的清场，三者应各有适用场景，不存在某弹珠在所有场地下都最优 | + +--- + +## 弹珠库存与收集进度 + +### 对战库存（弹珠小游戏管理） + +| 项目 | 规则 | +|------|------| +| 初始数量 | 5 颗（建议值，可调，范围 3-10 颗） | +| 弹珠构成 | 玻璃 / 陶瓷 / 铁混合，玩家选射手弹珠时能看到每颗属性与策略定位 | +| 射手弹珠归属 | 每局从库存选 1 颗作为射手弹珠，库存总数不变，用完归还 | +| 输赢流转 | 按对赌单位 ±库存，受保底机制约束 | +| 保底下限 | 3 颗（建议值，可调，范围 2-5 颗），玩家败时库存不会低于此值 | + +### 收集系统进度追踪（收集系统管理，v0.2 打通通知链路） + +| 项目 | 规则 | +|------|------| +| 归属 | 稀有弹珠通过收集系统的"获得物品"通知链路计入收集进度（v0.2 收集系统仅有进度追踪与收集通知能力，**无独立图鉴数据结构**，图鉴 UI 留 v0.4 收集系统完整版） | +| v0.2 稀有弹珠 | 仅"玻璃弹珠（猫眼）"1 种（与收集系统杂物清单的稀有归类一致；"弹珠（透明冰花）"在收集系统中归类为普通，不作为稀有弹珠）。后续版本扩展更多稀有花色 | +| v0.2 链路 | 弹珠小游戏中赢得稀有弹珠 → 通知物品系统 → 收集系统判定新收集 → 弹出收集通知，计入杂物收集进度 | +| 通知载荷 | 通知须携带三字段：物品名称（稀有弹珠名）+ 品类（"杂物"）+ 物品内部编号。稀有弹珠须预先注册进收集系统的杂物清单 | +| 完整展示 | v0.2 仅打通通知链路与进度计入，图鉴完整 UI 留 v0.4 | + +### 库存与收集进度的区分（边界） + +- 对战库存的输赢（普通弹珠）不影响收集进度，已收集的稀有弹珠不会因输局丢失 +- 收集进度的弹珠不直接进入对战库存计数（玩家主动将稀有弹珠"投入对战"的功能 v0.2 不做，留 v0.3+） + +--- + +## NPC 对手（v0.2） + +v0.2 提供 1 个 NPC 对手。默认采用死党 B（叙事框架角色列表中"家境差但乐观，弹珠高手"），小霸王作为备选配置。 + +| 配置项 | 死党 B（默认） | 小霸王（备选） | 说明 | +|--------|----------------|----------------|------| +| 准度（角度偏差） | ±3°（可调，范围 ±1°-±10°） | ±8°（可调，范围 ±1°-±10°） | 偏差越小越准 | +| 力度误差 | ±10%（可调，范围 ±5%-±25%） | ±20%（可调，范围 ±5%-±25%） | 力度偏差 | +| 基础力度 | 50%（可调，范围 30%-70%） | 60%（可调，范围 30%-70%） | 力度估算公式基数 | +| 距离补偿系数 | 每米 +15%（可调，范围 10%-25%/m） | 每米 +15%（可调，范围 10%-25%/m） | 距离远则加大力度 | +| 策略倾向 | 瞄准最近目标弹珠 | 瞄准距圈边缘最近、最易弹出的目标 | 目标选择方式 | +| 射手弹珠属性 | 玻璃弹珠（标准） | 铁弹珠（重） | NPC 射手弹珠沿用对应玩家弹珠属性表的数值 | + +**默认选择理由**：死党 B 准度高但力度稳健，让玩家前期有挑战又能赢，体验友好，契合叙事框架中"用便宜弹珠也能赢的高手"定位。 + +--- + +## 边界情况处理 + +### 玩家对战库存耗尽 +保底机制保证库存 ≥ 3 颗，玩家总能选到射手弹珠。若因异常库存为空，MatchInit 强制使用系统基础弹珠（属性等同于"玻璃弹珠（标准）"），不阻断游戏。 + +### 弹珠停在圈边界 +弹出判定统一使用带容差阈值：弹珠中心点到圈心距离 > 圈半径 + 容差 → 判定弹出；≤ 圈半径 + 容差 → 视为圈内（未弹出）。容差避免边界抖动导致的误判。此规则在 RoundEnd 弹出判定与边界情况中完全一致。 + +### 弹珠飞向场地边界 +场地周围有隐形边界（场地外扩 0.5m），弹珠碰撞后按反弹系数反弹回场地内，防止飞到不可达位置。 + +### 所有目标弹珠同一回合全部弹出 +RoundEnd 直接判定圈内剩余 0 颗 → 进入 MatchEnd，正常结算。 + +### 玩家中途退出 +玩家在 PlayerAim 按 ESC → 弹出"放弃本局？将判负"确认 → 确认则按"玩家放弃"处理（MatchEnd 跳过收获比较直接判玩家败，已收获弹珠作废），进入退出流程。PlayerCharge / Simulating 中 ESC 无效。 + +### NPC 弹射后弹珠几乎不动（力度极小） +仍走 Simulating → 快速停止 → RoundEnd → 切换回合，正常流转，不判定为异常。 + +### 物理结算卡死（弹珠持续微小运动） +超时保护 15 秒强制停止所有弹珠，进入 RoundEnd。 + +### 收获相等时的胜负 +由状态机记录的最近一次 Simulating 触发方（最后弹出方）决胜，不存在无法判定的情形。 + +--- + +## 跨系统交互 + +### 与交互系统（入口 / 出口） +- 弹珠小游戏作为交互系统的 SubSystem +- **进入**：玩家自行走到场地边缘触发范围内 → 交互系统"弹珠场地"交互物 → 原位转向 + 蹲下表现（不位移）→ postAction: minigame → SubSystem +- **退出**：MatchEnd 结算 + 玩家确认 → 原位站起（不位移）→ 退出 SubSystem → 交互系统回 Free 状态 +- 进入 / 退出全程不在交互系统 Interacting 状态内移动角色，符合交互系统"Interacting 内角色不移动"的规则 +- 弹珠小游戏内部使用独立的鼠标拖拽输入 + +### 与玩家控制器（视角与蹲下） +- **进入时**：角色蹲下（蹲下系统），相机切斜俯视 +- **退出时**：角色站起，相机回第三人称 +- 弹珠小游戏进行中角色不移动，玩家控制器的移动输入被忽略 + +### 与收集系统 / 物品系统（弹珠流转） +- 玩家赢得稀有弹珠 → 弹珠小游戏通知物品系统，载荷为三字段：物品名称（稀有弹珠名）+ 品类（"杂物"）+ 物品内部编号 → 物品系统弹出拾取通知 → 收集系统判定新收集弹出收集通知（计入杂物收集进度） +- 对战库存的普通弹珠输赢不经过物品系统，由弹珠小游戏内部管理 +- 弹珠小游戏不直接与收集系统通信，通过物品系统中转（与现有架构一致） +- 稀有弹珠须预先注册进收集系统的杂物清单（"玻璃弹珠（猫眼）"已存在于收集系统杂物清单并标为稀有） + +### 与蹲下系统 +- 弹珠小游戏入场使用蹲下表现（角色蹲在场地边操作弹珠），调用蹲下系统的"强制蹲下"接口 +- 退出时调用蹲下系统的"强制站起"接口 +- 蹲下系统的独立行为规则（蹲伏移动 / 待机 / 切换）见 `蹲下系统-执行案.md` + +--- + +## v0.2 不实现清单 + +| 功能 | 排除原因 | +|------|----------| +| 多规则（打坑 / 靠墙 / 斜坡） | v0.2 仅画圈弹验证核心，多规则留 v0.3+ | +| 手法系统（拇指法 / OK 法） | 四维降维，手法差异小，留 v0.3+ | +| 手柄操作 | 键鼠为主，手柄留后续 | +| 收集图鉴完整 UI | 留 v0.4 收集系统完整版 | +| 多 NPC 对手切换 | v0.2 固定 1 个对手 | +| NPC 日常 AI / 移动 | 留 v0.3（v0.2 NPC 仅静态站位 + 弹射 AI） | +| 拍洋画、四驱车、FC 家用机、街机厅、包机房、肢体活动类等其他小游戏品类 | 留后续版本（详见 `小游戏系统.md` 品类架构） | +| 弹珠花色外观美术差异 | v0.2 白盒，弹珠用颜色区分属性 | +| 玩家投入稀有弹珠对战 | 留 v0.3+ | +| 回合数上限 / 主动认输系统 | v0.2 弹完即结束，无回合上限 | +| 音效（弹射 / 碰撞 / 结算） | 留 v0.3 | + +--- + +## 可调参数汇总 + +| 参数 | 建议值 | 可调范围 | 说明 | +|------|--------|----------|------| +| 就位表现时长 | 0.8 秒 | 0.5-1.2 秒 | 进入时角色原位转向 + 蹲下 | +| 进入相机切换时长 | 0.6 秒 | 0.4-1.0 秒 | 第三人称 → 斜俯视 | +| 退出相机切换时长 | 0.6 秒 | 0.4-1.0 秒 | 斜俯视 → 第三人称 | +| 站起表现时长 | 0.8 秒 | 0.5-1.2 秒 | 退出时角色站起 | +| 射手弹珠高亮频率 | 1Hz | 0.5-2Hz | PlayerAim 脉冲发光 | +| 最大拖拽距离（屏幕高度占比） | 15% | 8%-25% | 力度 100% 对应的拖拽距离，相对屏幕高度 | +| 最小有效力度 | 10% | 5%-20% | 低于此松开视为取消 | +| 轨迹预测线最大显示长度 | 3m | 2-5m | 预测线最长路径 | +| 最大弹射初速度（100% 力度） | 8 m/s | 5-12 m/s | 力度 100% 时弹珠出膛初速度，对所有弹珠相同 | +| 圈半径 | 1.0m | 0.8-1.5m | 弹出判定边界 | +| 目标弹珠数 | 5 颗 | 3-8 颗 | 圈中央初始放置 | +| 对赌弹珠数 | 1 颗 | 1-3 颗 | 胜负流转单位 | +| 弹出判定容差 | 0.01m | 0.005-0.02m | 圈边界判定（统一带容差） | +| 场地边界外扩 | 0.5m | 0.3-1.0m | 隐形反弹边界 | +| 初始对战库存 | 5 颗 | 3-10 颗 | 玩家起始弹珠数 | +| 保底下限 | 3 颗 | 2-5 颗 | 库存不低于此值 | +| 弹珠停止速度阈值 | 0.05m/s | 0.02-0.1m/s | 判定停止 | +| 稳定时间 | 1 秒 | 0.5-2 秒 | 低于阈值持续至此判定停止 | +| 超时保护 | 15 秒 | 10-30 秒 | 物理结算强制停止 | +| 水泥地摩擦 | 0.3 | 0.2-0.5 | 场地摩擦（低） | +| 泥土地摩擦 | 0.6 | 0.4-0.8 | 场地摩擦（高） | +| 玻璃弹珠半径 | 0.015m | 0.01-0.02m | 标准弹珠 | +| 玻璃弹珠质量 | 1.0 | 0.8-1.2 | 相对单位 | +| 玻璃弹珠摩擦加成 | 0.0 | 0.0-0.2 | 低摩擦 | +| 玻璃弹珠碰撞恢复系数 | 0.5 | 0.4-0.7 | 碰撞传递中等 | +| 陶瓷弹珠半径 | 0.015m | 0.01-0.02m | 标准弹珠 | +| 陶瓷弹珠质量 | 1.0 | 0.8-1.2 | 相对单位 | +| 陶瓷弹珠摩擦加成 | 0.3 | 0.2-0.5 | 高摩擦 | +| 陶瓷弹珠碰撞恢复系数 | 0.8 | 0.7-0.9 | 碰撞传递高（核心优势） | +| 铁弹珠半径 | 0.012m | 0.008-0.015m | 小而重 | +| 铁弹珠质量 | 2.5 | 2.0-3.0 | 相对单位（重） | +| 铁弹珠摩擦加成 | 0.1 | 0.0-0.3 | 低摩擦 | +| 铁弹珠碰撞恢复系数 | 0.6 | 0.5-0.8 | 碰撞传递中等 | +| 弹珠-场地边界反弹系数 | 0.5 | 0.3-0.7 | 弹珠碰撞场地边界的反弹程度 | +| 目标弹珠属性 | 等同玻璃弹珠（标准） | — | 圈中央目标弹珠统一属性 | +| 系统基础弹珠属性 | 等同玻璃弹珠（标准） | — | 异常兜底用弹珠 | +| NPC 思考延迟 | 1.0 秒 | 0.5-2.0 秒 | NpcThink 状态 | +| 死党 B 准度（角度偏差） | ±3° | ±1°-±10° | NPC 弹射准度 | +| 死党 B 力度误差 | ±10% | ±5%-±25% | NPC 力度偏差 | +| 死党 B 基础力度 | 50% | 30%-70% | 力度估算基数 | +| 死党 B 距离补偿系数 | 每米 +15% | 10%-25%/m | 距离补偿 | +| 结果显示时长 | 2.0 秒 | 1.5-3.0 秒 | 胜负文本 | + +> 摩擦组合规则：最终摩擦 = 场地摩擦 + 弹珠摩擦加成。碰撞推力按物理规律根据质量自动计算。 + +--- + +## 文本示例 + +> 所有文本为小孩当下视角，无成人回顾。 + +### 操作提示 +- MatchInit：`选择你的射手弹珠` → `按 空格 开始` +- PlayerAim：`按住弹珠拖拽瞄准　ESC 放弃本局` +- 放弃确认：`放弃本局？将判负　[确认] [取消]` +- 结束确认：`按 空格 离开` + +### 局结算 +- 胜：`你赢了！获得 1 颗弹珠` +- 败（正常）：`你输了…失去 1 颗弹珠` +- 败（保底）：`你输了…好在没失去弹珠` +- 玩家放弃：`你放弃了这局` + +### 射手弹珠选择界面（属性标注，措辞对称） +- `玻璃弹珠 · 滚得远，走线精准` +- `陶瓷弹珠 · 滚得近，碰撞利落` +- `铁弹珠 · 质量大，撞散目标` diff --git a/docs/design/蹲下系统-执行案.md b/docs/design/蹲下系统-执行案.md new file mode 100644 index 0000000..bf911c5 --- /dev/null +++ b/docs/design/蹲下系统-执行案.md @@ -0,0 +1,218 @@ +# 蹲下系统执行案（v0.2 原型） + +## 迭代记录 + +| 迭代版本 | 修改日期 | 状态 | 说明 | +|----------|----------|------|------| +| v0.2.0 | 2026-06-15 | 📝 设计中 | 初版执行案，蹲伏姿态、蹲伏移动、视角与高度变化、低矮空间通行、与弹珠入场衔接 | + +> 状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步 + +--- + +## 系统概述 + +蹲下系统是玩家控制器的扩展。v0.1 仅实现站立姿态（Idle / Running），v0.2 增加蹲伏姿态。 + +**蹲下在 v0.2 的三个用途**： +1. **弹珠小游戏入场** — 角色蹲在场地边操作弹珠（由弹珠系统调用，系统强制蹲下） +2. **探索低矮空间** — 钻入桌下、矮洞、低矮门洞，发现隐藏物品 +3. **探索层次感** — 蹲下降低视角，看到接近地面的细节，增加探索丰富度 + +### 核心设计决定（已确认） + +1. **切换式蹲下（按 C 键切换站 / 蹲）** — 非长按。适合探索，蹲下找东西不需持续按键 +2. **蹲伏移动速度低于跑步** — 蹲下是谨慎 / 探索状态，速度约为跑步的一半 +3. **蹲伏降低有效高度** — 可钻过低矮空间（站立进不去的地方） +4. **蹲伏降低视角** — 摄像机跟随蹲下的头部高度 +5. **系统可强制蹲下** — 弹珠入场由系统控制姿态，玩家 C 键无效 + +--- + +## 系统边界 + +| 蹲下系统负责 | 蹲下系统不负责 | +|--------------|----------------| +| 蹲 / 站姿态切换与过渡表现 | 蹲下专属的隐藏物品内容（交互 / 收集系统） | +| 蹲伏移动速度与转向 | 低矮空间的场景搭建（关卡） | +| 蹲伏时有效高度与视角变化 | 弹珠小游戏的内部逻辑（弹珠系统） | +| 为弹珠入场提供蹲下姿态接口 | 交互物"仅蹲伏激活"的具体配置（交互系统） | + +--- + +## 状态定义（扩展玩家控制器） + +在 v0.1 的 Idle / Running 基础上引入"姿态层 + 移动层"二维状态： + +| 姿态 | 移动 | 组合状态 | 说明 | +|------|------|----------|------| +| Stand | Idle | 站立待机 | v0.1 的 Idle | +| Stand | Moving | 跑步 | v0.1 的 Running，4.5 m/s | +| Crouch | Idle | 蹲伏待机 | v0.2 新增 | +| Crouch | Moving | 蹲伏移动 | v0.2 新增，2.0 m/s | + +### 状态转换 + +``` +Stand-Idle ──(按 C)──→ Crouch-Idle +Stand-Moving ──(按 C)──→ Crouch-Moving +Crouch-Idle ──(按 C + 头顶无障碍)──→ Stand-Idle +Crouch-Moving ──(按 C + 头顶无障碍)──→ Stand-Moving +Crouch-Idle ──(按移动键)──→ Crouch-Moving +Crouch-Moving ──(松开移动键)──→ Crouch-Idle +``` + +**站起障碍检测**：从蹲到站，若头顶存在障碍物（处于低矮空间内）→ 无法站起，保持蹲伏。 + +**弹珠系统强制切换**：弹珠入场时角色强制进入 Crouch 姿态（系统触发，非玩家按 C）；退出时强制回到 Stand。 + +--- + +## 行为规则 + +### 一、姿态切换（站 ↔ 蹲） + +#### 玩家主动切换 + +| 操作 | 触发 | 表现 | +|------|------|------| +| 站 → 蹲 | 玩家按 C 键 | 立即开始下蹲过渡，时长 0.3 秒（建议值，可调，范围 0.2-0.5 秒）。过渡中可移动（按蹲伏速度） | +| 蹲 → 站 | 玩家按 C 键 | 先检测头顶障碍。无障碍 → 站起过渡 0.3 秒；有障碍 → 拒绝站起，保持蹲伏 | +| 过渡中再按 C | 取消当前过渡，反向切换 | 例：下蹲过渡中按 C → 转为站起 | + +#### 系统强制切换（弹珠入场 / 退出） + +| 场景 | 行为 | +|------|------| +| 弹珠入场 | 系统强制角色进入 Crouch 姿态（就位表现 0.8 秒，含下蹲过渡） | +| 弹珠退出 | 系统强制角色回到 Stand 姿态（站起表现 0.8 秒，含站起过渡） | +| 强制期间 | 玩家的 C 键输入被忽略，姿态由弹珠系统控制 | + +--- + +### 二、蹲伏移动 + +#### 速度与加减速 + +| 项目 | 建议值 | 可调范围 | 说明 | +|------|--------|----------|------| +| 蹲伏移动速度 | 2.0 m/s | 1.5-3.0 m/s | 约跑步（4.5）一半 | +| 蹲伏起步加速时间 | 0.2 秒 | 0.1-0.4 秒 | 与站立一致 | +| 蹲伏停止减速时间 | 0.3 秒 | 0.2-0.5 秒 | 与站立一致 | + +#### 方向与转向 + +- **移动方向**：相对摄像机水平朝向（与站立移动逻辑一致） +- **蹲伏转向速度**：540°/秒（建议值，可调，范围 360°-720°/秒），低于跑步（720°/秒），蹲下转身更慢、更谨慎 +- **连续移动**：蹲伏中旋转摄像机，移动方向实时跟随，与站立行为一致 + +#### 动画 + +- **蹲伏待机**：蹲姿静止（v0.2 占位动画） +- **蹲伏移动**：蹲姿挪步（v0.2 占位动画） + +--- + +### 三、蹲伏时的有效高度与通行 + +#### 有效高度 + +| 姿态 | 有效高度（建议值） | 可调范围 | +|------|---------------------|----------| +| 站立 | 1.6m | 1.4-1.8m | +| 蹲伏 | 1.0m | 0.8-1.2m | + +#### 通行规则 + +- 角色有效高度 ≤ 空间净高 → 可通过 +- 角色有效高度 > 空间净高 → 被阻挡 +- **效果**：蹲伏时可通过净高在 1.0m-1.6m 之间的低矮空间（桌下、矮洞、低矮门洞），站立无法进入 +- 蹲伏通过低矮空间时保持蹲伏姿态；离开低矮空间（头顶已无障碍）后可按 C 站起 + +--- + +### 四、蹲伏时的摄像机 + +| 项目 | 站立 | 蹲伏 | 说明 | +|------|------|------|------| +| 摄像机高度（头部上方） | 0.8m | 0.4m（建议值，可调，范围 0.3-0.6m） | 蹲伏视角降低 | +| 摄像机俯角 | 15° | 15° | 保持一致 | +| 跟随方式 | 软跟随 | 软跟随 | 规则不变 | + +**姿态切换时摄像机过渡**：摄像机高度随姿态过渡同步平滑变化（0.3 秒），与角色下蹲 / 站起同步。 + +**效果**：蹲下时视角降低，看到更接近地面的细节，适合寻找隐藏在低处的物品。 + +--- + +## 边界情况处理 + +### 在低矮空间内尝试站起 +头顶障碍检测阻止站起，角色保持蹲伏。v0.2 不强制提示文字，仅阻止动作（后续可加"上方有东西"的轻微反馈）。 + +### 蹲伏中头顶突然出现障碍（动态物体掉落） +v0.2 无动态物理掉落系统，不存在此情况。后续若加入，需定义"被压住时强制保持蹲伏"规则。 + +### 蹲伏中进入交互 +- 蹲伏姿态可正常触发交互，交互系统不因姿态拒绝触发 +- 交互期间姿态冻结（保持触发交互时的姿态），交互结束后恢复玩家控制 +- 某些低矮交互物（桌下物品）仅在蹲伏姿态下激活其触发范围 + +### 蹲伏中进入弹珠小游戏 +弹珠入场强制蹲下。若角色已在蹲伏姿态，就位表现中姿态无变化（仍为蹲伏），仅播放走到场地的位移表现。 + +### 姿态切换过渡中按移动键 +过渡中接受移动输入，按目标姿态的速度移动。例：站 → 蹲过渡中按住 W → 角色以蹲伏速度开始移动。 + +### 姿态切换过渡中进入交互 +交互触发时冻结当前姿态（无论过渡进行到哪）。交互结束后回到冻结时的姿态。 + +--- + +## 跨系统交互 + +### 与玩家控制器（移动系统） +- 蹲下系统扩展玩家控制器的姿态层，移动方向逻辑复用 +- 蹲伏移动速度、转向速度由蹲下系统提供数值 + +### 与交互系统 +- 蹲伏姿态可正常触发交互 +- 蹲下系统向交互系统提供"当前姿态"信号；某些低矮交互物仅在 Crouch 姿态激活触发范围（由交互物配置决定） + +### 与弹珠小游戏 +- 弹珠入场调用蹲下系统的"强制蹲下"接口 +- 弹珠退出调用蹲下系统的"强制站起"接口 +- 弹珠小游戏进行期间，姿态由弹珠系统控制，玩家 C 键无效 + +### 与收集系统（间接） +- 蹲伏发现的隐藏物品 → 交互拾取 → 通知物品系统 → 收集系统处理 +- 蹲下系统不直接与收集系统通信 + +--- + +## v0.2 不实现清单 + +| 功能 | 排除原因 | +|------|----------| +| 长按式蹲下 | 采用切换式，更适配探索 | +| 匍匐（趴下，更低姿态） | 留后续版本 | +| 蹲下静音 / 潜行机制 | 无 NPC 听觉 AI（v0.3+ 才有 NPC） | +| 蹲下专属精细动画 | v0.2 使用占位动画 | +| 滑铲 / 翻滚 | 留后续版本 | +| 站起失败的文字提示 | v0.2 仅阻止动作，不加提示 | + +--- + +## 可调参数汇总 + +| 参数 | 建议值 | 可调范围 | 说明 | +|------|--------|----------|------| +| 蹲伏移动速度 | 2.0 m/s | 1.5-3.0 m/s | 约跑步一半 | +| 蹲伏转向速度 | 540°/秒 | 360°-720°/秒 | 低于跑步 720°/秒 | +| 站立有效高度 | 1.6m | 1.4-1.8m | 小孩身高 | +| 蹲伏有效高度 | 1.0m | 0.8-1.2m | 蹲下高度 | +| 蹲伏摄像机高度 | 0.4m | 0.3-0.6m | 蹲伏头部上方 | +| 姿态切换过渡时长 | 0.3 秒 | 0.2-0.5 秒 | 站 ↔ 蹲 | +| 蹲伏起步加速时间 | 0.2 秒 | 0.1-0.4 秒 | 与站立一致 | +| 蹲伏停止减速时间 | 0.3 秒 | 0.2-0.5 秒 | 与站立一致 | +| 弹珠就位表现时长 | 0.8 秒 | 0.5-1.2 秒 | 含下蹲过渡（与弹珠执行案一致） |