summer-engine 3.0.0 → 3.2.0

package/library/skills/character-movement/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: character-movement
+description: "Player controllers for 2D and 3D, plus the canonical third-person controller for Summer humanoid packages: movement owns translation, clips follow state."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
+category: character-controllers
+user-invocable: false
+allowed-tools: Read Grep summer_read_file summer_write_file summer_replace_text summer_get_scene_tree summer_add_node summer_set_prop summer_batch summer_input_map_bind summer_save_scene summer_get_script_errors summer_get_diagnostics summer_play summer_stop
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# Character Movement
+
+The player controller is the first thing you build and the thing the user feels
+in the first 3 seconds. Ship the smallest correct controller, then tune feel.
+
+Trigger phrases: "add player movement", "the player can't move / falls through
+the floor", "wire my imported character as the player", "walk/run/jump
+animations", "mouse look", "make the jump feel better".
+
+Supporting files live in this skill's `references/` folder, next to this
+SKILL.md. Open only the one the task needs:
+
+| File | Read when |
+|------|-----------|
+| `references/default-third-person-controller.gd` | standard playable third-person Summer humanoid package; copy this exact controller instead of rewriting it |
+| `references/default-third-person-verification-probe.gd` | runtime proof for that controller; pass it unchanged as a `RunVerification` `probe_source` |
+| `references/platformer-feel.md` | jump feels bad, coyote time, jump buffering, variable jump height, one-way platforms |
+| `references/movement-3d.md` | FPS/third-person controllers, mouse look, sprint, crouch, spring-arm camera |
+
+## Default playable Summer character
+
+For a standard playable third-person Summer humanoid package, install this
+skill's `references/default-third-person-controller.gd` unchanged as the player
+script. Do not rewrite or reconstruct it from the snippets below. Customize the
+installed file only when the user explicitly asks for different controls or
+behavior.
+
+Install it byte-exact:
+
+1. Take the full text of `references/default-third-person-controller.gd` from
+   this skill's folder, unchanged (tabs, comments and all).
+2. New destination:
+   `summer_write_file(path="res://scripts/player.gd", content=<that text>, create_only=true)`.
+   Existing destination: `summer_read_file(path="res://scripts/player.gd")`
+   first, then `summer_write_file(path=..., content=<that text>, expected_sha256=<sha256 from the read>)`.
+3. Confirm the copy is exact: the write receipt's sha256 must equal the sha256
+   of the source file (hash it locally when you have a shell; otherwise
+   `summer_read_file` the result and compare it to the source text).
+
+Do not edit the installed file, add roles, or add an `AnimationTree` merely
+because the user selected more package clips: choosing clips is not a request
+to customize controls or behavior. When the user does explicitly request
+different controls or behavior, install the exact canonical source first, then
+`summer_read_file` the installed project file and change it with
+`summer_replace_text`. Configure the manifest path and node paths on the scene
+instance.
+
+Required main-scene shape:
+
+```text
+Main (Node3D)
+  Player (CharacterBody3D)               # template script
+    CollisionShape3D                     # capsule
+    CharacterRotationRoot (Node3D)       # only this node turns
+      Character                          # imported character.tscn instance
+    CameraYaw (Node3D)
+      CameraPitch (Node3D)
+        SpringArm3D
+          Camera3D                       # current = true
+  Ground / level geometry                # world siblings of Player
+  DirectionalLight3D / WorldEnvironment
+```
+
+When authoring a new main scene as `.tscn` text (written whole with
+`summer_write_file`, never a hand edit of a scene open in the editor), use this
+exact serialization pattern. Replace only the imported package paths when they
+differ:
+
+```text
+[gd_scene load_steps=7 format=3]
+
+[ext_resource type="Script" path="res://scripts/player.gd" id="1_controller"]
+[ext_resource type="PackedScene" path="res://characters/imported/character.tscn" id="2_character"]
+
+[sub_resource type="CapsuleShape3D" id="PlayerCapsule"]
+radius = 0.45
+height = 1.8
+
+[sub_resource type="BoxShape3D" id="GroundShape"]
+size = Vector3(20, 0.5, 20)
+
+[sub_resource type="BoxMesh" id="GroundMesh"]
+size = Vector3(20, 0.5, 20)
+
+[sub_resource type="Environment" id="WorldEnvironment"]
+background_mode = 1
+background_color = Color(0.12, 0.18, 0.3, 1)
+ambient_light_energy = 0.6
+
+[node name="Main" type="Node3D"]
+
+[node name="Player" type="CharacterBody3D" parent="."]
+position = Vector3(0, 1, 0)
+script = ExtResource("1_controller")
+character_manifest_path = "res://characters/imported/character.json"
+
+[node name="CollisionShape3D" type="CollisionShape3D" parent="Player"]
+shape = SubResource("PlayerCapsule")
+
+[node name="CharacterRotationRoot" type="Node3D" parent="Player"]
+
+[node name="Character" parent="Player/CharacterRotationRoot" instance=ExtResource("2_character")]
+
+[node name="CameraYaw" type="Node3D" parent="Player"]
+
+[node name="CameraPitch" type="Node3D" parent="Player/CameraYaw"]
+rotation = Vector3(-0.349066, 0, 0)
+
+[node name="SpringArm3D" type="SpringArm3D" parent="Player/CameraYaw/CameraPitch"]
+spring_length = 5.0
+
+[node name="Camera3D" type="Camera3D" parent="Player/CameraYaw/CameraPitch/SpringArm3D"]
+current = true
+
+[node name="Ground" type="StaticBody3D" parent="."]
+position = Vector3(0, -0.25, 0)
+
+[node name="MeshInstance3D" type="MeshInstance3D" parent="Ground"]
+mesh = SubResource("GroundMesh")
+
+[node name="CollisionShape3D" type="CollisionShape3D" parent="Ground"]
+shape = SubResource("GroundShape")
+
+[node name="DirectionalLight3D" type="DirectionalLight3D" parent="."]
+rotation_degrees = Vector3(-55, -30, 0)
+shadow_enabled = true
+
+[node name="WorldEnvironment" type="WorldEnvironment" parent="."]
+environment = SubResource("WorldEnvironment")
+```
+
+Every nested `parent` is the complete path from the scene root, excluding the
+root node's own name. Never shorten
+`parent="Player/CameraYaw/CameraPitch"` to `parent="CameraPitch"`. A
+`PackedScene` instance belongs in the `[node ...]` header and has no `type`;
+never write a typed `Node3D` followed by `instance = ExtResource(...)` in the
+node body. The playable body is a child of the world root. Ground, level
+geometry, lights, and environment remain siblings of `Player`, never children
+of it, so they do not move with the player.
+
+Set `character_manifest_path` to the imported package's `character.json`. Bind
+`move_left`, `move_right`, `move_forward`, `move_back`, `jump`, and `sprint`
+before running, one `summer_input_map_bind` per action (e.g.
+`summer_input_map_bind(name="move_forward", events=[{"type": "key", "key": "W"}])`);
+`ui_cancel` is a built-in action — confirm it is still bound. The controller
+asserts every one of them at `_ready`. Do not attach this template during generic import or
+to an NPC unless the user explicitly asks for player-style control.
+
+The default camera has horizontal mouse orbit only. `CameraPitch` is set once to
+a modest downward angle and vertical mouse motion does not change it. The
+controller keeps a short floor snap plus a small downward grounded velocity so
+ordinary horizontal movement does not create a false airborne `Jump` state. It
+also records the spawn point and respawns after falling below `respawn_below_y`.
+
+A bind T/A-pose survives every static check: the AnimationPlayer is wired, the
+clip is named `Idle`, and the files on disk all read correctly. Only a running
+frame separates that from a character actually at rest.
+
+**Runtime proof.** Read this skill's
+`references/default-third-person-verification-probe.gd` and pass its full text
+unchanged as the `probe_source` of a `RunVerification` op, which runs it in a
+hidden, disposable game instance that never touches the editor:
+
+```
+summer_batch(ops=[{"op": "RunVerification", "max_seconds": 30, "probe_source": "<the probe file, unchanged>"}])
+```
+
+The probe samples the live Skeleton3D after
+the player reaches the floor, requires the real resting clip to be named `Idle`,
+verifies that its pose actually changes, rejects an idle whose hands remain level
+with the upper arms like a bind T/A-pose, saves separate idle and moving frames,
+verifies W moves toward world `-Z`, and verifies vertical mouse input leaves
+camera pitch unchanged. Every boolean in `results` must be `true`; open the saved
+idle and moving frames listed in `frames` before you describe them. A `false` is
+a finding to fix, not a flaky probe.
+
+**If the probe cannot run** (the op returns `ok: false` with a `failure_reason`
+such as `spawn_failed`, or the engine build lacks the op), the runtime question
+belongs to the user. Do not paste the probe into the project. Finish on the
+saved state: the manifest path written into the
+Player node, the four semantic roles present, CameraYaw at identity and
+CameraPitch at its fixed angle in the `.tscn` text, the InputMap actions bound,
+and clean diagnostics. Then tell the user which idle clip should be playing at
+rest, so it is the first thing they look at on Play. That is a complete
+integration handed off for a playtest, not an incomplete one.
+
+## Order of operations
+
+1. Root node must be `CharacterBody2D` or `CharacterBody3D`. `move_and_slide()`
+   only exists on these. RigidBody is for physics props, not players.
+2. Give it a `CollisionShape2D/3D` with a real shape (CapsuleShape for 3D humans,
+   RectangleShape/CapsuleShape2D for 2D). No shape = falls through everything.
+3. Read gravity from project settings, never hardcode it, so tuning one value
+   fixes the whole game: `ProjectSettings.get_setting("physics/2d/default_gravity")`.
+4. Bind input actions BEFORE the script references them (`move_left`, `jump`, ...).
+   Referencing an unbound action is a silent no-op that reads as "controls dead".
+5. Compile-check, then run and watch it move. Feel is a user call, not a still frame.
+
+## 2D side-scroller controller (the 40% every 2D game shares)
+
+```gdscript
+extends CharacterBody2D
+
+@export var speed: float = 200.0
+@export var jump_velocity: float = -350.0   # negative = up in 2D
+
+var gravity: float = ProjectSettings.get_setting("physics/2d/default_gravity")
+
+func _physics_process(delta: float) -> void:
+	if not is_on_floor():
+		velocity.y += gravity * delta
+	if Input.is_action_just_pressed("jump") and is_on_floor():
+		velocity.y = jump_velocity
+	var dir := Input.get_axis("move_left", "move_right")
+	velocity.x = dir * speed if dir else move_toward(velocity.x, 0.0, speed)
+	move_and_slide()
+```
+
+Flip the sprite with `$Sprite2D.flip_h = velocity.x < 0` only when `velocity.x != 0`.
+For real platformer feel (coyote time, jump buffer, variable height) load
+`references/platformer-feel.md`.
+
+## Top-down controller (RPG / twin-stick / survivors)
+
+No gravity. 8-directional, normalize so diagonals are not faster.
+
+```gdscript
+extends CharacterBody2D
+
+@export var speed: float = 220.0
+
+func _physics_process(_delta: float) -> void:
+	var dir := Input.get_vector("move_left", "move_right", "move_up", "move_down")
+	velocity = dir * speed
+	move_and_slide()
+```
+
+Survivors-style games with 200+ agents: enemies are `Area2D` moved with
+`position += dir * speed * delta`, NOT physics bodies. See the `make-game`
+skill's `../make-game/references/2d-survivors.md`. The PLAYER stays a CharacterBody2D.
+
+## 3D controller (first + third person)
+
+Both share the same body + gravity + `Input.get_vector` floor logic. The only
+difference is where the camera lives and how look rotation is applied. Full
+first-person and third-person controllers, mouse look, sprint, crouch, and
+spring-arm setup are in `references/movement-3d.md` - load it for any 3D player.
+
+Minimal 3D walk (no look yet):
+
+```gdscript
+extends CharacterBody3D
+
+@export var speed: float = 5.0
+@export var jump_velocity: float = 4.5
+var gravity: float = ProjectSettings.get_setting("physics/3d/default_gravity")
+
+func _physics_process(delta: float) -> void:
+	if not is_on_floor():
+		velocity.y -= gravity * delta
+	if Input.is_action_just_pressed("jump") and is_on_floor():
+		velocity.y = jump_velocity
+	var input_dir := Input.get_vector("move_left", "move_right", "move_forward", "move_back")
+	var direction := (transform.basis * Vector3(input_dir.x, 0.0, input_dir.y)).normalized()
+	if direction:
+		velocity.x = direction.x * speed
+		velocity.z = direction.z * speed
+	else:
+		velocity.x = move_toward(velocity.x, 0.0, speed)
+		velocity.z = move_toward(velocity.z, 0.0, speed)
+	move_and_slide()
+```
+
+## Summer humanoid package
+
+When the player visual is a Summer character package:
+
+1. Produce or import the package first — it comes from the shared character
+   pipeline (`character-model`; `summer_generate_3d` with rigging and animations)
+   and carries `character.tscn` plus its `character.json` manifest. Instantiate
+   `character.tscn`; for clip wiring without this controller see
+   `character-animation-wiring`.
+2. Put the normalized wrapper under a `CharacterBody3D`; do not modify the package or
+   scale the body.
+3. Let controller velocity and `move_and_slide()` own all scene translation. Idle, Walk,
+   Run, and Jump are in-place visual clips; never add their root motion to velocity.
+4. Resolve the four clips from `character.json` semantic roles instead of guessing names.
+   Require every requested role; never substitute one role for another.
+5. Select one state from physics: airborne -> Jump, stopped -> Idle, moving -> Walk,
+   sprinting -> Run. Airborne Jump has highest priority and never falls back to Walk/Run.
+   Change clips only when the state changes, so Jump plays once per takeoff.
+6. Rotate the visual child toward non-zero movement while preserving the normalized
+   `-Z` forward axis. Turn only visual yaw; do not rotate the collision body merely to
+   turn the mesh. Keep the third-person camera behind the visual on local `+Z`.
+
+Do not put player controls into the generation pipeline or generic character importer.
+
+## Camera-follow basics
+
+- 2D: add a `Camera2D` as a CHILD of the player (it is active while `enabled`,
+  the default), `position_smoothing_enabled = true`, speed 5-8. Add
+  `limit_left/right/top/bottom` so it never shows past the level edge. Full rigs
+  in the `camera-rigs` skill.
+- 3D first-person: camera is a child of a `Head` node; yaw rotates the body,
+  pitch rotates the Head (never the body) to avoid gimbal lock.
+- 3D third-person: camera on a `SpringArm3D` so walls push it in. See `camera-rigs`.
+
+## Traps
+
+- Scaling the CharacterBody node breaks collision + velocity. Scale the MESH/Sprite
+  child instead. In 3D, 1 unit = 1 meter; a human is ~1.0-2.0 tall.
+- `is_on_floor()` is only valid AFTER `move_and_slide()` ran once this frame.
+- Diagonal speed-up = you forgot to normalize the input vector.
+- Mouse captured with no release traps the user. Always pair
+  `Input.MOUSE_MODE_CAPTURED` with a `ui_cancel` handler that sets it VISIBLE.

package/library/skills/character-movement/references/default-third-person-controller.gd

@@ -0,0 +1,201 @@
+class_name SummerThirdPersonController
+extends CharacterBody3D
+
+## Canonical controller for a playable Summer humanoid character package.
+## Copy this file unchanged first. Customize the copy only when the user asks.
+
+const REQUIRED_ROLES: Array[StringName] = [&"idle", &"walk", &"run", &"jump"]
+const REQUIRED_ACTIONS: Array[StringName] = [
+	&"move_left",
+	&"move_right",
+	&"move_forward",
+	&"move_back",
+	&"jump",
+	&"sprint",
+	&"ui_cancel",
+]
+
+@export_file("*.json") var character_manifest_path: String
+
+@export_category("Movement")
+@export var walk_speed: float = 4.0
+@export var run_speed: float = 7.0
+@export var acceleration: float = 24.0
+@export var jump_velocity: float = 5.5
+@export var turn_speed: float = 12.0
+@export var floor_snap_distance: float = 0.3
+@export var floor_stick_velocity: float = 0.5
+
+@export_category("Camera")
+@export var mouse_sensitivity: float = 0.002
+@export var camera_height: float = 1.5
+@export var camera_distance: float = 4.5
+@export_flags_3d_physics var camera_collision_mask: int = 1
+@export var camera_pitch_degrees: float = -20.0
+
+@export_category("Respawn")
+@export var respawn_below_y: float = -15.0
+
+@export_category("Required Nodes")
+@export_node_path("Node3D") var visual_root_path: NodePath = ^"CharacterRotationRoot"
+@export_node_path("Node3D") var camera_yaw_path: NodePath = ^"CameraYaw"
+@export_node_path("Node3D") var camera_pitch_path: NodePath = ^"CameraYaw/CameraPitch"
+@export_node_path("SpringArm3D") var spring_arm_path: NodePath = ^"CameraYaw/CameraPitch/SpringArm3D"
+@export_node_path("AnimationPlayer") var animation_player_path: NodePath = ^"CharacterRotationRoot/Character/Visual/AnimationPlayer"
+
+@onready var _visual_root: Node3D = get_node(visual_root_path) as Node3D
+@onready var _camera_yaw: Node3D = get_node(camera_yaw_path) as Node3D
+@onready var _camera_pitch: Node3D = get_node(camera_pitch_path) as Node3D
+@onready var _spring_arm: SpringArm3D = get_node(spring_arm_path) as SpringArm3D
+@onready var _animation_player: AnimationPlayer = get_node(animation_player_path) as AnimationPlayer
+
+var _gravity: float = 0.0
+var _spawn_position: Vector3
+var _clips_by_role: Dictionary = {}
+var _active_role: StringName = &""
+
+
+func _ready() -> void:
+	_validate_scene_contract()
+	_gravity = float(ProjectSettings.get_setting("physics/3d/default_gravity"))
+	_spawn_position = global_position
+	floor_snap_length = floor_snap_distance
+	_camera_yaw.position.y = camera_height
+	_camera_pitch.rotation = Vector3(deg_to_rad(camera_pitch_degrees), 0.0, 0.0)
+	_spring_arm.spring_length = camera_distance
+	_spring_arm.collision_mask = camera_collision_mask
+	_spring_arm.add_excluded_object(get_rid())
+	_configure_character_animation()
+	_play_role(&"idle")
+	Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
+
+
+func _unhandled_input(event: InputEvent) -> void:
+	if event.is_action_pressed(&"ui_cancel"):
+		Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
+		return
+	if event is InputEventMouseButton and event.pressed and event.button_index == MOUSE_BUTTON_LEFT:
+		Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
+	if Input.mouse_mode != Input.MOUSE_MODE_CAPTURED:
+		return
+	if event is InputEventMouseMotion:
+		_camera_yaw.rotate_y(-event.screen_relative.x * mouse_sensitivity)
+
+
+func _physics_process(delta: float) -> void:
+	var was_on_floor := is_on_floor()
+	if was_on_floor:
+		# A small downward velocity keeps the body snapped to flat and gently
+		# descending floors instead of producing a one-frame false airborne state.
+		velocity.y = -floor_stick_velocity
+	else:
+		velocity.y -= _gravity * delta
+	if Input.is_action_just_pressed(&"jump") and was_on_floor:
+		velocity.y = jump_velocity
+
+	var input_vector: Vector2 = Input.get_vector(
+		&"move_left",
+		&"move_right",
+		&"move_forward",
+		&"move_back"
+	)
+	var camera_forward: Vector3 = -_camera_yaw.global_transform.basis.z
+	var camera_right: Vector3 = _camera_yaw.global_transform.basis.x
+	camera_forward.y = 0.0
+	camera_right.y = 0.0
+	camera_forward = camera_forward.normalized()
+	camera_right = camera_right.normalized()
+	var movement_direction: Vector3 = (
+		camera_right * input_vector.x + camera_forward * -input_vector.y
+	)
+	if movement_direction.length_squared() > 1.0:
+		movement_direction = movement_direction.normalized()
+
+	var is_sprinting: bool = Input.is_action_pressed(&"sprint")
+	var target_speed: float = run_speed if is_sprinting else walk_speed
+	var target_velocity: Vector3 = movement_direction * target_speed
+	velocity.x = move_toward(velocity.x, target_velocity.x, acceleration * delta)
+	velocity.z = move_toward(velocity.z, target_velocity.z, acceleration * delta)
+
+	move_and_slide()
+	_turn_visual_toward(movement_direction, delta)
+	_update_animation_state(is_sprinting)
+	if global_position.y < respawn_below_y:
+		global_position = _spawn_position
+		velocity = Vector3.ZERO
+		_play_role(&"idle")
+
+
+func _validate_scene_contract() -> void:
+	assert(_visual_root != null, "Missing CharacterRotationRoot")
+	assert(_camera_yaw != null, "Missing CameraYaw")
+	assert(_camera_pitch != null, "Missing CameraPitch")
+	assert(_spring_arm != null, "Missing SpringArm3D")
+	assert(_animation_player != null, "Missing character AnimationPlayer")
+	assert(character_manifest_path != "", "Set character_manifest_path")
+	for action in REQUIRED_ACTIONS:
+		assert(InputMap.has_action(action), "Missing input action: %s" % action)
+
+
+func _configure_character_animation() -> void:
+	var file := FileAccess.open(character_manifest_path, FileAccess.READ)
+	assert(file != null, "Missing character manifest: %s" % character_manifest_path)
+	var manifest = JSON.parse_string(file.get_as_text())
+	assert(manifest is Dictionary, "Invalid character manifest JSON")
+	assert(manifest.get("status") == "ready", "Character package is not ready")
+	assert(
+		manifest.get("normalization", {}).get("forwardAxis") == "-Z",
+		"Character package forward axis must be -Z"
+	)
+
+	for entry in manifest.get("animations", []):
+		if not entry is Dictionary:
+			continue
+		var role := StringName(String(entry.get("semanticRole", "")).to_lower())
+		if role not in REQUIRED_ROLES:
+			continue
+		var clip := StringName(String(entry.get("name", "")))
+		assert(clip != &"", "Requested character role has no clip: %s" % role)
+		assert(not _clips_by_role.has(role), "Ambiguous character role: %s" % role)
+		assert(_animation_player.has_animation(clip), "Manifest clip is not playable: %s" % clip)
+		_clips_by_role[role] = clip
+
+	for role in REQUIRED_ROLES:
+		assert(_clips_by_role.has(role), "Missing requested character role: %s" % role)
+	for role in [&"idle", &"walk", &"run"]:
+		_animation_player.get_animation(_clips_by_role[role]).loop_mode = Animation.LOOP_LINEAR
+	_animation_player.get_animation(_clips_by_role[&"jump"]).loop_mode = Animation.LOOP_NONE
+
+
+func _update_animation_state(is_sprinting: bool) -> void:
+	var horizontal_speed := Vector2(velocity.x, velocity.z).length()
+	var next_role: StringName
+	if not is_on_floor():
+		next_role = &"jump"
+	elif horizontal_speed <= 0.05:
+		next_role = &"idle"
+	elif is_sprinting:
+		next_role = &"run"
+	else:
+		next_role = &"walk"
+	_play_role(next_role)
+
+
+func _play_role(role: StringName) -> void:
+	assert(_clips_by_role.has(role), "Missing requested character role: %s" % role)
+	if role == _active_role:
+		return
+	_animation_player.play(_clips_by_role[role])
+	# Apply the first keyed pose immediately. This prevents a visible bind-pose
+	# frame while the AnimationPlayer waits for its next process tick.
+	_animation_player.advance(0.0)
+	_active_role = role
+
+
+func _turn_visual_toward(direction: Vector3, delta: float) -> void:
+	if direction.length_squared() <= 0.0001:
+		return
+	var local_direction: Vector3 = global_transform.basis.inverse() * direction
+	var target_yaw := atan2(-local_direction.x, -local_direction.z)
+	var weight := 1.0 - exp(-turn_speed * delta)
+	_visual_root.rotation.y = lerp_angle(_visual_root.rotation.y, target_yaw, weight)

package/library/skills/character-movement/references/default-third-person-verification-probe.gd

@@ -0,0 +1,154 @@
+extends SummerProbeBase
+
+## Runtime proof for the canonical playable humanoid controller.
+## Pass this source unchanged as the probe_source of a RunVerification op:
+##   summer_batch(ops=[{"op": "RunVerification", "max_seconds": 30, "probe_source": <this file>}])
+##
+## If RunVerification cannot run, this file is not part of your job: finish on
+## the saved state and hand the playtest to the user. Do not paste this into a
+## script, a scene, or the project.
+## Saved frames come back in the result's `frames`; every reported boolean must
+## be true.
+
+
+func _find_first(node: Node, type_name: StringName) -> Node:
+	if node.is_class(type_name):
+		return node
+	for child in node.get_children():
+		var found := _find_first(child, type_name)
+		if found != null:
+			return found
+	return null
+
+
+func _pose_delta(before: Transform3D, after: Transform3D) -> float:
+	var translation_delta := before.origin.distance_to(after.origin)
+	var rotation_delta := before.basis.get_rotation_quaternion().angle_to(
+		after.basis.get_rotation_quaternion()
+	)
+	return maxf(translation_delta, rotation_delta)
+
+
+func _arm_down_ratio(
+	skeleton: Skeleton3D,
+	upper_arm_name: StringName,
+	hand_name: StringName
+) -> float:
+	var upper_arm_index := skeleton.find_bone(upper_arm_name)
+	var hand_index := skeleton.find_bone(hand_name)
+	if upper_arm_index < 0 or hand_index < 0:
+		return -1.0
+	var upper_arm_position := skeleton.get_bone_global_pose(upper_arm_index).origin
+	var hand_position := skeleton.get_bone_global_pose(hand_index).origin
+	var arm_vector := hand_position - upper_arm_position
+	if arm_vector.length_squared() <= 0.000001:
+		return -1.0
+	return (upper_arm_position.y - hand_position.y) / arm_vector.length()
+
+
+func _ready() -> void:
+	await super._ready()
+	await settle(20)
+
+	var scene := get_tree().current_scene
+	var player := _find_first(scene, &"CharacterBody3D") as CharacterBody3D
+	report("player_exists", player != null)
+	if player == null:
+		finish()
+		return
+
+	# Fresh scenes commonly spawn the capsule above the platform. Sampling after
+	# a fixed 20 frames can catch the initial Jump clip and falsely call it idle.
+	# Wait a bounded amount for real floor contact, then give the controller one
+	# short state transition window before measuring the resting animation.
+	for frame_index in 120:
+		if player.is_on_floor():
+			break
+		await settle(1)
+	report("idle_grounded", player.is_on_floor())
+	await settle(12)
+
+	var animation_player := _find_first(player, &"AnimationPlayer") as AnimationPlayer
+	var skeleton := _find_first(player, &"Skeleton3D") as Skeleton3D
+	report("animation_player_exists", animation_player != null)
+	report("skeleton_exists", skeleton != null)
+	if animation_player == null or skeleton == null:
+		finish()
+		return
+
+	var idle_animation := String(animation_player.current_animation)
+	report("idle_animation", idle_animation)
+	report(
+		"idle_named",
+		idle_animation == "Idle" or idle_animation.ends_with("/Idle")
+	)
+	report("idle_playing", animation_player.is_playing())
+
+	var before: Array[Transform3D] = []
+	for bone_index in skeleton.get_bone_count():
+		before.append(skeleton.get_bone_global_pose(bone_index))
+	await settle(24)
+	var maximum_pose_delta := 0.0
+	for bone_index in skeleton.get_bone_count():
+		maximum_pose_delta = maxf(
+			maximum_pose_delta,
+			_pose_delta(
+				before[bone_index],
+				skeleton.get_bone_global_pose(bone_index)
+			)
+		)
+	report("idle_pose_delta", maximum_pose_delta)
+	report("idle_moves_skeleton", maximum_pose_delta > 0.0001)
+
+	var left_arm_down_ratio := _arm_down_ratio(
+		skeleton,
+		&"LeftArm",
+		&"LeftHand"
+	)
+	var right_arm_down_ratio := _arm_down_ratio(
+		skeleton,
+		&"RightArm",
+		&"RightHand"
+	)
+	var idle_arm_bones_exist := (
+		left_arm_down_ratio >= 0.0 and right_arm_down_ratio >= 0.0
+	)
+	var idle_arms_relaxed := (
+		idle_arm_bones_exist
+		and minf(left_arm_down_ratio, right_arm_down_ratio) > 0.2
+		and (left_arm_down_ratio + right_arm_down_ratio) * 0.5 > 0.55
+	)
+	report("idle_arm_bones_exist", idle_arm_bones_exist)
+	report("idle_left_arm_down_ratio", left_arm_down_ratio)
+	report("idle_right_arm_down_ratio", right_arm_down_ratio)
+	report("idle_arms_relaxed", idle_arms_relaxed)
+	await save_frame("canonical-third-person-idle")
+
+	var camera_pitch := player.get_node_or_null("CameraYaw/CameraPitch") as Node3D
+	report("camera_pitch_exists", camera_pitch != null)
+	if camera_pitch != null:
+		var pitch_before := camera_pitch.rotation
+		var vertical_mouse := InputEventMouseMotion.new()
+		vertical_mouse.relative = Vector2(0.0, 160.0)
+		player._unhandled_input(vertical_mouse)
+		report(
+			"vertical_mouse_keeps_fixed_pitch",
+			camera_pitch.rotation.is_equal_approx(pitch_before)
+		)
+
+	var start_position := player.global_position
+	Input.action_press(&"move_forward")
+	await settle(24)
+	var moving_animation := animation_player.current_animation
+	var moving_position := player.global_position
+	Input.action_release(&"move_forward")
+	report("forward_progress", start_position.z - moving_position.z)
+	report("forward_moves_toward_minus_z", moving_position.z < start_position.z)
+	report("locomotion_animation", moving_animation)
+	report(
+		"locomotion_animation_active",
+		moving_animation == "Walk" or moving_animation == "Run"
+	)
+
+	await save_frame("canonical-third-person-moving")
+	finish()