feat(emotes): five dances, built like animation, behind a radial dial

The shared clip library ships exactly one `Dance_Loop`, and five copies of one
clip is not five dances. What the runtime does have is a procedural pose layer
over a real skeleton with spring-driven hair and cloth, which is enough — if
the motion is constructed the way an animator would construct it rather than
the way a programmer reaches for first.

Wiring sine waves to bones is that first reach, and everyone can tell. A raw
sine moves fastest through the middle and slowest at the ends by the same
amount on every channel, all in phase, forever. It floats. It has no weight, no
accent, and no sense that one part of the body is driving and the rest is
following. Four principles fix it, and all four are cheap:

  OVERLAP        the body is a chain. Hips lead, spine follows a beat later,
                 head last. One subtraction — `beat - lag * i` — and the spring
                 solver then carries it out through the hair and skirt for free,
                 because the dance layer runs before it.
  ACCENT         a dance HITS poses. `shape` bends the wave so it hangs at the
                 extremes and snaps between them, which is what a key-and-
                 breakdown pass produces by hand.
  WEIGHT         the HIPS translate, not just rotate. A body that never leaves
                 its own axis reads as a puppet on a stick.
  CONTRAST       Robot deliberately breaks all of the above — zero lag,
                 quantised motion — and reads as mechanical precisely because
                 the other four do not.

Spin spots its head: it holds a heading against the turn and whips round to
catch up, which is what a real dancer does to keep from getting dizzy and the
most recognisable thing about a turn.

The dial is a radial menu because every option is then the SAME DISTANCE from
where the pointer starts — the choice is a direction, and a direction becomes
muscle memory in a way "the fourth row down" does not. Selection is by ANGLE
alone, so a flick and a careful nudge do the same thing. HOLD to open, release
to commit; a tap too short to have aimed replays the last emote, which is what
the button did before, so the old habit still works. Pressing while already
dancing just stops — having to aim at something in order to STOP would be the
most annoying possible way to build this.

debug/dance_check.gd asserts the overlap, and getting it to measure that took
four wrong measurements, each of which is now a comment where it was made:

  - correlating the hips' TRANSLATION against the head's position relative to
    them compared two different quantities at different periods; it ranked the
    Robot, whose lag is zero by construction, as the most overlapped routine.
  - a signed scalar `angle * sign of the axis's largest component` is
    DISCONTINUOUS — as a rocking bone passes back through rest the axis flips —
    so smooth Two-Step measured a full-range jump per frame, which is exactly
    what quantised motion looks like.
  - a bone's GLOBAL rotation carries every ancestor's, so the head correlates
    with the hips at lag zero however delayed the head itself is.
  - and the hips and head are driven by different channels anyway.

Measuring two links of the SAME chain, as local rotation vectors, agrees with
the authored lag: Spin measures 9 frames against 8.4 authored, Two-Step 7
against 6.6, Robot 0. The Robot is checked on the property it actually has —
its jump per frame is 0.41 of its range against 0.03-0.06 for the others.

RigRoles is pulled out of ShooterPoseModifier so the dance layer resolves bones
the same way rather than carrying a second copy. Two copies is how a rig ends up
animating correctly under one modifier and not the other.

spawn smoke 0 failures, 11/11 movement, 21/21 weapon-hold pairs, contrast 108/108.

Co-Authored-By: Claude Opus 5 <[email protected]>

characters/dance_modifier.gd

@@ -0,0 +1,239 @@
+extends SkeletonModifier3D
+class_name DanceModifier
+
+## Drives a dance routine onto the skeleton, over whatever clip is playing.
+##
+## Runs AFTER the shooter pose layer and blends over it, so starting a dance
+## takes the arms off the weapon smoothly rather than cutting, and stopping one
+## hands them back the same way. The spring solver runs after both, so hair and
+## cloth follow the dance without anything being asked to make that happen.
+##
+## The routine data — and the reasoning behind why the motion is built the way it
+## is — lives in characters/dance_routines.gd. This is the machine that plays it.
+
+## The routine to play. See DanceRoutines.ROUTINES.
+var routine: Dictionary = {}
+## 0..1. Eased by the owner, so a dance fades in and out rather than snapping.
+var weight: float = 0.0
+## `<model>.rig.json` roles, for bone resolution. See RigRoles.
+var roles: Dictionary = {}
+
+var _idx: Dictionary = {}
+var _resolved := false
+var _t: float = 0.0
+
+## Per-link overlap, in seconds, from the hips outward. Index 0 is the hips.
+const CHAIN := ["DEF-hips", "DEF-spine.001", "DEF-spine.002", "DEF-spine.003"]
+
+
+func _process_modification() -> void:
+	var skel := get_skeleton()
+	if skel == null or weight <= 0.001 or routine.is_empty():
+		return
+	if not _resolved:
+		_idx = RigRoles.resolve(skel, roles)
+		_resolved = true
+
+	var delta := get_physics_process_delta_time() if Engine.is_in_physics_frame() \
+		else get_process_delta_time()
+	_t += delta
+
+	var bpm: float = float(routine.get("bpm", 100.0))
+	var beat := _t * bpm / 60.0
+	var lag: float = float(routine.get("lag", 0.05)) * bpm / 60.0
+	var w := weight
+
+	# ── Hips: the driver ────────────────────────────────────────────────────
+	#
+	# Translated, not just rotated. A body that never leaves its own axis reads
+	# as a puppet on a stick; moving the hips is what makes the legs look like
+	# they are carrying someone, and every other channel below is a reaction to
+	# this one.
+	var swing := _wave(beat, 2.0, 0.0)
+	var bob := _wave(beat, float(routine.get("hip_bob_beats", 1.0)), 0.25)
+	var hips: int = _idx.get("DEF-hips", -1)
+	if hips >= 0:
+		# Character-right is -X in skeleton space, up is +Y.
+		var offset := Vector3(-swing * float(routine.get("hip_swing", 0.0)),
+			bob * float(routine.get("hip_bob", 0.0)), 0.0) * w
+		_offset_bone(skel, hips, offset)
+		_add_space(skel, hips,
+			Quaternion(Vector3(0, 0, 1), swing * float(routine.get("hip_roll", 0.0)) * w)
+			* Quaternion(Vector3(0, 1, 0), swing * float(routine.get("hip_yaw", 0.0)) * w)
+			* Quaternion(Vector3(1, 0, 0), bob * float(routine.get("hip_pitch", 0.0)) * w))
+
+	# ── Spine: the same motion, later ───────────────────────────────────────
+	#
+	# Each link reads the wave at `beat - lag * i`, which is the whole of
+	# overlapping action. It is one subtraction and it is the difference between
+	# a rig oscillating and a person moving.
+	var counter: float = float(routine.get("spine_counter", 0.0))
+	var links := CHAIN.slice(1)
+	var n := maxf(links.size(), 1)
+	for i in links.size():
+		var b: int = _idx.get(links[i], -1)
+		if b < 0:
+			continue
+		var at := beat - lag * float(i + 1)
+		var s := _wave(at, 2.0, 0.0)
+		var v := _wave(at, float(routine.get("hip_bob_beats", 1.0)), 0.25)
+		var q := Quaternion(Vector3(0, 0, 1),
+				s * float(routine.get("spine_roll", 0.0)) * w / n) \
+			* Quaternion(Vector3(0, 1, 0),
+				(s * float(routine.get("spine_yaw", 0.0))
+					- s * float(routine.get("hip_yaw", 0.0)) * counter) * w / n) \
+			* Quaternion(Vector3(1, 0, 0),
+				v * float(routine.get("spine_pitch", 0.0)) * w / n)
+		_add_space(skel, b, q)
+
+	_head(skel, beat, lag, w)
+	_arms(skel, beat, lag, w)
+	_legs(skel, beat, w)
+
+
+## Head and neck: the last link in the chain, and the one carrying the spot.
+func _head(skel: Skeleton3D, beat: float, lag: float, w: float) -> void:
+	var at := beat - lag * float(CHAIN.size())
+	var s := _wave(at, 2.0, 0.0)
+	var v := _wave(at, float(routine.get("hip_bob_beats", 1.0)), 0.25)
+
+	var yaw: float = s * float(routine.get("head_yaw", 0.0))
+
+	# SPOTTING. A dancer turning keeps their head pointed at one place for as
+	# long as they can, then whips it round to catch up. It is what stops them
+	# getting dizzy, and it is the single most recognisable thing about a turn —
+	# a head that simply rotates with the shoulders reads as a mannequin on a
+	# turntable.
+	#
+	# So this is not a wave. The head COUNTERS the body's yaw exactly while the
+	# hold lasts, then releases over a short window and lets the neck catch up.
+	var spot: float = float(routine.get("spot", 0.0))
+	if spot > 0.001:
+		var body_yaw: float = s * float(routine.get("hip_yaw", 0.0)) \
+			+ s * float(routine.get("spine_yaw", 0.0))
+		# Where in the two-beat turn we are, 0..1.
+		var u := fposmod(at / 2.0, 1.0)
+		# Hold for the first 70%, then whip round over the next 20%, then arrive.
+		var hold := 1.0 - smoothstep(0.70, 0.90, u)
+		yaw -= body_yaw * spot * hold
+
+	var q := Quaternion(Vector3(0, 1, 0), yaw * w) \
+		* Quaternion(Vector3(0, 0, 1), s * float(routine.get("head_roll", 0.0)) * w) \
+		* Quaternion(Vector3(1, 0, 0),
+			(v * float(routine.get("head_bob", 0.0))
+				+ v * float(routine.get("head_pitch", 0.0))) * w)
+	# Split, so the whole column leans rather than the skull hinging off a rigid
+	# neck.
+	_add_space(skel, _idx.get("DEF-neck", -1), Quaternion.IDENTITY.slerp(q, 0.4))
+	_add_space(skel, _idx.get("DEF-head", -1), Quaternion.IDENTITY.slerp(q, 0.6))
+
+
+## Arms: out from the body, swinging in opposition, elbows folding on the beat.
+##
+## The two arms are half a cycle apart, which is what opposition is. Both read
+## the wave later than the spine did, so the hands are the last thing to arrive —
+## the end of the chain, where overlap is most visible.
+func _arms(skel: Skeleton3D, beat: float, lag: float, w: float) -> void:
+	var at := beat - lag * float(CHAIN.size() + 1)
+	var beats: float = float(routine.get("arm_beats", 2.0))
+	var out: float = float(routine.get("arm_out", 0.0))
+	var swing: float = float(routine.get("arm_swing", 0.0))
+	var elbow: float = float(routine.get("elbow", 0.0))
+
+	for sign_i in 2:
+		var right := sign_i == 0
+		var side := 1.0 if right else -1.0
+		var s := _wave(at + (0.0 if right else beats * 0.5), beats, 0.0)
+		var ua: int = _idx.get("DEF-upper_arm." + ("R" if right else "L"), -1)
+		var fa: int = _idx.get("DEF-forearm." + ("R" if right else "L"), -1)
+		if ua >= 0:
+			# Character-right is -X, so a positive Z rotation lifts the LEFT arm
+			# and drops the right — hence the side flip. `out` is a static lift
+			# that the swing then rides on top of, which is what stops the arms
+			# from passing through the body at the bottom of the stroke.
+			_add_space(skel, ua,
+				Quaternion(Vector3(0, 0, 1), -side * (out + s * 0.35 * swing) * w)
+				* Quaternion(Vector3(1, 0, 0), s * swing * w))
+		if fa >= 0:
+			# The elbow only ever folds, never hyperextends: a signed wave here
+			# bends the forearm backwards through the joint on half of every
+			# cycle, which is the most obvious possible tell.
+			var fold := (0.5 + 0.5 * s) * elbow
+			_add_space(skel, fa, Quaternion(Vector3(1, 0, 0), fold * w))
+
+
+## Legs: knees absorbing the bob, out of phase with each other so the weight
+## visibly transfers from one to the other.
+func _legs(skel: Skeleton3D, beat: float, w: float) -> void:
+	var knee: float = float(routine.get("knee", 0.0))
+	if knee <= 0.001:
+		return
+	var beats: float = float(routine.get("hip_bob_beats", 1.0))
+	for sign_i in 2:
+		var right := sign_i == 0
+		var s := _wave(beat + (0.0 if right else beats * 0.5), beats, 0.25)
+		var thigh: int = _idx.get("DEF-thigh." + ("R" if right else "L"), -1)
+		var shin: int = _idx.get("DEF-shin." + ("R" if right else "L"), -1)
+		var bend := (0.5 + 0.5 * s) * knee
+		# Thigh forward and shin back by twice as much, so the foot stays roughly
+		# under the hip instead of the whole leg swinging out in front.
+		_add_space(skel, thigh, Quaternion(Vector3(1, 0, 0), -bend * 0.5 * w))
+		_add_space(skel, shin, Quaternion(Vector3(1, 0, 0), bend * w))
+
+
+# ── The wave ─────────────────────────────────────────────────────────────────
+
+
+## One channel's value at `beat`, in -1..1.
+##
+## `shape` bends a sine so it HANGS at the extremes and SNAPS between them, which
+## is what an animator's key-and-breakdown pass produces and what a raw sine
+## cannot. At shape 1 this is exactly `sin`; above it the curve gets punchier
+## while staying continuous and staying in -1..1, so no amount of shaping can
+## make a channel overshoot its authored amplitude.
+##
+## `steps` quantises the result instead, for the robot — the one routine whose
+## whole point is that it does NOT move like the others.
+func _wave(beat: float, beats: float, phase: float) -> float:
+	if beats <= 0.001:
+		return 0.0
+	var u := beat / beats + phase
+	var steps: int = int(routine.get("steps", 0))
+	if steps > 0:
+		# Hold a value for a whole step, then jump. Rounded rather than floored
+		# so the extremes are actually reached — a floor never returns +1.
+		return sin(TAU * (round(u * float(steps)) / float(steps)))
+	var s := sin(TAU * u)
+	var shape: float = float(routine.get("shape", 1.0))
+	if is_equal_approx(shape, 1.0):
+		return s
+	return signf(s) * pow(absf(s), 1.0 / shape)
+
+
+# ── Bone plumbing ────────────────────────────────────────────────────────────
+
+
+## Move a bone by an offset expressed in SKELETON space.
+##
+## A bone's pose position is in its PARENT's space, so the offset has to be
+## rotated out of skeleton space by the parent's rest basis first. Skipping that
+## sends the hips sideways in whatever direction the rig happens to have called
+## "x", which differs per character.
+func _offset_bone(skel: Skeleton3D, idx: int, offset: Vector3) -> void:
+	if idx < 0 or offset == Vector3.ZERO:
+		return
+	var parent := skel.get_bone_parent(idx)
+	var local := offset
+	if parent >= 0:
+		local = skel.get_bone_global_rest(parent).basis.inverse() * offset
+	skel.set_bone_pose_position(idx, skel.get_bone_rest(idx).origin + local)
+
+
+## Compose a skeleton-space rotation onto a bone's animated local pose. Same
+## contract as ShooterPoseModifier._add_space.
+func _add_space(skel: Skeleton3D, idx: int, q_space: Quaternion) -> void:
+	if idx < 0:
+		return
+	var b := skel.get_bone_global_rest(idx).basis.get_rotation_quaternion()
+	var local := b.inverse() * q_space * b
+	skel.set_bone_pose_rotation(idx, skel.get_bone_pose_rotation(idx) * local)

characters/dance_modifier.gd.uid

@@ -0,0 +1 @@
+uid://bab4y7ba0yl87

characters/dance_routines.gd

@@ -0,0 +1,204 @@
+extends Object
+class_name DanceRoutines
+
+## The five emotes, as data.
+##
+## They are procedural rather than authored clips because the shared animation
+## library ships exactly one `Dance_Loop`, and five copies of one clip is not
+## five dances. What the runtime DOES have is a working procedural pose layer
+## over a real skeleton with spring-driven hair and cloth, which is enough to
+## build a dance out of if the motion is constructed the way an animator would
+## construct it rather than the way a programmer reaches for first.
+##
+## ── Why not just wire sine waves to the bones ───────────────────────────────
+##
+## Because that is what "programmer animation" looks like, and everyone can tell.
+## A raw sine moves fastest through the middle and slowest at the ends by exactly
+## the same amount on every channel, all in phase, forever. The result floats. It
+## has no weight, no accent, and no sense that one part of the body is driving and
+## the rest is following.
+##
+## Four principles fix that, and all four are cheap:
+##
+##   OVERLAP        the body is a chain, and a chain does not move as one piece.
+##                  Hips lead, spine follows a beat later, chest later still,
+##                  head last. `lag` below is that, in seconds per link. It is
+##                  the single largest difference between "a rig oscillating"
+##                  and "a person moving", and the spring bones then carry it
+##                  out through the hair and the skirt for free.
+##   ACCENT         a dance HITS poses. `shape` bends the wave so it hangs at
+##                  the extremes and snaps between them — the same asymmetry a
+##                  key-and-breakdown pass produces by hand. `sin` is shape 1.0;
+##                  above that it gets punchier.
+##   WEIGHT         a body that never leaves its own axis reads as a puppet. Real
+##                  dances move the HIPS — side to side, up and down — and the
+##                  rest of the body reacts. `hip_swing` and `hip_bob` are
+##                  translations, not rotations, and they are what make the legs
+##                  look like they are carrying someone.
+##   ANTICIPATION   the counter-move before the move. Handled per routine by
+##                  running a channel at a fraction of a beat AHEAD of the one it
+##                  precedes, rather than by a separate mechanism.
+##
+## ── The shape of a routine ──────────────────────────────────────────────────
+##
+## Everything is derived from one `bpm`, so no two channels can drift apart no
+## matter how long the emote runs — which is the other thing that goes wrong when
+## channels are given independent frequencies that are not exact ratios.
+##
+## Channel amounts are radians (rotations) or metres (the two hip translations).
+## `beats` is how many beats that channel takes for one full cycle, so 2 is a
+## side-to-side that takes two beats to return, 1 is once per beat, and 0.5 is
+## twice per beat. Fractions of a beat are how a routine gets a cross-rhythm
+## without leaving the grid.
+
+## `id` is what gets networked, so these strings must stay stable.
+const ROUTINES := [
+	{
+		"id": "two_step",
+		"name": "Two-Step",
+		"icon": "♪",
+		"bpm": 104.0,
+		"lag": 0.055,
+		"shape": 1.35,
+		# The foundation step: weight rocks side to side, the shoulders counter
+		# the hips, the arms hang and swing off the shoulders a beat behind.
+		"hip_swing": 0.075,
+		"hip_bob": 0.022,
+		"hip_bob_beats": 1.0,
+		"hip_roll": 0.16,
+		"hip_yaw": 0.20,
+		"spine_roll": 0.13,
+		"spine_counter": 0.55,
+		"head_roll": 0.22,
+		"head_bob": 0.10,
+		"arm_swing": 0.55,
+		"arm_out": 0.42,
+		"arm_beats": 2.0,
+		"elbow": 0.75,
+		"knee": 0.30,
+	},
+	{
+		"id": "body_wave",
+		"name": "Body Wave",
+		"icon": "〜",
+		"bpm": 88.0,
+		# The whole point of this one is the lag: a wave travelling up the spine
+		# IS overlap, made visible. At 0.13 s per link the crest takes most of a
+		# beat to get from the hips to the head.
+		"lag": 0.13,
+		"shape": 1.15,
+		"hip_swing": 0.03,
+		"hip_bob": 0.045,
+		"hip_bob_beats": 2.0,
+		"hip_pitch": 0.26,
+		"spine_pitch": 0.30,
+		"spine_counter": 0.0,
+		"head_pitch": 0.22,
+		"head_roll": 0.06,
+		"arm_out": 0.85,
+		"arm_swing": 0.20,
+		"arm_beats": 4.0,
+		"elbow": 0.55,
+		"knee": 0.18,
+	},
+	{
+		"id": "robot",
+		"name": "Robot",
+		"icon": "▣",
+		"bpm": 112.0,
+		# No lag, and the motion is QUANTISED — see `steps`. Both are deliberate
+		# violations of everything above, and they work for exactly that reason:
+		# the robot reads as mechanical because the viewer has been shown four
+		# other routines that do not.
+		"lag": 0.0,
+		"shape": 1.0,
+		"steps": 4,
+		"hip_swing": 0.04,
+		"hip_bob": 0.012,
+		"hip_bob_beats": 1.0,
+		"hip_yaw": 0.30,
+		"spine_yaw": 0.34,
+		"spine_counter": 0.0,
+		"head_yaw": 0.42,
+		"arm_out": 1.05,
+		"arm_swing": 0.85,
+		"arm_beats": 2.0,
+		"elbow": 1.35,
+		"knee": 0.10,
+	},
+	{
+		"id": "bounce",
+		"name": "Bounce",
+		"icon": "▲",
+		"bpm": 128.0,
+		"lag": 0.035,
+		# The punchiest shape in the set. A bounce lives entirely in the accent:
+		# the body hangs at the top and slams through the bottom, which is a
+		# gravity read, and a plain sine cannot express it.
+		"shape": 2.2,
+		"hip_swing": 0.03,
+		"hip_bob": 0.070,
+		"hip_bob_beats": 1.0,
+		"hip_roll": 0.08,
+		"spine_pitch": 0.14,
+		"spine_counter": 0.30,
+		"head_bob": 0.16,
+		"head_roll": 0.10,
+		"arm_swing": 0.95,
+		"arm_out": 0.30,
+		"arm_beats": 1.0,
+		"elbow": 1.05,
+		# Deep knees. This is the routine where the legs do the work, and a bounce
+		# with straight legs looks like a character being shaken.
+		"knee": 0.85,
+	},
+	{
+		"id": "spin",
+		"name": "Spin",
+		"icon": "↻",
+		"bpm": 96.0,
+		"lag": 0.07,
+		"shape": 1.5,
+		"hip_swing": 0.05,
+		"hip_bob": 0.030,
+		"hip_bob_beats": 2.0,
+		"hip_yaw": 0.85,
+		"spine_yaw": 0.30,
+		"spine_counter": 0.0,
+		"spine_roll": 0.14,
+		# SPOTTING: the head holds its heading while the body turns under it, then
+		# whips round to catch up. It is what a real dancer does to keep from
+		# getting dizzy, and it is the most recognisable thing about a turn. See
+		# `spot` in DanceModifier — this is not a wave, it is a hold and a snap.
+		"spot": 1.0,
+		"head_yaw": 0.0,
+		"arm_out": 1.15,
+		"arm_swing": 0.25,
+		"arm_beats": 4.0,
+		"elbow": 0.35,
+		"knee": 0.22,
+	},
+]
+
+
+static func count() -> int:
+	return ROUTINES.size()
+
+
+## A routine by index, wrapped so an out-of-range network value cannot crash a
+## remote peer's model.
+static func get_routine(index: int) -> Dictionary:
+	if ROUTINES.is_empty():
+		return {}
+	return ROUTINES[posmod(index, ROUTINES.size())]
+
+
+static func name_of(index: int) -> String:
+	return String(get_routine(index).get("name", ""))
+
+
+static func index_of(id: String) -> int:
+	for i in ROUTINES.size():
+		if ROUTINES[i]["id"] == id:
+			return i
+	return 0

characters/dance_routines.gd.uid

@@ -0,0 +1 @@
+uid://8p4yow40ni8p

characters/rig_roles.gd

@@ -0,0 +1,56 @@
+extends Object
+class_name RigRoles
+
+## Canonical bone names -> this rig's actual bone indices.
+##
+## Pulled out of `ShooterPoseModifier._resolve` so the dance layer can use the
+## same resolution instead of carrying a second copy of it. Two copies is how a
+## rig ends up animating correctly under one modifier and not the other.
+##
+## Non-negotiable: never look a bone up by name. `tools/rig_map.py` resolves
+## every rig to ROLES and writes them to the `<model>.rig.json` sidecar, and this
+## reads that. The name fallback below exists only for a model with no sidecar,
+## and it must never be the first thing tried — four characters could not hold a
+## gun because of exactly one hardcoded spelling.
+
+## The library skeleton's spine, hips first. A rig that kept its own names maps
+## onto this through the sidecar's `spine` chain.
+const SPINE := ["DEF-hips", "DEF-spine.001", "DEF-spine.002", "DEF-spine.003"]
+
+## Everything either pose layer asks for.
+const CANONICAL := SPINE + ["DEF-neck", "DEF-head",
+	"DEF-upper_arm.R", "DEF-forearm.R", "DEF-hand.R",
+	"DEF-upper_arm.L", "DEF-forearm.L", "DEF-hand.L",
+	"DEF-thigh.R", "DEF-shin.R", "DEF-thigh.L", "DEF-shin.L"]
+
+
+## Resolve `names` against a skeleton, given the sidecar's role table.
+##
+## The spine needs its own handling because a rig that kept its own skeleton
+## names things differently AND has a different number of spine bones — Taila's
+## hips are `DEF-spine` and her head is `DEF-spine.006`, and she has no bone with
+## "neck" in its name at all. Unresolved, every lean and aim pitch silently did
+## nothing.
+static func resolve(skel: Skeleton3D, roles: Dictionary,
+		names: Array = CANONICAL) -> Dictionary:
+	var alias := {}
+	if not roles.is_empty():
+		var neck: String = roles.get("neck", "")
+		var head: String = roles.get("head", "")
+		var torso: Array = []
+		for n in roles.get("spine", []):
+			if n != neck and n != head:
+				torso.append(n)
+		for i in mini(torso.size(), SPINE.size() - 1):
+			alias[SPINE[i + 1]] = torso[i]
+
+	var idx := {}
+	for n in names:
+		# Canonical names are the role keys with the DEF- prefix, so the limbs,
+		# hips, neck and head all map straight through.
+		var actual: String = alias.get(n, roles.get(String(n).trim_prefix("DEF-"), n))
+		var b := skel.find_bone(actual)
+		if b < 0:
+			b = skel.find_bone(String(n))
+		idx[n] = b
+	return idx

characters/rig_roles.gd.uid

@@ -0,0 +1 @@
+uid://coh341vhya5x5

characters/skinned_player_model.gd

@@ -96,6 +96,8 @@ var _rig_info: Dictionary = {}
 ## the same sidecar; drives the per-class cel look and answers `surfaces_of()`.
 var _surfaces: SkinSurfaces = null
 var _spring_mod: SpringBones
+## The emote layer, between the shooter pose and the cloth springs.
+var _dance_mod: DanceModifier
 var is_holding_weapon: bool = false
 ## Which hold archetype the equipped weapon uses — see WeaponHoldProfiles. Read
 ## by `_process` (a blade releases the off arm) and by the checks.
@@ -242,8 +244,17 @@ func load_model(path: String) -> void:
 		_pose_mod.fingers = _rig_info.get("fingers", {})
 		_pose_mod.name = "ShooterPose"
 		skeleton.add_child(_pose_mod)
+		# Dance AFTER the shooter pose, so an emote blends over the weapon hold
+		# instead of fighting it — the arms come off the gun as the dance weight
+		# rises and are handed back the same way.
+		_dance_mod = DanceModifier.new()
+		_dance_mod.name = "Dance"
+		_dance_mod.roles = _rig_info.get("roles", {})
+		skeleton.add_child(_dance_mod)
 		# Cloth and hair last, so the springs react to the FINAL body pose —
-		# animation plus the shooter lean/slide layer.
+		# animation plus the shooter lean/slide layer, plus any dance. Hair and
+		# a skirt following a dance is entirely this ordering; nothing else is
+		# needed to make it happen.
 		if not _rig_info.is_empty():
 			_spring_mod = SpringBones.new()
 			_spring_mod.name = "SpringBones"
@@ -553,6 +564,14 @@ func _set_shadow_mode_recursive(node: Node, mode: int) -> void:
 var _prev_state: String = ""
 var _oneshot_lock: float = 0.0  # seconds left where a one-shot owns playback
 var _dancing: bool = false
+## Which of DanceRoutines.ROUTINES is playing, and the eased 0..1 blend of the
+## dance layer over everything below it.
+var _dance_index: int = 0
+var _cur_dance: float = 0.0
+## How fast a dance takes the body and gives it back. Slower than the pose
+## layer's other blends on purpose: an emote starting is not a reaction, and
+## snapping into one looks like a bug rather than like a decision.
+const DANCE_SMOOTH := 5.0
 
 
 ## Play a one-shot clip over locomotion for `lock_time` seconds.
@@ -577,8 +596,16 @@ func play_oneshot(canonical: String, lock_time: float = 0.35) -> void:
 
 ## Emote toggle (Dance). Shown while grounded and near-idle; any real
 ## movement breaks it (the controller clears the flag too).
-func set_dancing(on: bool) -> void:
+##
+## `which` selects one of the five routines in DanceRoutines. The base clip stays
+## the library's single `Dance_Loop` underneath — the routine is layered over it
+## by DanceModifier, which is what makes five distinct emotes out of one clip.
+func set_dancing(on: bool, which: int = -1) -> void:
 	_dancing = on
+	if which >= 0:
+		_dance_index = which
+	if _dance_mod:
+		_dance_mod.routine = DanceRoutines.get_routine(_dance_index)
 
 
 ## Play a named gameplay action (reload / throw / shoot) as a one-shot.
@@ -734,6 +761,12 @@ func _process(delta: float) -> void:
 	_cur_slide = lerpf(_cur_slide, slide_target, t)
 	var wall_target := _target_wall if _pose_mod.state == "wall_run" else 0.0
 	_cur_wall = lerpf(_cur_wall, wall_target, lean_t)
+	# The dance blend. Eased both ways, so an emote arrives and leaves rather
+	# than cutting — and so the arms come off the weapon smoothly.
+	if _dance_mod:
+		_cur_dance = lerpf(_cur_dance, 1.0 if _dancing else 0.0,
+			1.0 - exp(-DANCE_SMOOTH * delta))
+		_dance_mod.weight = _cur_dance
 	_update_travel(delta, drive)
 	_pose_mod.strafe = _cur_strafe
 	_pose_mod.fwd = _cur_fwd
@@ -1352,7 +1385,9 @@ class ShooterPoseModifier extends SkeletonModifier3D:
 	const WALL_ARM_OUT := 0.9    # inner arm reaches out to touch the wall
 	const HOLD_SMOOTH := 8.0     # how fast the hold takes/releases the arms
 
-	const SPINE := ["DEF-hips", "DEF-spine.001", "DEF-spine.002", "DEF-spine.003"]
+	## The library skeleton's spine, hips first. Shared with the dance layer via
+	## RigRoles, which also owns the mapping onto a rig that kept its own names.
+	const SPINE := RigRoles.SPINE
 
 	var _idx: Dictionary = {}
 	var _resolved := false
@@ -1428,33 +1463,13 @@ class ShooterPoseModifier extends SkeletonModifier3D:
 
 	func _resolve() -> void:
 		var skel := get_skeleton()
-		var names := SPINE + ["DEF-neck", "DEF-head",
-			"DEF-upper_arm.R", "DEF-forearm.R", "DEF-hand.R",
-			"DEF-upper_arm.L", "DEF-forearm.L", "DEF-hand.L",
-			"DEF-thigh.R", "DEF-shin.R", "DEF-thigh.L", "DEF-shin.L"]
-		# The names above are the LIBRARY skeleton's. A model that kept its own
-		# rig names things differently and three of them simply do not exist on
-		# it — Taila's hips are DEF-spine, her head is DEF-spine.006, and she has
-		# no bone with "neck" in its name at all. Unresolved, every lean, aim
-		# pitch and slide head-lift below silently did nothing.
-		var alias := {}
-		if not roles.is_empty():
-			var neck: String = roles.get("neck", "")
-			var head: String = roles.get("head", "")
-			var torso: Array = []
-			for n in roles.get("spine", []):
-				if n != neck and n != head:
-					torso.append(n)
-			for i in mini(torso.size(), SPINE.size() - 1):
-				alias[SPINE[i + 1]] = torso[i]
-		for n in names:
-			# Canonical names are the role keys with the DEF- prefix, so the
-			# limbs, hips, neck and head all map straight through.
-			var actual: String = alias.get(n, roles.get(n.trim_prefix("DEF-"), n))
-			var b := skel.find_bone(actual)
-			if b < 0:
-				b = skel.find_bone(n)
-			_idx[n] = b
+		# The canonical names are the LIBRARY skeleton's, and a model that kept
+		# its own rig names things differently — Taila's hips are DEF-spine, her
+		# head is DEF-spine.006, and she has no bone with "neck" in its name at
+		# all. Unresolved, every lean, aim pitch and slide head-lift below
+		# silently did nothing. RigRoles maps them through the sidecar; the dance
+		# layer uses the same call rather than a second copy of it.
+		_idx = RigRoles.resolve(skel, roles)
 		_resolve_hands(skel)
 		_resolved = true