《乒乓生涯》引擎技术交接文档

用途:换 agent 时的完整交接。覆盖评分机制、属性机制、AI 决策、物理引擎、每 1 分差距的含义、真实球员数据标定方法、完整开发日志。
项目路径:/root/1234/tt-physics/ | 引擎:Godot 4.7(GDScript,纯代码后端 + Control UI)| 测试:9 套件 200 项检查全绿。

0. 一页速览(10 行读懂整个系统)

1. 评分机制(三套体系 + 绝对属性)

1.1 开球网积分(400-3000,底层锚点)

ELO 制:预期胜率 E = 1/(1+10^((Rb-Ra)/400)),K=32。所有球员内部都持有一个开球网积分,是业余/专业两套评分的换算桥梁。专业界面隐藏它,只在业余赛事对手身上显示。

1.2 业余评分(0-100)

由开球网积分分段线性映射(低分段区分度高):

1.3 专业评分(0-100)

2300 起(2300 以下不属专业体系,显示"—"):

1.4 绝对属性(引擎唯一标尺,0-100)

1.5 单项属性双标尺换算(核心公式,已在 src/scale.gd)

业余 → 绝对:                绝对 → 业余:
  v≤60: v×0.55                v≤33: v/0.55
  60<v≤80: 33+(v-60)×0.8      33<v≤49: 60+(v-33)/0.8
  80<v≤90: 49+(v-80)×1.1      49<v≤60: 80+(v-49)/1.1
  v>90: 60+(v-90)×4.0          v>60: 90+(v-60)/4.0

专业 → 绝对:                绝对 → 专业:
  v≤30: 40+v×0.7              v<40: 0(专业体系外)
  30<v≤50: 61+(v-30)×0.7      40≤v≤61: (v-40)/0.7
  50<v≤70: 75+(v-50)×0.5      61≤v≤75: 30+(v-61)/0.7
  v>70: 85+(v-70)×0.5         75≤v≤85: 50+(v-75)/0.5
                                v>85: 70+(v-85)/0.5

1.6 总评(绝对总评)计算

总评 = Σ(大类评分 × 风格权重)
大类评分 = Σ(子属性 × 类内权重)  (进攻类先算"正手拉球总评=前冲0.5+高吊0.3+侧拐0.2"等复合项)
风格权重(7风格,主0.7+副0.3混合):
  进攻型  .35/.10/.15/.10/.20/.10   快攻型  .30/.10/.20/.10/.20/.10
  弧圈相持 .35/.10/.10/.10/.25/.10   台内控制 .20/.10/.30/.15/.15/.10
  防守反击 .15/.30/.15/.10/.20/.10   削球型  .10/.35/.10/.10/.25/.10
  变化型   .20/.10/.20/.20/.15/.15   (顺序:进攻/防守/台内/发接/步法/心理)
器材修正先加在属性上(横拍反手拧拉+3…、正胶旋转类×0.85…),再截断开球网段上限,再加权。

总评与单项标尺的关系:总评是属性加权(绝对口径)。显示时再经绝对→专业/业余换算。16 岁青训开局:开球网 2300 → 绝对属性上限 61、绝对属性基础 58-61(核心技术/步法=61)、绝对总评约 60、专业综评≈29。

2. 属性机制(54 项,每项"差 1 分"的影响)

2.1 属性 → 物理参数的通用公式链

挥拍速度 swing = 基础速度 × (0.6+0.6·技术/100) × (0.8+0.4·爆发力/100) × 状态系数
目标转速 ω    = 顶级理论转速 × (技术/100) × (0.8+0.4·手腕/100)     (上限900 rad/s≈143转/秒)
拍面误差 err  = ((1-技术/100)×0.04 + 0.006 + (1-技术/100)×0.02×来球旋转强度) × (1-手腕/100×0.4)
主动失误率 p  = 基础失误率(按技术) × (1-技术/100) × 心理(1+(1-沉着/100)×0.5) × 体能(1+疲劳) × 风险(0.6+0.8×risk)
质量系数 Q   = (技术/100)×(爆发力/100)×(手腕/100)×手感×rand(0.9~1.1)
落点深度     = 0.45+0.7×(技术/100)^1.2   (控制型技术改打短球0.25+0.4·t/100)
够球率 P     = 1/(1+e^(-(步法分-来球难度)/8)), 步法分=启动×0.3+移动精度×0.5+还原×0.2

2.2 技术类属性(38 项)差 1 分的通用效果

技术属性 t 每 +1 分(以 t=70 为基准的典型值):

各技术的基础值差异(决定"同属性下不同技术强度"):

特殊修正:侧切出球速度×(0.5+0.5·侧切/100)卸力;吸短×(0.4+0.6·吸短/100)减力;扣杀失误=0.08×(1-扣杀/100)×(0.3+1-沉着/100)×体能×风险;放高球失误=0.03×(1-放高球/100)×(0.3+1-核心腰腹/100)×体能×风险。

2.3 身体类(7 项)差 1 分的影响

2.4 心理类(4 项)差 1 分的影响

2.5 发接类(4 项)差 1 分的影响

2.6 隐藏属性(5 项)

3. AI 球员决策机制

3.1 三层思维链(src/brain.gd)

战略层(比赛/局间):风格→主基调(attack/control/defend);总评差>25→风险基线×0.55求稳;
  比分落后→基线0.7、领先→0.35;再×胆识因子(0.7+0.6·胆识/100);压制区域=对手弱侧(反手/正手/中路)。
战术层(每回合):round_intent() 抢攻/控制/防守(连失2分+信心低→转控制;手感热→抢攻);
  serve_tactic() 发球旋转/落点/速度(对手接发弱→多变旋转;压对手弱侧)。
执行层(每拍 _strike):技术选择=策略表(按来球旋转×落点)→机会球识别(对手质量<0.4→拧拉/爆冲/扣杀)
  →冒险度 risk(见3.2)→接发判断→主动失误roll→意图生成→物理裁决。

3.2 冒险/搏杀管线(risk)

risk = clamp(战略基线(0.7+0.6·胆识/100 修正) + 意图(抢攻+0.15/防守-0.2)
            + 比分(落后3分+0.2/领先4分-0.15) + 手感(热+0.1/连失-0.1)
            + 关键分(沉着≥85-0.1/胆识≥85+0.1), 0.05~0.95)
     × 士气(0.35+0.65·士气)
risk 三出口:① 发力 swing×(0.8+0.4·risk) ② 失误率×(0.6+0.8·risk) ③ 技术选择(risk≥0.55→爆冲/扣杀,否则拉前冲)
物理裁决兜底:risk高→球快→可行角度窗口窄→拍面误差推出窗口→出界/下网(冒险=高失误的物理来源,非概率硬凑)
反馈:连续下网/出界≥2→swing×0.88收力(自动从搏杀降级,不会无限失误)

3.3 状态机制(士气/疲劳/发挥系数)

士气 morale(0-1):得分+波动×0.7;主动失误-波动×2.2(莫名其妙没打上波动最大);被压失分-波动×1.0;
  连得3分+波动×0.8回稳。波动值=0.08×(1-沉着/100×0.6)×(1-稳定性/100×0.5)。
士气低→保守(risk×士气因子)+士气<0.3→失误率×1.15(决策崩盘)。
疲劳 fatigue(0-1):每分+0.012×(1.5-耐力/100);疲劳→质量惩罚≤25%+失误率×(1+疲劳)+移动-30%+反应+40%+步法分-35%。
发挥系数 form=状态系数(0.85+0.3×近期状态)×士气心理(1+(士气-0.5)×0.2)×大赛(1+大赛发挥/100×0.1)×伤病(0.85)。
  最终有效属性=绝对属性×器材修正×form(比赛引擎每分刷新;比赛后复位,防残留污染球员卡)。

3.4 技术选择细节

策略表(select_technique):近网下旋→摆短/劈长/拧拉/挑打/晃搓…;近网上旋→挑打/弹击/拧拉;
  底线长下旋→拉高吊/拉前冲/削球;底线长上旋→快带/反拉/攻球;追身→攻球/推挡/防守;高球→扣杀。
机会球:对手质量Q<0.4→台内拧拉/挑打、中台risk≥0.55爆冲否则拉前冲、高球risk≥0.55扣杀否则拉前冲。
有限博弈(expect_advantage):每个候选技术算"我的出球质量→对手失误概率-我的失误概率",加权0.6进技术得分。
AI 决策:70% 选得分最高技术,30% 属性加权随机(临场变化)。

3.5 器材机制

3.6 徽章系统(12 枚,src/badges.gd)

触发:技术/情境(接发/相持/关键分/落后)匹配→每效果独立概率→应用。
效果类型:属性提升(可破上限)/球速提升/旋转提升/失误率降低/直接得分(发力×1.25)。
例:霸王拧(拧拉30%旋转+30%速度+25%、8%直接得分)、前三板大师(接发全属性+20%必触发)、
  大心脏(关键分沉着胆识+20%、失误-30%)、绝地反击(落后全属性+10%)、发球机器(发球旋转+20%隐蔽+15%)。
开局按风格赠送(STYLE_BADGES)+大心脏。

4. 物理引擎运算方式

4.1 飞行(RK4,dt=0.0005s)

力:重力(9.81,-z)+空气阻力+马格努斯。马格努斯 |Fm|=0.5·ρ·A·Cm·v²·(ω×v)/|ω||v| ——大小只与v²有关、与转速无关!
  下压力 a_m=0.0561·v²(球向+X飞、上旋ω=+Y时向下);实战用平均系数0.0382·v²(球速飞行中衰减到0.6-0.7,平均下压力≈0.68×瞬时)。
旋转衰减:ω(t)=ω0·e^(-λt)。

4.2 碰撞

台:法向恢复0.9+库仑摩擦μ=0.5,切向冲量封顶 min(μ·jn, 2/7·|v_t|)。下旋球底部前滚→摩擦削减前向速度→
  多次弹跳后回跳/停台(已实验验证:ω=550慢发高弧23次弹跳停在对方半台近网)。
网:薄片模型,x反向低恢复(0.3),y/z衰减。
拍:平面碰撞,恢复0.85,摩擦0.8,无滑移封顶;碰撞后旋转=0.3×物理+0.7×目标旋转(简化旋转传递)。

4.3 目标导向击球模型(2025 重写,用户批准):每板两步 ① 判定阶段(属性驱动):技术/战术 → 目标落点区域(安全区,不贴底线;技术决定深浅、战术决定左右、risk 决定深浅)+ 属性散布(σ = 0.02+0.28×(1−t/100)^2 rad,安全阈值下限 0.02 rad=现实高手落点精度极限)→ 上台概率 p_on = 0.85+0.15×t − 0.25×来球质量(受迫) − 主动失误率,接发再×判断系数;失败 = 下网/出界,回合结束。 失误率(用户规格 2025):主动失误率 = 自身技术基础(基础失误率×(1−t/100)^1.5,心理/体能/冒险修正) + 绝对属性差距项(正降负加):自己绝对 ≥61 每分差距 0.85%、50-60 每分 1.0%、40-50 每分 1.25%、0-40 每分 1.5%(对手总评−自己总评)。全局上限 70%(平衡机制:1200 新手打明显强者时"10个自杀7,8个"),下限 0.3%(现实记录)。1200 打 1200 差距项=0,不会全失误。 ② 物理生成阶段(反推+模拟):由目标落点反推出球速度(纯重力估算 v_h=L/t_f、v_z=(z_T−z0+½gt²)/t_f,含过网约束与马格努斯有效重力)→ 2-3 次 RK4 短模拟迭代校准(残差 ≤5cm)→ 将出球状态交给物理引擎,RK4 完整飞行(阻力/马格努斯/弹跳)裁决。 循环:击球 → 够球判定(线性曲线)→ 对手击球。失误率与落点完全由属性决定;离拍后轨迹完全物理。安全阈值:球速 ≤16 m/s(常规)/20(扣杀)、失误率 ≥0.3%、落点散布 ≥0.02 rad、有效属性 ≤100。 （原"拍面角+经验压拍"实现已废弃:碰撞微观过程由反推取代,见开发日志 16） 4.3旧 意图生成+物理裁决(击球核心,_strike)

1 技术选择(策略表/机会球/博弈) → 2 冒险度risk → 3 接发判断(首拍:判断准确率=接发判断/100×(1-隐蔽×0.5)×rand)
→ 4 主动失误roll(基础失误率×(1-技术/100)×心理×体能×风险) → 5 意图:
   swing=基础×(0.6+0.6·技/100)×(0.8+0.4·爆/100)×状态×risk×疲劳惩罚
   目标仰角=射程公式(平均Magnus修正)+过网约束+经验压拍(上旋来球摩擦抬vz→压拍 atan((2/7)·R·ω/v)×技术精度)
   发力控制:出球速度≤可行上限v_max(二分,保证"过网且落台内"的最大速度;含迎面来球借力)
→ 6 拍面误差±err(属性决定) → 7 racket.collide → RK4飞行 → 触台/撞网/出界/漏球 由引擎判定(不保证上台)。

4.4 失误模型

主动失误(非受迫)=概率roll+物理失误,只关自己属性(与对手级别无关)。
受迫失误=对手来球质量Q≥0.45压制(王0.87压李、李0.03压不动王、同级≈0.5部分受迫)。
物理失误=拍面误差把出球推出可行角度窗口(快球窗口窄→搏杀天然高失误)。
够球判定:P=1/(1+e^(-(步法分-来球难度)/8)),来球难度=球速×0.3+旋转×0.3+落点×0.4(各0-100)。
E-R-L:执行-应对+运气>10→敢打满速+擦边运气;<0→误差×1.5+低分失误概率。

5. 每一分的差距意味着什么

5.1 总评差 1 分

设计口径:总评差 1 分 ≈ 开球网差 20 分 ≈ 胜率 53%(ELO)。总评差 5 分 ≈ 胜率 60%,差 10 分 ≈ 70%,差 20 分 ≈ 80%+。

5.2 单项技术差 1 分(汇总,实测口径)

关键理解:技术属性同时作用 6 个出口(速度/转速/误差/失误率/质量/落点),单项+1 的单板收益约 0.5-1.5%,乘以每局 20-50 拍,对同水平对手的净胜率影响约 +0.5~1 个百分点。所以"差 1 分"单看微小,但"差 10 分 = 一个档次"是设计口径(与 FC 的"总评 +1 是大事、+5 是档次"同理)。

5.3 开球网差 100 分

ELO 预期胜率 64%。实测(新标定:青训绝对总评 60 vs 2200 业余绝对总评 54.8,差 5.2 分):约 6:4 开(10 场 8 胜、55.6% 分胜率),符合"总评差 5 分 ≈ 胜率 60%"口径;状态差(0.7)时约 55 开,低谷(0.5)可反转至 5:5。

5.4 初始球员 vs 各段对手(实测 3 种子,供校准参考)

6. 真实球员数据(主观标定,如何自己改)

6.1 怎么改(全部在 src/pros.gd)

const TOP20 := [
  {"name": "王楚钦", "nation": "中国", "rank": 1, "style": "进攻型", "grip": "横拍", "rubber": "反胶", "abs": 96.0},
  ...
]
每行改:abs=绝对属性中心(总分水平)、style=打法(决定AI战术+风格权重)、grip/rubber=器材。
生成时按 abs ±2 分散到 54 项,核心打法属性再 +4。
世界排名→绝对属性映射(abs_by_rank)也在同文件,想改梯度就改它。
赛事对手段(tournament.gd LEVELS 的 opp_rank)决定各赛事遇到的世界排名区间。

6.2 FC 式定制的建议落点

FC 的"总评=多小项加权、每项影响比赛行为"我们已经具备;要更精细可加:正手/反手/中路倾向、步法覆盖半径、比赛风格徽章树、潜力动态上限、伤病恢复时间等(当前隐藏属性只做了 5 项基础版)。

7. 开发日志

附:参数手册

详细参数手册(所有公式/常量/属性作用点/调参入口):参数手册.html —— 含物理常量表、属性→物理公式(swing/转速/落点散布/失误率/质量/接发)、比赛引擎判定(发球/够球/目标导向击球)、思维链、徽章、平衡实测与调参速查表。

附:测试与运行

cd /root/1234/tt-physics
./run.sh                                        # 启动游戏(Linux)
godot --headless --path . --script res://tests/run_XXX.gd   # 9 套件:
run_tests(物理37) run_match_tests(比赛52) run_rating_test(评分19) run_state_test(状态25)
run_career_test(生涯19) run_interactive_test(回合制4) run_ui_test(UI流程8)
run_scale_test(双标尺19) run_tour_test(赛事17)
Windows 版下载:https://theparadiseoftabletennis.art/ttcareer/ttcareer-windows.zip

—— 文档完。所有公式与数值均可在 src/ 源码与 tests/ 断言中逐条核对 ——