AI tools: Characters and animation

Rigs, poses, clips, Motion AI, faces, clothes, holding and weapons. 80 tools. You see every step your AI takes and can undo any of them.

active_body

Euphoria-style active bodies while playing: make a character physical (a ragdoll that follows its animation through muscles and pins) and push it, hit a limb, or make it drunk; then read every active body's phase (reacting: swaying and stepping to keep its balance; falling: balance lost, muscles bracing; down), its pins and muscles, how far its weight drifted, the stagger steps it took and what happened. Bullets on live characters already use this.

anim_graph core

A character's animation state machine (3D): states (a clip, "auto" for the locomotion blend by speed, layer=upper over the legs, move=<move_hitbox move> for a combat attack with its hit windows, blend= for a blend space by any param: blend=speed:Idle@0,Walk@1.4,Run@4 or 2D blend=right,forward:Clip@x/y,... for strafing), transitions (on a press, if a param, done, after seconds; blend=SECONDS its cross-fade), combos (a state's cancel window lets the next press chain), input buffering. preset: locomotion, melee_combo (from the character's move_hitbox moves), upper_actions (emotes or reloads over walking), traversal (a ladder state on on_ladder); or states/transitions/start/params/buffer by hand. Always checks it (every clip and move really there, every state reachable). presses [{t, fire} | {t, set: {param: value}}] with seconds: plays it in a private copy and returns the timeline of states (the proof a combo chains). In Play: the live state, params and history. Scripts: self.anim.fire("attack"), .set, .play, onMessage('state'). kit_playbook animation teaches the whole system. HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.

anim_view

Animation lab view while playing: draws every nearby character's skeleton (white bones), the hit capsules bullets really test (head red, torso orange, limbs yellow, hands/feet green), the centre of mass with a plumb line to the floor (balance), and the last 24 shots' flights (white at the muzzle to red) with a dot at every impact (red on a limb). Reports the same as numbers: each body's limbs (radius, length), how far its weight sits outside its feet, and each shot's impacts with what it hit and the speed in and out. Session only.

body_measure

Measure a rigged character's body against real adults, in its bind pose: stature; skin girths (upper arm, forearm, wrist, thigh, calf, neck) as a tape would read them, with what's worn over them; segment lengths and joint heights as fractions of stature (Winter's anthropometric ratios), so a bone in the wrong place shows; where each joint sits in its limb's cross-section (a knee or elbow off-centre or outside the flesh); hands and fingers (hand and foot length, each finger's three segments to the skin tip, index:ring ratio, the curl at rest). sex picks the reference ranges (default: both shown). HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.

character_look

Read or set the look (the character creator's person: body and face sliders 0...1 with 0.5 the kit's own, skin tone, hair style and colour, eye colour) an object wears, in Play when Play runs, else in the scene. action get (default) returns the look as JSON; set wears `look` (a whole look) and/or `set` (sliders to change, e.g. {"height": 0.8, "jaw": 0.3}, plus skin_tone, hair, hair_color, eye_color); random wears a random person (seed); preset wears one (ranger, scholar, brawler, elder, runner). Built from the look's creator kit (forge_creator_kit; default Characters/TTR_CreatorKit.glb) the first time, then shared by everyone with that look. In Play the player's look rides the run (every scene, every save slot).

clip_blend

A new clip that mixes two (Beta 2 fix tools): `name` = clip `a` with clip `b` mixed in at `weight` (0 all a … 1 all b), b sampled at the same share of its length (a walk with a limp, a tired run, an attack halfway to another). Same as clip_edit with blend_with; kept in the clips file beside the model.

clip_edit

Edit an animation clip without touching its file (Beta 2 fix tools; any rigged character, imported or made here): makes `name` from clip `from` (its own or its animator library's), with any of: start/end (trim, seconds), speed (retime: 2 twice as fast), loop (made seamless: the end eases into the start over loop_blend s), mirror (left/right swapped), root_motion "in_place" (the hips' travel across the floor taken out) or "keep", blend_with + blend (another clip mixed in, 0-1), events, feet (floor_offset m, toe_angle degrees, plant: foot-down/up events where each foot is down). Kept in the clips file beside the model (X.glb.clips.json), made at every load; plays by name anywhere (animator.clip, sequencer, brains). Same name as `from` replaces it in play (the file is never changed). play: true plays it on the character now. list: true lists the clips and edits; remove: true deletes the edit `name`.

clip_events

Events on an animation clip (Beta 2 fix tools): list them, add, remove, or place them for you. Names that do something in play: footstep.L / footstep.R (the footstep sound, and the foot held planted), sound:<name> (that sound at the character), windows with an end: hit or hit:hand.R (damage lands), combo (the next attack may chain), cancel (a dodge or block may cut in); any other name reaches scripts (onAnimEvent). footsteps: true places left_foot_down/up and right_foot_down/up where each foot is down (play holds it flat between, and sounds each landing). from_hitboxes: true copies each move_hitbox naming this clip's active frames as its hit window (so combat and the clip agree). The clip itself isn't changed: the events go on an edit of the same name (clips file beside the model).

clip_feet

A clip's feet, fixed in the engine (Beta 2 fix tools; any rigged character, a retargeted clip too): floor_offset raises (+) or lowers (−) the whole body in metres (feet through the floor, or floating), toe_angle bends the toes (degrees, + up), plant: true places foot-down / foot-up events where each foot is down (play holds each foot flat between, and sounds each landing). Kept as an edit of the same clip (clips file beside the model). The retarget solver itself isn't changed (🤖 Motion Core's): these sit on top, per clip.

clip_preview

Play a clip on a character and see its timeline (Beta 2 fix tools): sets its animator to the clip (loop as asked) and replies with the clip's length and every event in order (windows as spans), then, after `seconds` of play, which events actually fired and when. Turn on anim_view {steps: true} alongside to see the foot plants drawn.

cloth

Real cloth in the world (Beta 2): flags on poles, curtains, banners between posts, tarps on frames, sheets on a line, capes. It hangs from its pins, blows in the scene's wind (gusts ripple across it) and never passes through the colliders and characters near it (poles, walls, crates, the player walking into it): the `cloth` component, simulated in Play on the engine's cloth solver; the editor shows it at rest unless view on. action make puts one up: shape (flag, curtain, banner, tarp, sheet, cape) with its own sensible settings, at [x, y, z] (default on the ground in front of the camera), facing (degrees), width/height, color; pole true (a flag's pole, the default for a flag; a banner gets two posts, a tarp four corner posts) so it hangs from something real. pin sets what holds it (pins top/left/right/corners/top_corners/none, points [[u, v], ...]); unpin lets go (loose top_left, top_right, bottom_left, bottom_right, left, right, top, bottom or all: torn loose, pulled down). retune changes any cloth field (stiffness, stretch, weight, damping, wind_response, wind, thickness, collide, width, height, resolution...) as one undoable change, and live in the game while it plays. view on runs the cloth in the editor (off: back at rest). report: per cloth its particles, what it met (boxes, capsules, characters), ms per frame, the wind on it and the worst penetration (0 mm: nothing clips).

cloth_tune

Live overrides for the cloth characters wear, in Play or not, no rebuild: friction (against the body, its capsules and the layers under the cloth), damping (swing lost per second), bend (× how easily it folds), ease (× the room for the stride below the hips), stand_off (× loose cloth's kept gap off the body), floors (loose cloth keeps in front of the layers under it) and floor_gap (metres off them). Each value given replaces the one in force; reset: true first puts all back to the fabric's. Applies to every character's cloth from the next frame; replies with what's in force.

clothes_fit

Looser or tighter clothes, per garment or the whole outfit (Beta 2 fix tools; any outfit and body, forged or imported): looser_mm moves the garment out from the body (tighter_mm in), the full amount over the cloth and fading to nothing at its cuffs, hems and collar, so it gets roomier without its openings moving. Also hide_skin (skin fully under the clothes is removed at load: true, the default) and cover_cm (how far out clothing still hides the skin under it). Saved in the model's fit file (X.glb.fit.json) and applied now (the character reloads). garment: a name from clothes_check's list ("shirt" or its material "Human.shirt") or "all". reset: true clears this character's fit (clothes_fix's fixes too).

clothes_fix

Fix a character's clothing clipping in one step (Beta 2 fix tools; any outfit and body, forged or imported): watches it (seconds, in Play while it moves; 0 one frame), then at every place a layer shows through the one over it: skin showing through is pulled in under the cloth, an inner garment showing through is tucked under the outer one (each by its depth + 2 mm, spread smoothly over a few cm). Cloth measured inside a limb is reported, not moved (that measure reads limbs as round tubes: check the picture, and clothes_fit the garment looser where it shows). Saves the fixes in the model's fit file (X.glb.fit.json, replayed at every load), reloads the character and checks again: replies before and after per clip. dry_run: true only says what it would change. undo: true takes this tool's fixes back out (clothes_fit's looser/tighter stay). Worn gear (boots, armour attached to bones) isn't changed: it says to move it.

compact_character

Make a person already in Assets/Characters the shipping size, in place: every map at most texture_size (default 2048, eyes 1024) as JPEG where opaque, a map shared by pieces written once, lean body shapes (no shape normals). The settings forge_creator_kit ships with; a 40-50 MB villager comes out several times smaller. Check the face at 1 m after (screenshot or inspect). Its recipe stays. HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.

equip_item

Put an item on a character: worn cloth (its item's equip.wear) is drawn fitted to the character's body, hiding the skin under it; helmets, packs and weapons (equip.model) ride their bone as a child "<name>/<slot>". What the slot held comes off, and so does what the item blocks (equip.blocks: a two-handed sword the off hand). While the game plays, it changes the running game (scripts hear 'equipped'/'unequipped'); otherwise the scene, one undoable step. Items: Assets/Items/<id>.item.json with {"equip": {"slot": "chest", "wear": [garments]}} or {"equip": {"slot": "main_hand", "model": "Weapons/sword.glb", "offset": [x,y,z], "rotation": [x,y,z]}}. Worn cloth needs a fit for the body first: equip_prepare.

equip_prepare

Fit worn items to the bodies that wear them: the tailor drafts each item's garments for each body's measurements, drapes them, bakes their folds and paints their fabric, and writes Equipment/<item>/<body>.glb (only the garments, skinned to that body's skeleton). Run it after making or changing a worn item, or before shipping (games load these files on every platform; only a Mac can make them). Bodies: the characters given, else every character in the scene with an equip component (their bare model). Items: those given, else every worn item those characters have on. Slow: about a minute per item and body. "refit" makes them again. HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.

face_capture

Face performance capture from a video (a phone clip of someone talking or pulling faces): Apple Vision tracks the face every frame and the frames are solved for the 52 face shapes of the person who will play it (their own shapes explain the motion), with eyes from the pupils and the head's turn. Writes Assets/Captures/<name>.json; play it with face_perform {capture}. iPhone ARKit / Live Link Face CSVs play directly, no solve needed. HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.

face_critic

Score a character's face the way a close-up reads: renders a front close-up of the face in the scene's light and measures the eyes (the whites' lightness, spread and corner shading, the pink inner corner), the lashes (strokes above the upper lid: width, coverage, darkness), the cheek skin (pores, fine lines, blotches, colour blotch, sheen) and the nose (alar crease, nostrils, nasolabial fold), with the floors a real face clears. reference: a target picture of the same framing (a Nano Banana repaint of this close-up), measured the same way for ratios. save: keep the close-up (a .png path).

face_decay

Turn a Face Forger person into a zombie, keeping their face: stage fresh (bloodless grey-yellow pallor, dark veins surfacing, bruised sunken sockets, milky corneas, purple dry lips, dried blood run from the mouth and a bite), rotted (grey-green marbling, black veins, slipped skin, a torn lip opened into the mouth with a real wound wall, bite craters in the mesh, opaque eyes, stained teeth) or burned (charred, blistered and cracked skin, raw burns, waxy patches, eyes boiled white). amount 0...1 scales it; seed varies wounds and blood runs. The 52 face shapes, rig, groom and wrinkles stay. Writes Characters/<name>.glb. HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.

face_detail

Give a Face Forger person (forge_person output) expression wrinkles and the blood and veins under the skin: forehead lines, crow's feet, bunny lines, the 11s, nasolabial folds, lip and chin lines, neck bands, measured from the person's own 52 face shapes (lines form only where their skin really squeezes) and deepened with age; the face flushes with effort and anger. New forge_person faces have them already; this upgrades older ones (also adds the skin profile if missing). Writes the model in place (or as `name`). HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.

face_lids

Give a toon character with painted eyes (a face drawn from a face_sheet: the eyes are on the skin, no eyeballs) lids that close: an upper and a lower lid of its own skin over each painted eye, folded away while open, shut by the face shapes eyeBlinkLeft / eyeBlinkRight. Then it blinks, and a cutscene or script holds its eyes shut with the expression "eyes_closed" (or "asleep"), easing them open with animator.expression_intensity. New face_sheet creatures get lids when forged; this adds them to older ones. Writes the model in place (or as `name`). HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.

face_perform

Direct a character's face (characters with face shapes): an expression or a blend (angry, contempt, determined, disgusted, effort, eyes_closed, flirty, happy, laugh, neutral, pain, sad, scared, shout, smirk, surprised, thinking, tired, worried; or "happy:0.6, surprised:0.4"), or any of the 52 ARKit face shapes by name for subtle faces ("browInnerUp:0.3, mouthPressLeft:0.2, eyeSquintRight:0.15", mixable with emotions), eased in and out; a spoken line with lip sync (text, and optionally a recorded WAV in Sounds the lips follow); where it looks (an object, [x, y, z] or "ahead"); a short cue ("effort" while firing or reloading, "pain" a flinch, or any emotion as a flash). Eyes, blinks, breathing and glances are automatic.

fp_hands

The running game's first-person hands, live (Play mode; no rebuild, nothing saved): `view` takes what game.weaponView takes: hip / down / sprint / reload holds ({position: [right, up, ahead] m from the eye, turn: [up, right, roll] degrees}; down is the hold looking down, fully in at down_pitch degrees below level), sway, bob, lag, view_fov, view_scale, elbow [down, out], one_handed. `offhand` holds the free hand up where asked ({at: [right, up, ahead] m, fingers: [x,y,z], palm: [x,y,z], grip: a grip_presets name, grip_amount 0...1, ease s}) to try a grip or a hold by eye; let_down true lets it down. Put what works in the scripts (kits/torch_hands.js params, game.offhand in a kit) to keep it.

gait_from_video

Read a four-legged animal's real gait from a video: a wolf's trot, a horse's walk, a boar's gallop (side on, the camera following the animal, a plain grey backdrop reads best: make one with Veo 3.1 Fast in Google Flow). Apple Vision finds the legs, paws, spine, head and tail on every frame; out come the gait's numbers in leg lengths, so any creature takes them: period (seconds a stride), duty (share of it a paw is down), the gait (walk, trot or gallop, from when the hind and fore paws land), each paw's lift-off phase, stride length, paw lift, body and head bob, speed. Writes Assets/Motion/Gaits/<name>.gait.json, <name>_footfalls.png (each paw's stances over time) and <name>_skeleton.jpg (what Vision saw on 12 frames, to check it). macOS editor only. HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.

grip_in_hand

Seat a prop in a character's hand by its grip: the prop's grip point (prop_grips) goes on the palm's centre, the palm facing the way the grip says and the fingers wrapping it, and the prop is attached to the hand bone (attach { to, bone, offset, rotation }) so it rides every animation. Swords, axes, torches, tools, guns. flip turns it end for end round the palm (the blade out of the other side of the fist); turn adds degrees round the grip's axis.

grip_presets

The finger presets a hand can take (GripLibrary): for make_pickup's grip, game.offhand({grip}) in a script, a pose's grip, a hold socket's grip. Each with what it's for.

No arguments.

groom

Grow real strand hair or fur on a rigged character (Characters/<name>.glb): writes Characters/<name>.groom beside it, which the engine draws as thousands of strands up close (clumped, curled, self-shadowed, lit as fibers) and as the model's own hair cards far away. Presets: lion (mane, short coat, face fur, whiskers, tail tuft), tiger, wolf (guard-hair coat, ruff, bushy tail; on a forge_creature body "wolf"), fur (an even coat on any creature), or a human style grown on the scalp with brows: straight, long, wavy, curly (ringlets), coily (4C), afro, fade, short, crop, buzz, waves (360), messy, slick. Re-run to regrow (deterministic for a seed). HTTP calls return a job_id immediately; read progress and the final result with tool_job instead of repeating the tool.

gun_move_status

Weapon locomotion of a character (gun_move component): its class, the speeds it walks, runs, sprints and walks aiming at (with the class defaults filled in), its ADS raise/lower and sprint-out times, posture, bob and sway, and the measured gaits its animation library has (natural speed of each loop), so speeds can be set where the clips look right.

hair_detail

Strand hair's distance detail, live (no rebuild; session-wide, every groom): how many strands are drawn as a groom gets smaller on screen and how much wider each is drawn to make up for the rest. fraction: the share of strands drawn whatever the distance (testing: 1 draws every strand); automatic: true goes back to choosing it by distance. pixel_coverage: how much of a pixel a drawn strand covers at least before strands are thinned out (0.5 default; lower keeps more strands, finer and slower). width_exponent: thinned strands are drawn share^-exponent wider (0.85 default; 1 keeps the total cover exactly, lower lets far hair go see-through). With no arguments, reports the settings.

hold

Put a hand on an object by intent: the arm reaches, the wrist turns to the hold point, the elbow goes where the forearm runs on with the hand (wrist straight) and under the object, and the fingers close joint by joint until they touch it, the thumb opposing. point: a hold point (hold_points); slide 0...1 along it (a handguard, rear to front); grip: power, pinch, c_clamp, cup, hook, flat, trigger (a firing hand on a pistol grip, the index on the trigger; on_trigger false lays it along the frame); finger_angle: degrees the fingers turn toward the object's front. object defaults to the gun in the character's hands. On a weapon hold being edited it goes into the hold at every aim pitch. Returns a readout of each hand (contact, finger gaps and faces, wrist bend, penetration, elbow) and a picture.

hold_adjust

Change a hold by intent, from where it is: forward_cm (toward the object's front, e.g. slide the left hand 4 cm forward), up_cm, across_cm (to the object's right), finger_angle (degrees more toward the front), slide (a new place along the range), grip, close_fingers (true: close again until contact). Re-solved and written like hold.

hold_finger

Put one finger of a holding hand where it goes, by intent: on "trigger" (the pad on its face), "far_side" (round the back strap onto the grip's other side: a firing thumb), "back_strap", "front_strap", "top" (the grip's top under the frame), any point the object names (hold_points, its sockets), or to [x, y, z] in the object's own frame (metres; x the object's left, y up, z its front); offset_mm nudges that in the object's frame. The finger is solved in a hand's joint ranges against the object's real surface (never through it), the rest of the hand kept; on a weapon hold it goes into the hold. Returns where every finger now is on the object.

hold_points

The hold points of an object (a gun's grip, handguard, fore grip; a handle): where the palm goes, which grip suits it, and the range a hand can slide along. Found from the object's parts, or declared in <model>.sockets.json.

keyposes_to_motion

Turn a sheet of key poses (one move drawn as figures side by side: the same person from the same angle, a three-quarter view reads best, the same floor line; make it with Nano Banana in Google Flow) into an animation clip for our characters: the figures are found on the sheet, each one's 3D body pose is read (Apple Vision) and checked against the picture, the joints carried through the keys on smooth curves at the times given (moving through a pose that passes, easing into a pose that turns back), the move kept in place, then retargeted and cleaned up like video_to_motion (floor, planted feet, limits). For moves a video can't give cleanly: a claw swipe, a lunge, tearing a board off, a grab. Saved as Motion/Video/<name>.videomotion.json, played as clip Video/<name>; returns the panels over the character at each key.

locomotion_drive

Drives the third-person player through the real controls on a movement course while the system measures every held foot: reversals (back and forth, sideways, diagonals), slalom (quick zig-zags), camera_swing (walking while the view swings), sprint_turns (hard 90° turns at a sprint), stops (walk/sprint then stop), or all of them. The camera follows as in play, so the person watches; tune with locomotion_tune and anim_view {locomotion: true} between runs. Starts and returns at once; call again with report true for the numbers (frames a held foot stretched past the moving drift and near the forced step, the worst stretch and when) and to hand the controls back.

locomotion_tune

Live tuning for character movement, no rebuild: lists every movement value (the third-person velocity curve, the body's turn, the foot locks' step, pivot and split guards, and the everyday walk's whole shape: walk.* steps, heel landing, push-off, toe-out, bob, pelvis, chest, lean, arms) with what it does and its value now; `set` changes any of them for the very next frame (walk.* regenerates every loaded character's walk in place; until the editor quits; `reset` puts them back as built). `posture` changes a character's posture in the live game (lean, head, shoulders, slouch, elbows, toe_out, pelvis_tilt, step_width, arms_out, stride, arm_swing, sway, bounce: its gait component). `matching` turns motion matching on or off for a character in the live game. `save_preset` keeps every value (and the player's posture) in Assets/Motion/Tuning/<name>.locomotion.json, `load_preset` puts a saved one back live (walk, run, turn, anything), `presets` lists them. `pause`, `step` (frames while paused) and `slowmo` (0.05...1) freeze, advance or slow the game to look at one step. Watch with anim_view {locomotion: true, steps: true}.

make_brain core

Create or update an editable native brain using exactly one preset or description. Description is a deterministic keyword match to a named preset, not invented code; ambiguous descriptions are refused. Advanced presets: tactical, stealth_guard, slasher, pedestrian, traffic, boss, zombie (wanders, hears gunshots through real geometry, groans to draw the horde, chases, searches, follows trails). Uses the same undoable protected-scene path as add_brain. Existing components are preserved.

motion_ai

The motion AI in Play (motion_ai components: NVIDIA MotionBricks run inside the engine, the body moved by it instead of its clips while it walks): the network's state and, per character, generations, frames drawn, generations that came back late, frames the body check (PoseAnatomy) failed and the last finding, its share of the drawn pose and its speed. entity + on: turn it on or off on a character in the running game (A/B against the clip walk; on gives it a motion_ai component with the defaults if it has none); keys: its key-pose file (a ttr.jointworld in Assets); start: a ttr.jointworld that begins standing still (motion_learn of a stand-walk-stop video), so starts from standing are the motion AI's own ("" for none). reload: make every character's driver again.

motion_critic

Referee for character motion: characters walking side by side (default), the Quality Lab course, embedded looping clips or capture takes keep their separate baseline checks. An authored clip Poses/<name> is measured directly from its baked poses and saved 3D root travel, including exact key times: centimetres per complete step, partial contact slide, sole penetration against a stated flat ground, body jerk, joint frame deltas, saved goal misses and root endpoint error when expected_root_delta is supplied. Authored results are raw measurements with explicit nulls for unexercised metrics, not an overall pass; one-shot clips are never repeated to invent steps. Watch the motion too.

motion_export

A character's motion written onto another skeleton, as each joint's world turn and place per frame (JSON): the motion AI's key poses come from it. video: a video_to_motion performance (Motion/Video/<name>.videomotion.json, or a path); or clip: a pose clip of the character (default the one playing). to: a BVH file whose skeleton receives it (NVIDIA SOMA is retargeted from its T-pose). root_motion (default true) keeps the travel. out: the .json written (rate, joints, frames: per joint 9 rotation numbers row by row then x y z in metres). Reports the body check (PoseAnatomy) on both skeletons, frame by frame. straighten: take a treadmill or tracking-camera take's slow drift in facing out (it goes straight by nature).

motion_generate

NVIDIA MotionBricks makes a motion on a character: from where it is in a clip (clip, time) to a target ahead of it (forward metres along its facing, default 1.5; turn degrees, default 0; gap: how far into the clip the target's poses come from, default 36 frames), generated on the SOMA skeleton and retargeted onto the character. Saves it as a clip (save_as, default <clip>_generated) with the model's foot contacts as its foot events, and plays it. The network runs on ONNX Runtime: the model (mmm_v6_soma_fp16.onnx) from the project's Assets/MotionAI, the app, or TTR_MOTIONBRICKS_MODEL. replay: a recorded network output instead (tests).

motion_import

A BVH motion file moved onto a character as a clip (any skeleton: a mocap take, MotionBricks output, another tool's export): bones matched by role, the hips scaled by leg length, planted feet cleaned of skating, played in place (the travel is taken out). file: a path in the project or an absolute one; unit: automatic (default), meters, centimeters, inches; turn: degrees about up that bring the performer's rest facing to +Z. Saves it as a clip for the character (default the file's name) and plays it.

motion_learn

Teach a character's motion AI (NVIDIA MotionBricks, run by the engine) a way of moving from one reference video: a person walking, jogging, running or sneaking across the frame, side on, whole body in view (make one in Google Flow: Veo with a locked-off camera, or first and last frames from Nano Banana so the camera can't move). One call: reads the video, tries it as a still camera and as a treadmill (a following camera), straightens it, writes it onto SOMA as Motion/AI/<name>.jointworld.json, grades each reading (its pace, the longest straight stretch the AI can steer by, the knee through the stance, how far a planted foot slides), keeps the best and adds it to the character's motion_ai keys (a motion_ai component is added if it has none). mode: auto (default), still or treadmill. keys: add (default), replace or none. through: soma (default: the video is read straight onto the model's own human skeleton, right for any character, a toon with a simple rig included) or character (through the character's own rig). A video that begins with the person standing still (a stand-walk-stop take) also becomes the character's motion_ai start, so the motion AI makes its starts from standing too. Then play: the character walks on it at speeds near its pace.

motion_match_debug

Inspect a character's classic motion matcher: requested library, actual owner-scoped pose source and approved-default carriage policy, borrowed compatibility library, indexed clips, feature sample count and feature-array bytes, selected clip/time, search and switch counters, latest match cost, desired and actual velocity, and inertialization state. mode authoring (default) reads the authoring/rehearsal world; mode live requires this editor's running Play session. A missing database or unsampled animator is explicit. May build this model's pending feature cache; never moves the character or invents a play run. Use motion_critic for contact measurements and play_test for input-driven footage.

onion_skin

Onion skin for a pose clip at a time: ghost poses before (blue) and after (orange) every `step` frames, faded with distance, plus the hands', feet's and head's arcs, as data for the editor's timeline (bone segments and points, world space) and one composite picture.

performance_capture

Private-editor performance evidence: start returns a capture session, stop with that session returns exact unsmoothed per-frame interval/CPU/draw counts, indexed mesh triangle submissions, independent GPU samples, resolution and texture allocation. Idle costs no extra render pass. Never treat missing samples as a passing 60fps result; Scripts/performance-gate.py evaluates the strict 16.7ms p95 gate.

pick_up

A keyed pick-up: the hand reaches to the object's hold point with the fingers open (approach), closes on it (grasp), and lifts it lift_cm (default 15) with the feet planted; the object follows the hand from the grasp on. Saved as a clip (Assets/Motion/Poses/<clip>.poseclip.json, default <entity>_pick_up, with its keys and the object's track) and played. seconds: the whole action (default 1.4).

pose_character

Pose any rigged character (humans, creatures) by contacts and goals, not bone angles: hands on a sill, a foot on a wall, a knee up, looking at something, hips lowered, a prop held with fingers wrapped round its grip points. A full-body IK solve (limbs never stretch past their length, joints stay in their limits, the body leans toward goals out of reach, feet stay planted) saves the pose as a clip (Assets/Motion/Poses/<name>.poseclip.json), plays it on the character and returns a picture plus how close each goal came.

pose_constraint

Constraints over a clip. kind "aim": a bone's axis points at an object or point (bone, axis [x,y,z] in the bone's frame, chain, weight); "look_at": the head and neck follow a target; "parent": a prop follows a bone between switches ([{time, to: right_hand | a bone | world, blend, fall: true drops it to the floor}]), keeping where it was at each switch (no pop). Aim and look_at re-bake the clip; parent saves the prop's track beside it (<clip>.<prop>.track.json, for the Sequencer) and returns a filmstrip.

pose_explain

Describe the character's pose (or a keyed clip) in plain words and numbers, to check posing without guessing from pictures: the trunk's lean, where the head faces, each arm and leg's direction and bend, what is on the ground, whether the centre of mass is over the feet (by how much), joints past their range; for a clip also each key, the hips' path, the fastest hand and foot, and feet sliding while planted.

pose_ik_fk

IK/FK per limb over a clip: each limb's IK weight over time ([[time, weight], ...] or one number), its IK goal (a goal like pose_character's, or pin_at: a time whose FK hand/foot position is held from then on: a hand planted on a wall while the body moves). Switching uses FK's own hand as the IK start, so nothing pops. Saves the result as a new clip and plays it.

pose_key

Keyframe a pose clip by goals: add (or replace) the key at `time` with goals like pose_character's (anchored to the objects they name, so the clip can later be re-fitted with warp_pose_clip), or remove one. Every edit re-solves all keys on this character, solves every frame between them (hands and feet whose goal is the same in two keys stay exactly planted; others glide with the key's easing: linear, ease_in, ease_out, ease_in_out, hold), bakes it at 30 fps into Assets/Motion/Poses/<clip>.poseclip.json and plays it. root_motion:true saves the hips' horizontal travel as an actor-root path with in-place frames for gameplay. Optional hips_rotation keys the pelvis' absolute world orientation while the body-part goals are solved. Returns a still per key.

pose_layers

Animation layers: a base pose clip with layers over it, each another clip, override (replaces the masked bones by its weight) or additive (adds its change from its own first frame, or from rest), masked to body parts (aim with the upper body over a walk; a breathing layer over anything). Layer clips loop over the base's length. Saves the result as a new clip and plays it.

pose_library

The pose library (Assets/Motion/Poses/library.poses.json): save a frame of a pose clip under a name, apply a saved pose to any body (bones by name, else by role; optionally masked to body parts, weighted, mirrored) as a new clip, list or delete poses.

pose_mirror

Mirror a pose clip left ↔ right (any rig with a symmetric rest pose: bones pair by .L/.R, _l/_r, Left/Right). Saves it as a new clip (default <clip>_mirrored) and plays it.

prop_grips

A prop's grip points (sockets: where each hand goes, which way the palm faces, which grip closes the fingers), named points (butt, muzzle, trigger, sight) and a gun's trigger guard opening, found from its parts (derived when a gun has no trigger or guard part) or declared in <model>.sockets.json beside it ("trigger_guard": {"center", "half"}).

put_down

A keyed put-down of what a hand holds: lowered to `to` [x, y, z] world (its hold point there; default straight down onto what's under it), the fingers opened, the hand drawn back; the object stays where it was put from the release on. Saved as a clip with the object's track and played.

retarget_clip

Move a pose clip from one character to another with a different skeleton (bones by role; the hips scaled by leg length; keep_feet re-plants the feet where the source planted them). Saves it as a clip for the target (default <clip>_<target>) and plays it there.

rig_aim_hand

Turn a hand so its fingers point toward a place (fingers_toward [x, y, z] world) or along a direction (fingers_dir), and its palm faces a place (palm_toward) or direction (palm_dir); either alone keeps the other as near as it can. The wrist stays where it is. On a weapon hold being edited it goes into the hold. Undoable.

rig_edit_weapon_hold

Edit a weapon hold on the character in the scene: loads Assets/Motion/Poses/<preset>.weaponaim.json onto it (the gun in its hands, as in play) and shows its hand rig. Then turn and move joints with rig_rotate, rig_move and rig_finger: each change goes into the hold relative to the gun (a hand's place on the gun, a finger's curl), the same at every aim pitch, and plays live, in first person too. stance: ready or aim (the stance edited outside Play; in Play, the one shown). Save with rig_save_weapon_hold.

rig_effector

Move a hand, foot, the head, chest or hips (not a joint) with the whole body following: full-body IK keeps lengths and joint limits, leans for what's out of reach, and keeps the feet planted where they stand (pin_feet, default true). to [x, y, z] world or offset [x, y, z]; look_at turns the head. Seen moving over seconds; undoable.

rig_finger

Curl and spread a finger in one go (all its joints), seen moving. curl: degrees each joint bends toward the palm (0 straight, about 90 a fist); spread: degrees away from the middle finger. relative adds to the finger's current pose instead of setting it from rest. finger "all" does every finger. Undoable.

rig_key

Key the character's current pose into a clip at `time` (seconds), with easing to the next key. The clip is saved as Assets/Motion/Poses/<clip>.poseclip.json (plays anywhere, animator clip "Poses/<clip>") with its keys beside it (<clip>.studio.json), and a key strip shows at the bottom of the viewport. remove: true deletes the key at `time`. Key by intent with goals (as pose_character's: "left_foot": {"on": "Wall", "at": "top near edge"}, "right_hand": {"position": [x, y, z]}): they're solved over the pose now (feet planted unless plant_feet false) and kept with the key. bpm sets the clip's beat grid; snap puts the key on it (bar, beat, half, quarter).

rig_move

Move a hand, foot or fingertip to a point (IK), seen moving over `seconds`: to [x, y, z] world, or offset [x, y, z] meters from where it is (world axes). chain is how many joints above it turn (default 2: shoulder and elbow for a hand, hip and knee for a foot, all three finger joints for a fingertip). Lengths never change: a point out of reach stops short. Undoable.

rig_physics

Hand a stretch of a keyed clip to physics: from start to end (seconds) the body is a ragdoll (capsules, human joint ranges) carried by how it was moving, pushed by impulses ([{at: effector (head, chest, hips, left_hand...) or [x, y, z] world, impulse: [x, y, z] newton-seconds world}]: a car's hit is a few hundred), falling onto the floor; blend_in (default 0.1 s) eases into it, blend_out (0.4 s) back into the keys after. The clip is baked and played; keys still edit it. remove: true takes the range at start out.

rig_play

Play a keyed clip on the character in the editor from the playhead (on: false stops it there). loop sets whether it repeats.

rig_pose_get

Read the pose: for each joint its turn from rest (degrees about its own axes, as rig_rotate's absolute mode takes it), its rotation and its world position. Also the picked joint, the joint the person last clicked, the clip and the weapon hold being edited.

rig_release

Give the character back to its animation (drops the pose Pose Studio holds; the rig view stays) and end editing a weapon hold (refused while it has unsaved edits, unless discard: true). Undoable.

rig_rotate

Turn one joint, seen moving over `seconds`. euler [x, y, z] degrees about the joint's own axes (the coloured rings: x red, y green, z blue), or axis [x, y, z] (the joint's own frame) with degrees. mode relative (default) turns from where it is; absolute sets its turn from the rest pose. Lengths never change. On a weapon hold being edited the change goes into the hold. Undoable.

rig_save_weapon_hold

Write the weapon hold being edited back into its .weaponaim.json (every pitch sample), or into a new set with save_as. Reloads it and checks it matches.

rig_scrub

Show a keyed clip's pose at `time` (the playhead moves on the key strip). clip defaults to the one being keyed.

rig_select

Pick a joint: it is drawn large with its axes and rotation rings, so the person sees which one you mean. frame: true moves the camera in close on it (through Follow AI). Without a joint, returns the joint the person last clicked.

rig_view

Show or hide a character's rig in the viewport: every joint as a dot (left side blue, right side orange, middle grey) and the bones as lines, drawn over the body, with short names. labels: all, hands (hands and fingers), limbs (no fingers) or selected (only the picked joint). xray false fades joints behind the body. Also says which joint the person last clicked.

secondary_motion

Overlap baked into a clip: tails, wings, hair and cloth flaps lag, swing and settle behind the body's motion (damped springs on each bone, held at its length, within joint limits). parts picks the chains; stiffness (default 120), damping (9), gravity (0.1: a droop). The character's travel counts when travel is true (the clip's root motion). Saves the result and plays it.

set_move_hitbox core

Create or update a fighter's saved bone-attached attack capsule. A sphere has offset==tip. Exact bones, semantic hand.R/foot.L roles and explicit @root are supported. active_start <= hit frame < active_end at fps; frames includes recovery. Several named boxes may share a move, but each victim is hit once per activation. The clip and real bone path must connect; no missing-bone fallback or added reach. Undoable, protected objects respected.

unequip_item

Take off what a character has in a slot (head, chest, legs, feet, hands, back, main_hand, off_hand or a game's own): its cloth comes off the body, its rider is removed. The running game while it plays, else the scene.

video_to_motion

Turn a video of a person moving (a dance, a vault, a push; one person, whole body in view, a still camera) into an animation clip for our characters: Apple Vision reads the body's 3D pose on every frame, it is retargeted onto the character's skeleton, smoothed, the floor found and levelled, planted feet and hands held still (no skate), spine and neck kept within human limits, and the travel taken out as root motion with contact events (foot_down.l, hand_up.r...). Saved as Motion/Video/<name>.videomotion.json and played as clip "Video/<name>" (animator.clip, add_clip in sequences). variations: N also makes N natural variations (timing, amplitude, arm swing, stride, takeoff/landing, style noise), each re-solved and kept only if it keeps its contacts, doesn't skate or over-stretch and isn't jerkier: saved as <name>_v1... Returns the metrics, a side-by-side sheet (video frame over the character, same moments) and a sheet of the variations.

warp_pose_clip

Motion warping: re-fit a keyed pose clip to other objects (a higher wall, a wider window). Each goal anchored to an object moves to the same spot on the new object's box (rename maps old object names to new ones; the same names re-fit to their current size), the keys are re-solved on the character, the clip re-baked, saved (as save_as) and played.

weapon_tune

While playing (play_mode): tune the player's gun live, no script edit. `shot` options win over what the gun's kit passes, from the next shot: damage, headshot, speed (m/s), spread (°), range (m), drag, gravity, mass (kg), recoil (° of view kick), kick {back, up, side}, tracer, shell, flash, flash_size (×, 1.6), flash_light (lm), loudness. `remove` names options to stop tuning; `clear` drops them all first. `view` is first-person weapon data laid on the player's weapon: pattern [[up°, right°], ...] per shot of a burst, hip_recoil / ads_recoil {view, back, up, side, roll}, recovery, recovery_delay, ads_in, ads_out, ads_zoom, view_fov, ads_view_fov, zero, sight. `debug_view` true draws the last 4 s of shots: their flight (yellow), a red box on a body hit, orange where a round went on through, white where one met a surface. `save` "carbine" writes what is tuned into the project's Weapons/carbine.weapon.json ({ params, shot, view }), which the gun kit lays over its params as it starts and when the gun is equipped. Returns what is tuned now.