docs(design): v0.2 弹珠小游戏与蹲下系统设计准备

- 弹珠小游戏执行案 v0.2.1（经6维度对抗性审查修订25项问题） - 蹲下系统执行案 v0.2.0（玩家控制器姿态扩展） - v0.2 范围定义（对标 v01-范围） - 弹珠操作手感与系统决策头脑风暴共识 - 弹珠配置表（属性/场地/NPC/参数，4个文件） - 更新设计文档索引与 GameConfig 说明 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-15 05:07:41 +08:00
parent 893ef1eac2
commit 2c10eedad3
10 changed files with 1143 additions and 2 deletions
@@ -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 创建/更新配置文件
@@ -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 思考延迟" }
+  }
+}
@@ -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
@@ -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,库存异常兜底用
@@ -0,0 +1,3 @@
+id,displayName,friction,frictionMin,frictionMax,behaviorNote
+concrete,水泥地,0.3,0.2,0.5,摩擦低滚动均匀距离远走线可预测适合精准操作
+dirt,泥土地,0.6,0.4,0.8,摩擦高减速快滚动距离明显短需更大力度到达圈心