Add Mixamo Clips and Authored Contact Moves to a Custom Game Character

---
name: custom-character-contact-animation
description: Add owner-bought Mixamo/Adobe clips and authored contact moves (sword hits own shield, hand on prop) to an already-rigged custom GLB game character in headless Blender, graft them without touching mesh/skin bytes, measure foot-locked strides, and wire synchronized group actions + sound in a three.js game. Use when a rigged unit needs richer motion or a new prop-contact action.
---

# Mixamo clips + authored contact moves on a custom game character

Tested 2026-10-28 on a 40-joint UniRig swordsman (fused sword and shield, meshopt GLB, three.js RTS): a 2.4 s "bang sword on shield" clip, 9 Mixamo clips, a sidestep pair, foot-locked gait, a unison group order with sound, in about an hour end to end. This skill is the fast path; see "Time budget" for what to skip.

Assumes the character is already rigged and some clips were already retargeted (for raw retargeting see the skill "Retarget Free Animation Clips onto AI-Rigged Custom Characters").

## Fast path (do these in order)

1. **Inventory first (5 min).** Before Blender: list existing donor GLBs and the owner's source FBXs; hash any new download and compare *motion*, not bytes (step 3). Look for a GLB that already holds retargeted clips on the same skeleton: grafting from it needs no Blender at all.
2. **Blender headless, low priority.** `nice -n 19 blender -b --factory-startup -t 2 --python script.py -- args`. On WSL with a Windows install, call `blender.exe` and pass paths through `wslpath -w`. One short job per call; no GUI, no GPU.
3. **Compare motions, not files.** Two Mixamo downloads of the same move differ in bytes (mesh included or not). Sample 33 normalized poses of every joint plus hip travel; under ~3 degrees max rotation difference = same move. Hip travel sign gives direction: Mixamo imports facing -Y, so **+X hip travel = character's LEFT** sidestep, -X = right, +Y = backward walk.
4. **Contact sheet before choosing clips.** Render 2 views x 16 poses in one Blender call (Workbench, 300 px, ortho camera) for old vs new clips. Reject deep-crouch attacks; prefer clips whose pelvis range matches idle.
5. **Author the contact move** (below), check numbers, then one close-up render of the contact frame.
6. **Graft** clips into the exact runtime GLB (below), qualify bytes + glTF validator.
7. **Measure foot-locked strides** from the GLB as the engine loads it (below).
8. **Wire runtime** behind one config file with a revert flag.
9. **In-engine check** with exact frames (see skill "Headless In-Engine QA for Three.js Games").

## Find fused props from the skin

Weapons fused into the mesh are rigid: collect vertices whose dominant weight is >0.95 on one bone, keep clusters >30 verts. The hand bones with thousands of rigid verts are the props.

```python
for v in mesh.data.vertices:
    g = max(v.groups, key=lambda g: g.weight)
    if g.weight > .95: clusters[groups[g.group]].append(v.index)
```

PCA of the **evaluated** (posed) cluster: shield normal = smallest axis, blade = largest axis (tip = longer side from the hand), blade flat normal = smallest axis. Orient the shield normal toward the character's forward.

**Trap (cost a re-bake):** measure with the base action assigned and frame set. After glTF import the active action is arbitrary, and the shield's front/back sign came out flipped.

## Authoring a contact move (sword strikes own shield)

- Base body = a looping owner idle that already holds the prop forward (time-stretched to the new clip length so it still loops).
- Per frame: evaluate base pose, add accents (torso twist/lean, head nod, small hip dip peaking at contact), then **analytic two-bone IK** for both arms, then key every bone's quaternion (root also location). Analytic IK avoids Blender constraint dependency cycles (arm IK targeting an object parented to the other arm's bone).
- Shield arm: target the shield centre/normal in the chest frame (closer than idle: the striking arm is shorter than you think; check reach = |shoulder->target| vs upper+lower length and log the shortfall).
- Sword arm: compute the contact point **in the posed shield frame** each frame, so hits land even while the body sways. Contact point = shield centre + normal x (front surface + 1 cm) + offset toward the sword side. Hand rotation = the rotation that puts the blade axis along the shield plane and the blade flat against the face; hand position = contact - R x (blade contact offset).
- **Two-stage swing**, or the blade passes behind the rim: overhead wind-up -> "cocked" pose (blade rotated ~65 deg off the face about blade x normal) -> flat slap onto the face. Slerp wind-up->cocked, then hinge cocked->contact.
- Beat curve per strike: ease-out rise, accelerating fall (power ~2.2), short rebound. 18 frames per strike at 30 fps reads clearly at RTS zoom.
- Report and check: reach shortfall < 5 mm, blade-to-target error ~0, blade height above face > 0 (no penetration), feet drift < 3 cm.

```python
def two_bone(upper, lower, hand, target, pole):
    S=head(upper); l1=(head(lower)-S).length; l2=(head(hand)-head(lower)).length
    d=target-S; dist=max(abs(l1-l2)+1e-4, min(d.length,(l1+l2)*.999)); u=d.normalized()
    a=(l1*l1-l2*l2+dist*dist)/(2*dist); h=sqrt(max(0,l1*l1-a*a))
    v=(pole-S); v=(v-u*v.dot(u)).normalized(); E=S+u*a+v*h
    aim_child(upper, lower, E); aim_child(lower, hand, S+u*dist)   # minimal-arc rotation about each head
```

Set bones through `pose_bone.matrix` (armature space) and `view_layer.update()` after each so children see the new parent. Reset non-root location/scale every frame or edits accumulate.

## Graft without touching the art

Append animations from donor GLBs to the exact runtime GLB, by node name:
- Check every donor bone has the same parent and the same local rest matrix (error < 1e-4).
- Copy donor accessors/bufferViews as new **plain** views appended to the GLB binary chunk (buffer 0); never copy a view carrying a compression extension. **Meshopt-compressed bases work**: their compressed views sit on the fallback buffer and stay byte-identical.
- Rename on the way in (`donor::SourceClip=>NewName`), refuse to overwrite an existing output, keep the original bytes as a prefix.
- Qualify: nodes/meshes/skins/materials/images identical, original animations/accessors/views identical as a prefix, binary prefix identical, gltf-validator errors = baseline.

## Foot-locked stride (do not guess)

Load the GLB the way the engine does (same height normalization, MeshoptDecoder in Node with images/materials stripped). For each clip sample 90 frames; stance = frames where a toe is in the lowest 20% of its height range; stride per cycle = median backward toe speed x clip duration, along forward for walks, along the left axis for sidesteps. Then drive the clip phase from distance travelled / stride.

Measured example (1.8 m knight): Mixamo run 2.47 m/cycle, guarded walk 1.36, sidestep 1.21-1.36, backward 1.54. The old hand-tuned constant was 2.64. Estimating from Mixamo root travel x leg-length ratio gave 2.27, close but not exact.

Traps: the Blender glTF importer may read frames at 24 fps (durations look 0.8x); a helper object in the GLB (e.g. an Icosphere) inflates Blender bounds but not the engine's, so use the engine-side measurement.

## Runtime wiring that stays reversible

- One config module: model path, clip map (old map kept), strides, and a `useNewMotion` flag. Other files import it; flipping one flag restores the previous behaviour. Keep a separate clip map for any rig that is hand-posed on top (e.g. a mounted rider).
- Sidestep/backward choice: smoothed travel vector vs facing; forward < 55 deg, sidestep 55-125 deg (sign of the left component), backward > 125 deg. Facing +X means the right hand points to +Z (forward x up). Formation moves that hold a heading are where this shows; also stop braced units gliding in a frozen block pose while they walk.
- Group action (bang shields): presentation-only order. Keep state per game in a `WeakMap<GameState,...>` (restart cleans itself), one shared start time per order (unison), seek the clip by `(now-start)/clipLength` rather than letting each mixer drift, end on any new order/death, bounded strike count + cooldown. A rewound clock clears the book (by design).
- Sound: one cue per strike per group, never per unit; switch to a "whole rank" recording above ~3 units. Generate SFX with a single-hit prompt, check every variant's onset is at 0 ms, peak-normalize public copies (raw generations can differ by 30 dB) and keep the raw files.
- Tests pinned to literals (sample count, old stride phase, exact float cycle boundaries, default facing) will fail: derive expectations from the config instead of editing numbers.

## Time budget (about an hour on the first run)

| Phase | Took | Next time |
|---|---|---|
| Orientation, where to run Blender | ~15 min | Inventory list + known Blender path up front: ~5 min |
| Inspect + 4 contact bakes | ~9 min | Measure in base pose + two-stage swing first time: 1-2 bakes |
| Sidestep check, SFX, graft (+rename regraft) | ~10 min | Name the action in the owner's words before grafting |
| Stride measurement | ~6 min | Use the engine-side script directly |
| Runtime + tests | ~10 min | Expect pinned-literal test updates |
| In-engine QA (4 runs) | ~6 min | Pause-overlay, no-rewind, framing known: 1 run |
| Snapshot, registry, log, board | ~9 min | Same (required) |

## Honest limits

Wrist twist at full wind-up came from analytic IK, not a hand pass. Attack clips can carry a different contact frame from the game's damage timing, so check before swapping. Props that are not rigid (capes, scepters stretched by old weights) need a reweight first, not new clips.