starmen1265
2f0a2133a1
- 弹珠执行案 v0.2.2：明确进入触发物就位点(=玩家起点)与半径(1.5m)、MatchInit射手弹珠选择改UI列表+可重选、贪力反噬放回初始起点、补质量基准脚注 - 蹲下执行案 v0.2.1：修复与弹珠执行案"不位移"的矛盾、补蹲伏动画兜底声明 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
34 KiB
34 KiB
弹珠小游戏执行案（v0.2 原型）
迭代记录
| 迭代版本 | 修改日期 | 状态 | 说明 |
|---|---|---|---|
| v0.2.0 | 2026-06-15 | 📝 设计中 | 初版执行案，覆盖画圈弹规则、弹弓式操作、NPC对手、对战库存保底的完整行为规则。基于头脑风暴-2026-06-15 共识 |
| v0.2.1 | 2026-06-15 | 📝 设计中 | 对抗性审查修订（25 项确认问题）：补全物理参数语义（摩擦组合规则、弹射初速度、目标弹珠属性、碰撞恢复系数）；泥土地去随机偏差改确定性差异；陶瓷补碰撞传递优势并加策略矩阵；统一平局/容差/射手弹出代价逻辑；明确 Interacting 内不位移；量化 NPC 力度参数；修正稀有弹珠归类与术语；新增平衡性验收标准 |
| v0.2.2 | 2026-06-15 | 📝 设计中 | game-reviewer 审查修订：明确进入触发物注册点（=玩家起点=射手弹珠生成点）与触发半径（1.5m）；MatchInit 射手弹珠选择改为 UI 列表 + 可重选；贪力反噬放回“初始起点”精确化；补充质量相对值基准脚注 |
状态标记：📝 设计中 | 🔄 开发中 | ✅ 已同步
系统概述
弹珠小游戏是 v0.2 的核心，验证游戏三大支柱之一"好玩"是否成立。
验证假设：弹珠小游戏的操作手感成立吗？策略深度够让人玩十几把不腻吗？
体验目标：操作手感直觉流畅，策略深度来自弹珠属性选择与场地差异的组合，而非操作精度。
v0.2 范围：1 种规则（画圈弹）、2 种场地（水泥地 / 泥土地）、3 种弹珠属性（玻璃 / 陶瓷 / 铁）、1 个 NPC 对手、与对战库存联动。
核心设计决定（基于头脑风暴共识，已确认）
- 简化上手，策略为主 — 力度与方向用弹弓式拖拽一步完成，重复可玩性来自策略组合，不靠操作精度
- 斜俯视视角 — 45° 俯瞰场地，全局可见，瞄准直观
- 回合制 — 玩家与 NPC 轮流弹射
- 弹弓式拖拽操作 — 按住弹珠反向拖拽，方向与力度合一，配轨迹预测线
- 键鼠为主 — 手柄 v0.2 不做
- 手法维度 v0.2 不做 — 头脑风暴原定的四维策略在 v0.2 降为"弹珠属性选择 + 场地差异"两个玩家可感知维度，手法（拇指法 / OK 法）留 v0.3+
- 库存 / 进度追踪分离 — 对战库存（输赢流转）与收集系统进度追踪（永久记录）分开管理
系统边界
| 弹珠小游戏负责 | 弹珠小游戏不负责 |
|---|---|
| 弹珠小游戏的进入 / 退出流程 | 弹珠场地的场景美术搭建（关卡） |
| 弹弓式操作的交互与反馈 | 弹珠作为收集品的进度展示（收集系统） |
| 画圈弹规则判定与物理结算 | NPC 的日常行为 AI（v0.3） |
| NPC 对手的弹射决策 | 多规则 / 多场地的扩展（v0.2 仅 1 规则 2 场地） |
| 对战库存的输赢流转与保底 | 手法系统（v0.3+） |
| 胜负判定与奖励结算 | 拍洋画、四驱车、FC 家用机、街机厅、包机房等其他小游戏品类（详见 小游戏系统.md 品类架构） |
进入与退出（与交互系统衔接）
弹珠小游戏作为交互系统的 SubSystem（交互系统执行案 v0.1 已预留该状态与 postAction: minigame 分叉）。
关键约束：交互系统的 Interacting 状态规定"所有移动输入被忽略，角色不移动"。因此弹珠小游戏的进入流程不依赖 Interacting 状态内的角色位移——玩家触发交互时必须已站在场地边缘的触发范围内，进入流程只做转向 + 蹲下表现，不发生位移。
进入流程
| 步骤 | 行为 |
|---|---|
| 1 | 玩家在空地弹珠场地附近自由走动 |
| 2 | 玩家自行走动到弹珠场地的交互触发范围内。交互触发物注册点位于圈外"玩家起点"（即射手弹珠生成点），触发半径复用交互系统建议值 1.5m（可调，范围 1.0-3.0m）。玩家就位点 = 玩家起点 = 射手弹珠生成点（三点重合），保证斜俯视相机能覆盖全场 |
| 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 起点位置"（与玩家起点关于圈心对称，位于圈的对侧）
- 屏幕显示"选择你的射手弹珠"界面（UI 列表面板，非 3D 场景操作）：列出玩家对战库存中所有弹珠，标注每颗的属性（玻璃 / 陶瓷 / 铁）与一句话策略定位
- 玩家鼠标点击列表项选择射手弹珠，点选后该项高亮为"当前选中"。玩家可反复点击不同弹珠切换选择（最后一次点选生效），场上射手弹珠属性实时跟随当前选中项更新
- 显示提示
按 空格 开始。玩家按空格确认当前选中弹珠 → 界面收起，进入 PlayerAim
结束条件：玩家按空格 → 进入 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 决策规则：
- 按策略倾向选择目标弹珠（死党 B：选距离 NPC 射手弹珠最近的目标弹珠）
- 计算瞄准方向（NPC 射手弹珠 → 目标弹珠）
- 按距离估算力度：力度 = 基础力度 + 距离补偿系数 × 距离。基础力度 50%（建议值，可调，范围 30%-70%），距离补偿系数每米 +15%（建议值，可调，范围 10%-25%/m）。估算结果截断在 0%-100%
- 加入准度偏差与力度误差（取自 NPC 属性配置，死党 B：角度偏差 ±3°、力度误差 ±10%，详见"NPC 对手"章节）
- 弹射，进入 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）。这是陶瓷相对玻璃的核心差异化优势，补偿其滚动距离近的劣势。
碰撞推力：弹珠碰撞的总动量由质量决定（铁弹珠质量大，碰撞推力强），按物理规律自动计算。
质量基准：质量为相对单位，玻璃弹珠质量 1.0 为基准（实际物理质量由技术方案按基准换算），其他弹珠质量为相对玻璃的倍数。
策略矩阵（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 颗弹珠 - 败（保底）：
你输了…好在没失去弹珠 - 玩家放弃：
你放弃了这局
射手弹珠选择界面（属性标注，措辞对称）
玻璃弹珠 · 滚得远，走线精准陶瓷弹珠 · 滚得近，碰撞利落铁弹珠 · 质量大，撞散目标