summer-engine 3.1.0 → 3.2.0

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()

package/library/skills/character-movement/references/movement-3d.md

@@ -0,0 +1,136 @@
+# 3D Controllers: First + Third Person
+
+Both build on the minimal 3D walk in SKILL.md. The difference is entirely the
+camera rig and how look rotation is split across nodes.
+
+## First-person node layout (non-negotiable)
+
+```
+Player (CharacterBody3D)          # yaw (horizontal look) rotates THIS
+  CollisionShape3D                # CapsuleShape3D, radius 0.35, height 1.8
+  Head (Node3D)                   # y = 1.5; pitch (vertical look) rotates THIS
+    Camera3D                      # fov 70-75
+      WeaponHolder (Node3D)       # weapons/tools ride here
+```
+
+Yaw on the body, pitch on the Head. Never pitch the body (gimbal lock + physics
+tilt). Camera is a child of Head so it inherits both rotations.
+
+```gdscript
+extends CharacterBody3D
+
+@export var speed: float = 5.0
+@export var sprint_speed: float = 8.0
+@export var jump_velocity: float = 4.5
+@export var mouse_sensitivity: float = 0.002
+
+@onready var head: Node3D = $Head
+var gravity: float = ProjectSettings.get_setting("physics/3d/default_gravity")
+
+func _ready() -> void:
+	Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
+
+func _unhandled_input(event: InputEvent) -> void:
+	if event is InputEventMouseMotion:
+		rotate_y(-event.relative.x * mouse_sensitivity)
+		head.rotate_x(-event.relative.y * mouse_sensitivity)
+		head.rotation.x = clampf(head.rotation.x, -PI / 2.0, PI / 2.0)
+	if event.is_action_pressed("ui_cancel"):
+		Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
+
+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 cur_speed := sprint_speed if Input.is_action_pressed("sprint") else speed
+	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 * cur_speed
+		velocity.z = direction.z * cur_speed
+	else:
+		velocity.x = move_toward(velocity.x, 0.0, cur_speed)
+		velocity.z = move_toward(velocity.z, 0.0, cur_speed)
+	move_and_slide()
+```
+
+## Crouch
+
+Keep two collision shapes (standing + crouching), toggle `disabled`, and a
+`RayCast3D` pointing up (`CeilingCheck`) so you cannot stand up under a ceiling.
+Lerp the Head y from 1.5 to ~0.9 for a smooth crouch, not a snap.
+
+## Headbob (optional polish)
+
+Drive the Camera's local y with `sin(time * bob_freq) * bob_amp` scaled by
+horizontal speed, only while `is_on_floor()`. Keep amp under 0.08 or it nauseates.
+
+## Third-person node layout
+
+```
+Player (CharacterBody3D)
+  CharacterRotationRoot (Node3D)   # only this visual node yaws toward movement
+    character.tscn                  # normalized role-neutral visual package
+  CameraController (Node3D)
+    SpringArm3D                     # extends behind the -Z-facing visual on local +Z
+      Camera3D
+```
+
+The `SpringArm3D` is the whole trick: it raycasts from the pivot to the camera
+and shortens when a wall is in the way, so the camera never clips into geometry.
+Set its `collision_mask` to your Level layer only (not the player).
+
+Third-person differences from FPS:
+- Mouse motion rotates the `CameraController` (orbit), not the body.
+- The visual wrapper rotates to face the MOVEMENT direction, decoupled from the camera.
+  Because imported characters face Godot forward `-Z`, lerp
+  `CharacterRotationRoot.rotation.y` toward `atan2(-direction.x, -direction.z)`.
+- Rotate only `CharacterRotationRoot.rotation.y`. Do not yaw the CharacterBody3D or add a
+  compensating 180-degree model rotation. The package already normalizes forward to `-Z`.
+- Keep the third-person camera behind the character on the camera rig's local `+Z` side.
+- Camera direction drives movement basis: build `direction` from the spring-arm's
+  global basis, flattened to the XZ plane, so "forward" means "where the camera
+  looks".
+
+## Canonical humanoid animation states
+
+Keep translation in the controller and use package animations only as in-place visuals.
+For a standard playable third-person character, read and copy
+`default-third-person-controller.gd`. It already loads exact semantic roles
+from `character.json`, selects state after `move_and_slide()`, gives airborne
+Jump highest priority, changes clips only when state changes, uses camera-relative
+movement, and turns only the normalized `-Z` visual root. Do not reassemble the
+controller from partial examples.
+
+Do not advance the `CharacterBody3D` from animation root translation. Rotate only the
+visual child when movement is non-zero, and keep the last facing direction while idle.
+
+## Legacy clip-name compatibility only
+
+Use substring discovery only for old, non-package GLBs that have no manifest. Resolve Jump
+before Run and claim each real clip at most once. Never use this for a canonical package:
+
+```gdscript
+func resolve_legacy_roles(player: AnimationPlayer) -> Dictionary:
+	var result: Dictionary = {}
+	var used_clips: Dictionary = {}
+	for role in [&"jump", &"idle", &"walk", &"run"]: # Jump must precede Run.
+		for clip in player.get_animation_list():
+			if used_clips.has(clip):
+				continue
+			if String(clip).to_lower().contains(String(role)):
+				result[role] = clip
+				used_clips[clip] = true
+				break
+	return result
+```
+
+Validate every requested role after legacy resolution. Do not fall back from Jump to Walk
+or Run, and do not reuse one clip for multiple roles.
+
+## Shared traps
+
+- Capture/release the mouse as a pair or you trap the player (see SKILL.md).
+- Sprint reads an unbound `sprint` action = silent no-op; bind it first.
+- Spring arm with the wrong mask collides with the player and jams at length 0.

package/library/skills/character-movement/references/platformer-feel.md

@@ -0,0 +1,83 @@
+# Platformer Feel
+
+The base controller in SKILL.md runs, but a raw `is_on_floor()` jump feels stiff
+and unforgiving. These four additions are what separate a prototype from a game
+that feels good. Add them in this order; each is independent.
+
+## Coyote time
+
+Let the player jump for a few frames AFTER walking off a ledge. Without it, jumps
+near edges feel like the game ate the input.
+
+```gdscript
+@export var coyote_time: float = 0.1
+var _coyote_timer: float = 0.0
+
+func _physics_process(delta: float) -> void:
+	if not is_on_floor():
+		velocity.y += gravity * delta
+		_coyote_timer -= delta
+	else:
+		_coyote_timer = coyote_time
+	# jump check uses _coyote_timer > 0.0 instead of is_on_floor()
+```
+
+## Jump buffering
+
+If the player presses jump a few frames BEFORE landing, remember it and fire on
+touchdown. Without it, fast players feel like jumps get dropped.
+
+```gdscript
+@export var jump_buffer: float = 0.1
+var _buffer_timer: float = 0.0
+
+func _physics_process(delta: float) -> void:
+	if Input.is_action_just_pressed("jump"):
+		_buffer_timer = jump_buffer
+	_buffer_timer -= delta
+	if _buffer_timer > 0.0 and _coyote_timer > 0.0:
+		velocity.y = jump_velocity
+		_buffer_timer = 0.0
+		_coyote_timer = 0.0
+```
+
+## Variable jump height
+
+Tap = short hop, hold = full jump. Cut upward velocity when the button releases.
+
+```gdscript
+	if Input.is_action_just_released("jump") and velocity.y < 0.0:
+		velocity.y *= 0.4
+```
+
+## Asymmetric gravity (fall faster than you rise)
+
+A heavier fall gravity is the single biggest feel upgrade. Rising floaty, falling
+snappy reads as responsive.
+
+```gdscript
+@export var fall_multiplier: float = 1.6
+
+func _physics_process(delta: float) -> void:
+	var g := gravity * (fall_multiplier if velocity.y > 0.0 else 1.0)
+	if not is_on_floor():
+		velocity.y += g * delta
+```
+
+## One-way platforms
+
+Use a `CollisionPolygon2D`/`CollisionShape2D` on a platform with
+`one_way_collision = true` in the platform's collision shape. Drop through by
+briefly disabling the player's collision with that layer, or move the player to a
+lower collision layer while `move_down` is held.
+
+## Tuning starting points
+
+| Feel | speed | jump_velocity | gravity scale |
+|------|-------|---------------|---------------|
+| Tight/precise | 180 | -320 | 1.0 (fall 1.8) |
+| Floaty/explorer | 220 | -420 | 0.7 (fall 1.3) |
+| Fast/action | 300 | -380 | 1.0 (fall 2.0) |
+
+Never ship default gravity 980 with a -350 jump and call it done - that is the
+"why does my jump feel bad" default. Tune fall_multiplier first.

package/library/skills/character-movement/resource.yaml

@@ -0,0 +1,40 @@
+id: skill/character-movement
+kind: skill
+version: 1.2.1
+summary: "Player controllers for 2D and 3D, plus the canonical third-person controller for Summer humanoid packages: movement owns translation, clips follow state."
+use_when:
+  - building or fixing player movement — gravity, collision, side-scroller, top-down, or 3D walk
+  - wiring an imported Summer character package (character.tscn) as the playable third-person player
+  - walk, run, and jump animation states, facing, or mouse look for a player controller
+  - the jump feels bad — coyote time, jump buffering, variable jump height, one-way platforms
+do_not_use_when:
+  - a production first-person shooter controller with air control and external velocity — use fps-controller
+  - Celeste-style momentum precision platforming with dash and wall climb — use celeste-momentum-platforming
+facets:
+  lifecycle:
+    - build
+  domains:
+    - character-controller
+    - gameplay
+    - 2d
+    - 3d
+  modalities:
+    - scripts
+    - scenes
+    - animation
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/make-game
+    - skill/camera-rigs
+    - skill/combat-basics
+    - skill/fps-controller
+    - skill/celeste-momentum-platforming
+    - skill/character-animation-wiring
+    - skill/character-model
+    - skill/playtesting-a-feature
+source: official
+license: MIT
+status: preview
+recommended: false

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

@@ -1,6 +1,6 @@
 ---
 name: character-portrait
-description: Use when generating a single, polished bust/portrait of a character for dialogue UI, character-select screens, lore cards, or codex entries. One character, locked composition, VN-style. Trigger on "character portrait", "dialogue portrait", "VN portrait", "character bust", "headshot", "character select image", "lore card art".
+description: "Generate a single polished character bust for dialogue UI, character select, lore cards, or codex entries. One character, locked composition, VN-style."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

package/library/skills/cinematic-cutscene/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cinematic-cutscene
-description: Use when generating a non-interactive cutscene clip — opening scene, story beat, character intro, ending. Locks the look with a reference image, image-to-videos a 5-10s shot, optionally adds TTS dialogue, and wires it as a VideoStreamPlayer that fades in/out. Trigger on "cutscene", "intro cinematic", "opening scene", "ending cinematic", "story beat video", "character intro video", "in-engine cinematic", "non-playable scene".
+description: "Generate a non-interactive cutscene — reference-locked look, a 5-10s image-to-video shot, optional TTS dialogue — wired as a fading VideoStreamPlayer."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: video