diff --git a/.workbuddy/memory/2026-09-23.md b/.workbuddy/memory/2026-09-23.md index 6d31beb..b92e89a 100644 --- a/.workbuddy/memory/2026-09-23.md +++ b/.workbuddy/memory/2026-09-23.md @@ -86,3 +86,58 @@ - 与相机前向 `dot = 0.999` → 看到的是角色背面 ✅ - `body_rot_deg = 0`、位移 3.51 m（0.75s × 5 m/s）✅ +## 重构：动画状态机抽成 PlayerAnimator（与移动解耦） + +用户先问「动画状态机和玩家代码耦合吗」。结论：是**结构性耦合**（5 个点），但只有**单向** +—— `_update_animation()` 只读 `velocity`/`is_on_floor()`/`Input`，从不回写物理量。 +真实代价只有一条：这套状态机没法给 NPC 复用。用户选择抽成独立组件。 + +**新结构**（`character/player/player.tscn`）： + + Player (CharacterBody3D, player.gd) ← 输入 / 物理 / 相机 / 血条 / 联机分叉 + └─ Body ← 视觉层，换模型整棵替换 + ├─ PlayerAnimator (Node, player_animator.gd) ← 动作状态机 + └─ character-male-e2 / character-male-e / Skeleton3D + AnimationPlayer + +**接口只有一个**：`animator.set_motion(velocity, is_on_floor(), sprinting)`，在 +`move_and_slide()` 之后调用。控制器不认识任何片段名，动画器不认识输入。 +动画准备（补 loop、播 idle）搬到 `PlayerAnimator._ready()` —— 子节点先于父节点 ready， +所以 player.gd 的 `_ready()` 里不再需要任何动画代码。 + +**关键设计决定：片段基准速度属于片段，不属于控制器。** +`PlayerAnimator.walk_ref_speed = 5.0` / `sprint_ref_speed = 8.5` 语义是「这段动画在多少 +米/秒下按原速播」。控制器把 `walk_speed` 调到 6，动画自然播成 1.2 倍，两边不用同步改 —— +这才是真正解掉了耦合，而不是把常量搬个家。 + +**同步路径变了**：`Body/PlayerAnimator:anim_state` 与 `Body/PlayerAnimator:anim_speed` +（`Sync.root_path` 仍是 `..` 即 Player）。`anim_state` / `anim_speed` 现在是 +PlayerAnimator 的成员，player.gd 里已无这两个属性（测试里有一条专门守住这个边界）。 + +**`animation_player` 接线**：声明成 `@export var animation_player: AnimationPlayer`， +场景里留空（原因见下），`_ready()` 用 +`get_parent().find_child("AnimationPlayer", true, false)` 自动找。实机确认能解析。 + +**player.gd 306 → 206 行**；测试 5 → 7 条 / 154 断言，全过。 + +**实机验证**（game_eval，跑着的游戏里）： + +- `animator_node = /root/Main/1/Body/PlayerAnimator`，`auto_find_resolved = true` +- loop 模式 `[idle, walk, sprint, jump] = [LINEAR, LINEAR, LINEAR, NONE]` +- idle / walk@2.5(0.65) / walk@5(1.0) / sprint@8.5(1.0) / jump / fall 全部正确 +- `controller_drives_animator = [WALK, "walk", 1.0]` —— 控制器→动画器链路真的在跑 + +## 本轮新增的 MCP 坑 + +1. **`node_set_property` 设不了 Node 类型的属性。** 传 + `/Player/Body/character-male-e2/AnimationPlayer` 会报 + `VALUE_OUT_OF_RANGE: value: Path must start with res://, uid://, or user://` + —— 该工具只按「字符串=资源路径」加载。所以 `@export var x: AnimationPlayer` + 在场景里只能留空、靠代码兜底（或改用 `NodePath` 类型 export，那个能收字符串）。 +2. **`project_run` 会把编辑器当前场景切成主场景。** 跑完游戏再 `node_create` 会报 + `NODE_NOT_FOUND: Parent not found: /Player/Body. Scene root is "/Main"`。 + 写场景节点前先 `scene_open("res://character/player/player.tscn")`。 +3. **删掉某个脚本里的 enum/常量后，所有引用处会立刻刷一屏 parse error。** + 分步 patch 时这是正常的中间态，把引用清完 diagnostics 自动归零 —— 别当成自己写错了。 +4. **中文字符串用 `\uXXXX` 转义极易打错字**（本轮把「抽搐」打成「抽搝」、「照抄」打成 + 「照拄」，都要事后 grep 才发现）。直接传字面中文更稳。 + diff --git a/character/player/player.gd b/character/player/player.gd index 48ea314..e94f870 100644 --- a/character/player/player.gd +++ b/character/player/player.gd @@ -1,17 +1,19 @@ extends CharacterBody3D -## 第三人称控制器（胶囊体占位） +## 第三人称控制器：只管「怎么动」—— 输入、移动物理、相机、血条、联机分叉。 +## 表现层（动画）在 Body/PlayerAnimator 里，本文件不认识任何片段名。 ## ## 场景结构： ## Player (CharacterBody3D) ← 只负责移动与碰撞，自身不旋转 ## ├─ Collision (CollisionShape3D, CapsuleShape3D) ## ├─ Body (Node3D) ← 视觉层，朝移动方向转身；换角色模型时挂在它下面 +## │ ├─ PlayerAnimator (PlayerAnimator.gd) ← 动作状态机：只读运动、只写动画 ## │ └─ character-male-e2 (Node3D) ## │ ├─ character-male-e/Skeleton3D ← 骨骼 + 蒙皮网格（character-male-e.glb） -## │ └─ AnimationPlayer ← 动作库：idle / walk / sprint / jump / fall +## │ └─ AnimationPlayer ← 动作库，由 PlayerAnimator 驱动 ## ├─ CameraRig (Node3D) ← 承担偏航 yaw，独立于本体旋转 ## │ └─ SpringArm (SpringArm3D) ← 承担俯仰 pitch，自动避障 ## │ └─ Camera (Camera3D) -## ├─ Sync (MultiplayerSynchronizer) ← 同步 position、Body.rotation、health、anim_state、anim_speed +## ├─ Sync (MultiplayerSynchronizer) ← 同步 position、Body.rotation、health、动画状态 ## └─ HealthLabel (Label3D) ← 头顶血条（节点配置，不是代码建的） ## ## 操作：WASD/方向键移动，鼠标转视角，Shift 疾跑，空格跳跃，Esc 释放/锁定鼠标 @@ -19,22 +21,6 @@ extends CharacterBody3D ## 跳跃输入缓冲帧数（输入事件在渲染帧到达，物理帧读取，避免漏跳） const JUMP_BUFFER_FRAMES: int = 6 -## 角色动作状态。权威端每物理帧算一次，再靠 Sync 复制给远端回放。 -enum AnimState { IDLE, WALK, SPRINT, JUMP, FALL } - -## 状态 → 片段名。名字取自 character-male-e.glb 的动作库，改名要同步改这里。 -const ANIM_CLIPS: Dictionary = { - AnimState.IDLE: "idle", - AnimState.WALK: "walk", - AnimState.SPRINT: "sprint", - AnimState.JUMP: "jump", - AnimState.FALL: "fall", -} - -## 需要循环的状态。glb 里每个片段的 loop_mode 都是 NONE， -## 不补循环的话 idle/walk/sprint 播一遍就定在最后一帧。 -const ANIM_LOOPED: Array[int] = [AnimState.IDLE, AnimState.WALK, AnimState.SPRINT] - @export_group("属性") ## 血量 @export var health: int = 100: @@ -64,23 +50,14 @@ const ANIM_LOOPED: Array[int] = [AnimState.IDLE, AnimState.WALK, AnimState.SPRIN ## 最高仰角（向上看） @export var pitch_max_deg: float = 45.0 -@export_group("动画") -## 动作切换的交叉淡入时间（秒）。0 为硬切 -@export var anim_blend_time: float = 0.15 -## 低于此水平速度就视为站立（米/秒） -@export var anim_idle_threshold: float = 0.2 -## 播放倍率下限：被墙抵住、起步那一瞬，脚步不该慢到像在滑冰 -@export var anim_speed_scale_min: float = 0.65 -## 播放倍率上限：防止速度被外力拉高时脚步快到抽搐 -@export var anim_speed_scale_max: float = 1.6 - @onready var body: Node3D = $Body @onready var camera_rig: Node3D = $CameraRig @onready var spring_arm: SpringArm3D = $CameraRig/SpringArm ## 头顶血条是 player.tscn 里的 Label3D 节点（3D 世界里的文字，会跟着角色走） @onready var _health_label: Label3D = $HealthLabel -@onready var animation_player: AnimationPlayer = $"Body/character-male-e2/AnimationPlayer" +## 动画状态机（挂在 Body 下）。只把「运动结果」交给它，也只知道它会自己播动画。 +@onready var animator: PlayerAnimator = $Body/PlayerAnimator var _gravity: float = float(ProjectSettings.get_setting("physics/3d/default_gravity", 9.8)) var _yaw: float = 0.0 @@ -89,30 +66,10 @@ var _jump_buffer: int = 0 ## 本节点是否由本机玩家操控。由世界节点在生成时设置 authority 决定，见 world/main.gd。 var _is_local: bool = true -## 当前动作状态（AnimState）。 -## 权威端每物理帧写一次，Sync 把它复制给远端 —— 远端物理与输入都关着， -## 只有靠这个值才知道该播哪个片段。 -var anim_state: int = AnimState.IDLE: - set(value): - if anim_state == value: - return - anim_state = value - _apply_anim_state() - -## 当前播放倍率（1.0 = 片段原速）。 -## 同样要复制：远端只有 position，算不出真实速度，只能照抄权威端的倍率。 -var anim_speed: float = 1.0: - set(value): - value = clampf(value, anim_speed_scale_min, anim_speed_scale_max) - anim_speed = value - if animation_player != null: - animation_player.speed_scale = value - func _ready() -> void: _report_identity() - # 本地端与远端都要跑：本地端播自己的动作，远端靠复制来的 anim_state 回放 - _prepare_animation() + # 动画准备不在这里 —— PlayerAnimator 有自己的 _ready()，而子节点先于本节点 ready _is_local = is_multiplayer_authority() if not _is_local: # 远端玩家只是一具「回放身体」： @@ -200,7 +157,8 @@ func _physics_process(delta: float) -> void: move_and_slide() - _update_animation() + # 动画只读运动结果。控制器不认识任何片段名，动画器也不认识输入。 + animator.set_motion(velocity, is_on_floor(), Input.is_action_pressed("sprint")) func _refresh_health_label() -> void: @@ -211,63 +169,6 @@ func _refresh_health_label() -> void: _health_label.text = "HP %d / 100" % health -## 准备动作库。两个端点都要跑，且必须在本地/远端分支之前。 -func _prepare_animation() -> void: - if animation_player == null: - push_warning("%s 下没有 AnimationPlayer，角色不会有动画" % name) - return - for state in ANIM_LOOPED: - var clip: String = ANIM_CLIPS[state] - if not animation_player.has_animation(clip): - continue - animation_player.get_animation(clip).loop_mode = Animation.LOOP_LINEAR - # 先站在 idle。之后 state 不变时 setter 不会重进去，所以这一句不能省。 - animation_player.play(ANIM_CLIPS[AnimState.IDLE], 0.0) - - -## 权威端每物理帧调用：从本帧的真实运动推出动作状态与播放倍率。 -## 只读 velocity / is_on_floor()，不写任何物理量。 -func _update_animation() -> void: - var h_speed := Vector2(velocity.x, velocity.z).length() - - var next_state: int - if not is_on_floor(): - # 上升用 jump、越过顶点用 fall。jump 片段长 0.5s， - # 恰好约等于 jump_velocity 5 / 重力 9.8 的上升时间。 - next_state = AnimState.JUMP if velocity.y > 0.0 else AnimState.FALL - elif h_speed < anim_idle_threshold: - next_state = AnimState.IDLE - elif Input.is_action_pressed("sprint"): - next_state = AnimState.SPRINT - else: - next_state = AnimState.WALK - - # 先把倍率写下去，再切片段 —— 顺序反了会让新片段用一帧旧倍率。 - var ref := _anim_reference_speed(next_state) - anim_speed = h_speed / ref if ref > 0.0 else 1.0 - anim_state = next_state # setter 负责切片段 - - -## 该状态对应的「设计速度」。片段在 ref 速度下按 1.0 倍播放，快慢全靠比例缩。 -func _anim_reference_speed(state: int) -> float: - match state: - AnimState.WALK: - return walk_speed - AnimState.SPRINT: - return sprint_speed - _: - return 0.0 - - -func _apply_anim_state() -> void: - if animation_player == null: - return - var clip: String = ANIM_CLIPS.get(anim_state, "") - if clip.is_empty() or not animation_player.has_animation(clip): - return - animation_player.play(clip, anim_blend_time) - - ## 关卡 0 的临时自检：把「我这一端」和「这个节点」分层打印出来。 ## 联机框架调通后可以整段删掉（连同 _ready() 里的那一行调用）。 func _report_identity() -> void: diff --git a/character/player/player.tscn b/character/player/player.tscn index a7f55b5..7d36068 100644 --- a/character/player/player.tscn +++ b/character/player/player.tscn @@ -1,6 +1,7 @@ [gd_scene format=4 uid="uid://bekuuw153mv03"] [ext_resource type="Script" uid="uid://f5ptp3is4agf" path="res://character/player/player.gd" id="1_gtsfv"] +[ext_resource type="Script" uid="uid://roaqmma0vjon" path="res://character/player/player_animator.gd" id="3_g20gq"] [ext_resource type="Texture2D" uid="uid://cq3awe0wjqsih" path="res://character/player/assets/Textures/colormap.png" id="3_gtsfv"] [ext_resource type="SceneReplicationConfig" uid="uid://c4ubbxjfrrs47" path="res://character/player/player_sync.tres" id="3_wu8e1"] @@ -2796,6 +2797,9 @@ skeleton = NodePath("..") [node name="AnimationPlayer" type="AnimationPlayer" parent="Body/character-male-e2" unique_id=1443249442] libraries/ = SubResource("AnimationLibrary_muffn") +[node name="PlayerAnimator" type="Node" parent="Body" unique_id=390989323] +script = ExtResource("3_g20gq") + [node name="Sync" type="MultiplayerSynchronizer" parent="." unique_id=1979575210] replication_config = ExtResource("3_wu8e1") diff --git a/character/player/player_animator.gd b/character/player/player_animator.gd new file mode 100644 index 0000000..0351bfb --- /dev/null +++ b/character/player/player_animator.gd @@ -0,0 +1,154 @@ +extends Node +class_name PlayerAnimator +## 角色动作状态机 —— 只负责「把运动状态翻译成播放哪段动画」，完全不碰移动。 +## +## 挂在 Player/Body 下，与具体模型解耦：换角色模型只要在检视面板重新指定 +## animation_player（或让它自动找），代码里没有任何硬编码的节点路径。 +## +## 对外接口只有一个：set_motion()。方向、加速度、重力、输入全归控制器管； +## 本组件只读入一个「运动快照」，输出到 AnimationPlayer。反向不回写任何东西。 +## +## 为什么状态与倍率必须是可复制属性： +## 远端玩家物理与输入都关着，手里只有 position 和 Body.rotation， +## 算不出水平速度，也分不清是上升还是下落。所以权威端把结论复制过去， +## 远端只在 setter 里回放。 +## 对应的同步条目（Sync.root_path = ".."，即 Player 节点）： +## Body/PlayerAnimator:anim_state +## Body/PlayerAnimator:anim_speed + +## 角色动作状态。权威端每物理帧算一次，再靠 Sync 复制给远端回放。 +enum AnimState { IDLE, WALK, SPRINT, JUMP, FALL } + +## 状态 → 片段名。取自 character-male-e.glb 的动作库，换动作库改这里。 +const ANIM_CLIPS: Dictionary = { + AnimState.IDLE: "idle", + AnimState.WALK: "walk", + AnimState.SPRINT: "sprint", + AnimState.JUMP: "jump", + AnimState.FALL: "fall", +} + +## 需要循环的状态。glb 里每个片段的 loop_mode 都是 NONE， +## 不补循环的话 idle/walk/sprint 播一遍就定在最后一帧。 +const ANIM_LOOPED: Array[int] = [AnimState.IDLE, AnimState.WALK, AnimState.SPRINT] + +@export_group("接线") +## 要驱动的 AnimationPlayer。留空则在本节点的兄弟子树里自动找一个。 +## 换模型后这里重新指一下即可 —— 这也是它能脱离具体模型的原因。 +@export var animation_player: AnimationPlayer + +@export_group("播放") +## 动作切换的交叉淡入时间（秒）。0 为硬切 +@export var blend_time: float = 0.15 +## 低于此水平速度就视为站立（米/秒） +@export var idle_threshold: float = 0.2 +## 播放倍率下限：被墙抵住、起步那一瞬，脚步不该慢到像在滑冰 +@export var speed_scale_min: float = 0.65 +## 播放倍率上限：防止速度被外力拉高时脚步快到抽搐 +@export var speed_scale_max: float = 1.6 + +@export_group("片段基准速度") +## walk 片段在多少米/秒下按 1.0 倍播放。这是片段自身的属性，不是控制器的手感参数： +## 控制器把跑速调到 6 m/s 时，这段动画自然播成 1.2 倍，脚步自动跟上，无需同步改两边。 +@export var walk_ref_speed: float = 5.0 +## sprint 片段的基准速度（米/秒） +@export var sprint_ref_speed: float = 8.5 + +## 当前动作状态（AnimState）。权威端每物理帧写一次，Sync 复制给远端。 +var anim_state: int = AnimState.IDLE: + set(value): + if anim_state == value: + return + anim_state = value + _play(ANIM_CLIPS.get(anim_state, ""), blend_time) + +## 当前播放倍率（1.0 = 片段原速）。 +## 同样要复制：远端只有 position，算不出真实速度，只能照抄权威端的倍率。 +var anim_speed: float = 1.0: + set(value): + value = clampf(value, speed_scale_min, speed_scale_max) + anim_speed = value + if animation_player != null: + animation_player.speed_scale = value + + +func _ready() -> void: + if animation_player == null: + animation_player = _auto_find_animation_player() + if animation_player == null: + push_warning("%s 没绑定 AnimationPlayer，角色不会有动画" % get_path()) + return + _patch_loop_modes() + # 同步可能在 _ready() 之前就把 anim_state 写进来了 —— 那时 animation_player 还是 null， + # setter 空跑了一趟。所以这里按「当前状态」补播一遍，不能写死 idle。 + _play(ANIM_CLIPS.get(anim_state, ""), 0.0) + + +# ---------------- 对外接口 ---------------- + +## 控制器每物理帧调用一次（放在 move_and_slide() 之后）。 +## 只读入运动快照，不回写任何物理量 —— 这就是「单向耦合」的边界。 +func set_motion(velocity: Vector3, on_floor: bool, sprinting: bool = false) -> void: + var state := _resolve_state(velocity, on_floor, sprinting) + # 先写倍率再切片段 —— 顺序反了会让新片段用一帧旧倍率。 + anim_speed = _speed_scale_for(state, velocity) + anim_state = state # setter 负责切片段 + + +## 当前正在播的片段名。调试与测试用。 +func current_clip() -> String: + if animation_player == null: + return "" + return str(animation_player.current_animation) + + +# ---------------- 内部 ---------------- + +func _resolve_state(velocity: Vector3, on_floor: bool, sprinting: bool) -> int: + if not on_floor: + # 上升用 jump、越过顶点用 fall。jump 片段长 0.5s， + # 恰好约等于 jump_velocity 5 / 重力 9.8 的上升时间。 + return AnimState.JUMP if velocity.y > 0.0 else AnimState.FALL + if Vector2(velocity.x, velocity.z).length() < idle_threshold: + return AnimState.IDLE + return AnimState.SPRINT if sprinting else AnimState.WALK + + +## 播放倍率 = 实际水平速度 / 该片段的基准速度。 +## 只有循环的移动动作参与缩放，跳跃/下落/站立一律原速。 +func _speed_scale_for(state: int, velocity: Vector3) -> float: + var ref := 0.0 + match state: + AnimState.WALK: + ref = walk_ref_speed + AnimState.SPRINT: + ref = sprint_ref_speed + _: + return 1.0 + if ref <= 0.0: + return 1.0 + return Vector2(velocity.x, velocity.z).length() / ref + + +func _play(clip: String, blend: float) -> void: + if animation_player == null or clip.is_empty(): + return + if not animation_player.has_animation(clip): + return + animation_player.play(clip, blend) + + +## 兜底：在同一层视觉节点里找一个 AnimationPlayer。只在没接线时生效。 +func _auto_find_animation_player() -> AnimationPlayer: + var parent := get_parent() + if parent == null: + return null + return parent.find_child("AnimationPlayer", true, false) as AnimationPlayer + + +func _patch_loop_modes() -> void: + for state in ANIM_LOOPED: + var clip: String = ANIM_CLIPS[state] + if not animation_player.has_animation(clip): + continue + animation_player.get_animation(clip).loop_mode = Animation.LOOP_LINEAR diff --git a/character/player/player_animator.gd.uid b/character/player/player_animator.gd.uid new file mode 100644 index 0000000..70603b0 --- /dev/null +++ b/character/player/player_animator.gd.uid @@ -0,0 +1 @@ +uid://roaqmma0vjon diff --git a/character/player/player_sync.tres b/character/player/player_sync.tres index 17b3085..8942569 100644 --- a/character/player/player_sync.tres +++ b/character/player/player_sync.tres @@ -10,9 +10,9 @@ properties/1/replication_mode = 1 properties/2/path = NodePath(".:health") properties/2/spawn = true properties/2/replication_mode = 1 -properties/3/path = NodePath(".:anim_state") +properties/3/path = NodePath("Body/PlayerAnimator:anim_state") properties/3/spawn = true properties/3/replication_mode = 1 -properties/4/path = NodePath(".:anim_speed") +properties/4/path = NodePath("Body/PlayerAnimator:anim_speed") properties/4/spawn = true properties/4/replication_mode = 1 diff --git a/tests/test_net_replication.gd b/tests/test_net_replication.gd index 2c29166..5baec7f 100644 --- a/tests/test_net_replication.gd +++ b/tests/test_net_replication.gd @@ -1,19 +1,23 @@ @tool extends McpTestSuite -## 回归测试：Player 的同步配置与动作库必须真的被解析。 +## 回归测试：Player 的同步配置、动作库，以及「移动 / 表现」的组件边界。 ## -## 两处典型的「静默失效」： -## 1. player_sync.tres 键名写错 / replication_mode 落到 NEVER -## → 远端玩家僵在原地，而且不打任何错误。 -## 2. 动作库是从 .glb 拷进来的，track 路径带一层 character-male-e/ 前缀。 -## 一旦模型换名、层级变动、蒙皮骨骼改名，AnimationPlayer 会「有片段但什么都播不出来」， -## 同样不报错。 +## 三处典型的「静默失效」——都表现为「人站着不动」且不打任何错误： +## 1. player_sync.tres 键名写错 / replication_mode 落到 NEVER → 远端收不到字段； +## 2. track 路径带一层模型目录名前缀，换模型/改层级后整组失效； +## 3. glb 片段的 loop_mode 默认是 NONE，idle/walk/sprint 播一遍就定在最后一帧。 +## （loop 由 PlayerAnimator._ready() 在运行时补，编辑器测试覆盖不到，靠实机验证。） const CONFIG_PATH := "res://character/player/player_sync.tres" const PLAYER_SCENE_PATH := "res://character/player/player.tscn" + +## 从 player.gd 抽出来的动画状态机。控制器只通过它间接驱动动画。 +const ANIMATOR_PATH := "Body/PlayerAnimator" +const ANIMATOR_SCRIPT := "res://character/player/player_animator.gd" +## 真正干活的动画器。PlayerAnimator 没接线时按这个名字在自己兄弟子树里找它。 const ANIM_PLAYER_PATH := "Body/character-male-e2/AnimationPlayer" -## player.gd 的 ANIM_CLIPS 写死了这几个名字，少一个对应状态就会静默不动。 +## player_animator.gd 的 ANIM_CLIPS 写死了这几个名字，少一个对应状态就会静默不动。 const REQUIRED_CLIPS: Array[String] = ["idle", "walk", "sprint", "jump", "fall"] ## 必须被复制到远端的字段。远端物理与输入都关着，全靠这几个值回放。 @@ -21,8 +25,8 @@ const REQUIRED_SYNCED: Array[String] = [ ".:position", "Body:rotation", ".:health", - ".:anim_state", - ".:anim_speed", + "Body/PlayerAnimator:anim_state", + "Body/PlayerAnimator:anim_speed", ] @@ -54,7 +58,7 @@ func test_config_replication_mode_is_always() -> void: assert_eq( config.property_get_replication_mode(path), SceneReplicationConfig.REPLICATION_MODE_ALWAYS, - "%s 的 replication_mode 不是 ALWAYS（改为 NEVER 会静默断掉同步）" % path + "%s 的 replication_mode 不是 ALWAYS（改成 NEVER 会静默断掉同步）" % path ) @@ -76,6 +80,49 @@ func test_player_scene_wires_synchronizer() -> void: ) +## 组件边界：动画状态机必须是挂在 Body 下的独立节点，而不是塞回 player.gd。 +## 有人把 anim_state / anim_speed 挪回控制器时，这条会失败。 +func test_player_scene_has_animator_component() -> void: + var player := _instantiate_player() + if player == null: + return + var animator := player.get_node_or_null(ANIMATOR_PATH) + assert_true(animator != null, "Player 下缺少 %s（动画状态机应独立于 player.gd）" % ANIMATOR_PATH) + var player_script: Script = player.get_script() + assert_true(player_script != null, "Player 没有挂脚本") + if player_script != null: + var member_names: Array[String] = [] + for member in player_script.get_script_property_list(): + member_names.append(str(member.get("name"))) + assert_false(member_names.has("anim_state"), "anim_state 应该留在 PlayerAnimator 上，不该回到 player.gd") + assert_false(member_names.has("anim_speed"), "anim_speed 应该留在 PlayerAnimator 上，不该回到 player.gd") + if animator == null: + return + var script: Script = animator.get_script() + assert_true(script != null, "%s 没有挂脚本" % ANIMATOR_PATH) + if script != null: + assert_eq(script.resource_path, ANIMATOR_SCRIPT, "%s 挂的不是动画状态机脚本" % ANIMATOR_PATH) + + +## PlayerAnimator 没接线时按名字在自己兄弟子树里找 AnimationPlayer。 +## 编辑器里跑不了它的 _ready()（非 @tool 脚本），所以这里退一步、用同样的规则找一遍： +## 改名或挪位置会让这条失败。 +func test_animator_auto_find_target_exists() -> void: + var player := _instantiate_player() + if player == null: + return + var body := player.get_node_or_null("Body") + assert_true(body != null, "Player 下缺少 Body") + if body == null: + return + var found := body.find_child("AnimationPlayer", true, false) as AnimationPlayer + assert_true(found != null, "Body 子树里找不到名为 AnimationPlayer 的节点，PlayerAnimator 的自动接线会失败") + assert_true( + player.get_node_or_null(ANIM_PLAYER_PATH) != null, + "动画器不在预期路径 %s" % ANIM_PLAYER_PATH + ) + + func test_required_animation_clips_exist() -> void: var anim_player := _find_animation_player() if anim_player == null: @@ -83,7 +130,7 @@ func test_required_animation_clips_exist() -> void: for clip in REQUIRED_CLIPS: assert_true( anim_player.has_animation(clip), - "动作库里缺少片段 %s（player.gd 的 ANIM_CLIPS 会指向不存在的片段）" % clip + "动作库里缺少片段 %s（PlayerAnimator 的 ANIM_CLIPS 会指向不存在的片段）" % clip ) @@ -98,7 +145,6 @@ func test_animation_track_paths_resolve() -> void: if root == null: return - # 逐帧验证 5 个要用到的片段，任何一个 track 断了都会让该动作失效 for clip in REQUIRED_CLIPS: var anim := anim_player.get_animation(clip) if anim == null: @@ -123,12 +169,6 @@ func test_animation_track_paths_resolve() -> void: ) -## 直接用 load() 拿到的是编辑器进程里的内存副本 —— 外部刚改过磁盘时它可能还是旧的， -## 测试会因此假绿或假红。这里强制按磁盘重读，断言的是文件本身。 -func _load_config() -> SceneReplicationConfig: - return ResourceLoader.load(CONFIG_PATH, "", ResourceLoader.CACHE_MODE_REPLACE) as SceneReplicationConfig - - func _find_animation_player() -> AnimationPlayer: var player := _instantiate_player() if player == null: @@ -138,6 +178,12 @@ func _find_animation_player() -> AnimationPlayer: return anim_player +## 直接用 load() 拿到的是编辑器进程里的内存副本 —— 外部刚改过磁盘时它可能还是旧的， +## 测试会因此假绿或假红。这里强制按磁盘重读，断言的是文件本身。 +func _load_config() -> SceneReplicationConfig: + return ResourceLoader.load(CONFIG_PATH, "", ResourceLoader.CACHE_MODE_REPLACE) as SceneReplicationConfig + + func _instantiate_player() -> Node: var packed := load(PLAYER_SCENE_PATH) as PackedScene assert_true(packed != null, "%s 未能加载" % PLAYER_SCENE_PATH)