cs68614-hash/costage/character-action-design

CoStage Character Action Design

Turn an action intention into a readable CoStage character key pose, or decompose a complex movement into inspectable action phases for previs.

Current Capability Boundary

CoStage currently stores one static 25-field pose per character. It does not yet store skeletal animation clips, interpolated pose tracks, root-motion curves, hand or foot IK constraints, or contact events.

• For a request such as “make A throw a punch,” apply the most narratively useful hero pose and state which phase was chosen.
• For dance, martial arts, sports, or other continuous movement, first design a phase plan. Apply only the requested phase, or the clearest hero phase when the user asked to pose the character without naming a phase.
• Use action-stage timeline shots to preserve different real key poses and root positions at different story moments. Do not call the discrete transitions continuous character animation.
• Do not claim smooth playback, planted feet, hand contact, or collision response when the system cannot represent it.

Execution Contract

1. If the user asks only for a plan, provide an action-phase plan without changing the stage.
2. If the user asks to create, pose, adjust, apply, or stage an action, open CoStage when needed and call get_director_stage_state before editing.
3. Preserve the returned stageDir and use it for every subsequent MCP call.
4. Identify exact character IDs. Never guess from labels when multiple nodes share a label.
5. Copy the character's complete current pose, change intentional values, then send the complete pose object through update_node. A partial pose patch can discard untouched fields.
6. Keep root position, root rotation, object scale, and skeletal pose separate. Root rotations are radians; pose fields are degrees.
7. Preserve the real modelUrl, modelName, modelScale, and other character fields. Never replace a failed model with geometry or an invented resource.
8. Re-read the state after applying changes and verify all requested characters numerically.

Use director-stage-compose for scene placement, semantic relationships, object scale, and camera composition. Use this skill for body mechanics, action phases, pose values, silhouette, balance, and interaction intent.

Action Workflow

1. Define the beat

Write down:

• actor and target;
• action family and exact verb;
• phase: preparation, action, impact/accent, follow-through, recovery;
• travel direction and gaze target;
• support side and gesture/attack side;
• energy: soft, suspended, sharp, heavy, explosive, restrained;
• camera-readable result.

Vague verbs produce vague poses. Prefer “right straight punch at B's chest, impact phase, left leg supporting” over “fighting.”

2. Establish root blocking

Use semantic placement operations before posing:

• arrange_facing_pair for two participants facing each other;
• orient_toward for a gaze or attack target;
• place_relative for approach, retreat, screen-side, and depth relationships;
• arrange_group for dance formations, teams, crowds, and surrounding actions.

The skeleton pose does not correct wrong distance or root orientation. For paired actions, place both performers first, leave believable reach, then pose both sides of the interaction.

3. Build the pose from the ground up

1. Choose the support leg and body level.
2. Set pelvis direction and weight intention with body controls.
3. Counter-rotate the torso when the action needs torque.
4. Aim the head and gaze toward the target or dramatic counterpoint.
5. Shape the primary arm or leg that communicates the action.
6. Use the opposite limbs for balance, defense, rhythm, or secondary story information.
7. Introduce purposeful asymmetry so the silhouette does not read as a mannequin preset.

See references/pose-schema.md for the real fields and ranges.

4. Apply atomically

Send one apply_director_stage_operations call when changes belong to one action beat. Root placement/orientation operations should precede each character's update_node operation in the same call.

For update_node, pass category: "characters", the exact node id, and a patch containing the complete 25-field pose. Add root position or rotation to the same patch only when the action beat changes blocking.

When the requested action belongs in the shot timeline, prefer create_director_timeline_shot with actionStage and characterUpdates. Use a new action-stage ID only when position, root rotation, or pose really changes. Reuse the existing ID without character updates for additional cameras covering the same instant. The tool rejects a new non-setup stage whose performance state is unchanged.

If an existing timeline action is refined after its shot is opened, apply the pose edit to the live character and then call refresh_director_timeline_shot. This is required to overwrite the frozen action-stage snapshots and regenerate their thumbnails; editing the live scene alone is not timeline synchronization.

5. Verify

Re-read the active scene and check:

• the expected character ID has all 25 finite pose values;
• every value is inside the editor range;
• the support and gesture sides match the request;
• root facing matches the target and participants do not overlap;
• the character remains on the intended ground level and at usable scene scale;
• the active camera can read the line of action and key silhouette.

Correct failed checks before reporting success.

Pose Design Principles

• Line of action: make one dominant curve or thrust readable through pelvis, torso, head, and gesture limb.
• Weight: bend and load the support side; the free side may reach, kick, step, or counterbalance.
• Counter-rotation: hips initiate many forceful actions while the torso twists against or through them.
• Silhouette: separate limbs from the torso enough to read from the chosen camera without flattening every pose into a front view.
• Asymmetry: vary shoulders, elbows, hips, knees, and head unless symmetry is the intended graphic idea.
• Anticipation and recovery: an action phase should visibly differ from its preparation and aftermath.
• Eyeline: head direction should support the target, intention, or reaction rather than remain neutral.
• Restraint: use the smallest change that communicates the beat. Extreme values are not automatically more dynamic.

Complex Actions

Dance

Break choreography into counts or accents. Track support leg, body level, travel direction, torso rhythm, arm line, gaze, and energy on each selected count. Use references/dance-key-poses.md.

Martial arts and fights

Separate guard, chamber/anticipation, attack, impact, follow-through, and recovery. Design attacker and receiver as one paired beat and verify target distance before posing. Use references/martial-key-poses.md.

Interaction and balance

For lifting, holding, embracing, pushing, pulling, handing over, sitting, kneeling, or prop use, define support, contact intention, and relative spacing first. Current controls end at forearms and calves, so treat hands, feet, toes, and exact contact as visual approximations. Use references/interaction-and-balance.md.

Completion Report

After an executed change, report:

• scene and character IDs changed;
• action and phase applied;
• root relationship or facing change, if any;
• whether the result is a static key pose or a multi-phase plan;
• any limitation that affects the requested action, especially missing IK or continuous animation.