stickman/RIGGING.md

Stickman Rigging

We currently have a test harness to .stk files to be loaded, and figured to be tested by moving IK guides. We need to plan and implement several new features to the rigging and the harness.

Task 1: Skeleton IK bone switches

The stickman will eventually be able to move in different 'directions', to make movement look better we need to build bone modification switches into the rig (master_rig.tscn)

Bend direction

Each IK modifier in the skeleton has a 'Flip Bend Direction' flag. This flag needs to be made available to the user's stickman figure so that the switch can be changed dynamically.

• In the test harness, a user should be able to right click on a non-leaf joint (upper-lower limb connector) and select from a dropdown context menu 'Normal Bend' or 'Invert Bend'
• The menu should look like the stickman editor's 'Hide Pose' vs 'Show Pose' item. When the normal bend is currently on, the menu will show invert bend and also the other way around.

Rig bend direction profiles

Eventually, the stickman will be able to face different directions. There needs to be a selectable profile that can be set by the user. Each profile changes the 'flip bend direction' on the rig.

Left

The rig if 'facing' left, it will have the following bend profiles for these bones

• Left Arm (Upper/Lower Left Arm joint): Flip Bend Direction - off
• Right Arm (Upper/Lower Right Arm joint): Flip Bend Direction - off
• Left Leg (Upper/Lower Left Leg joint): Flip Bend Direction - on
• Right Leg (Upper/Lower Right Leg joint): Flip Bend Direction - on

Right

The rig if 'facing' right, it will have the following bend profiles for these bones

• Left Arm (Upper/Lower Left Arm joint): Flip Bend Direction - on
• Right Arm (Upper/Lower Right Arm joint): Flip Bend Direction - on
• Left Leg (Upper/Lower Left Leg joint): Flip Bend Direction - off
• Right Leg (Upper/Lower Right Leg joint): Flip Bend Direction - off

Forward

The rig is looking 'at the user'

• Left Arm (Upper/Lower Left Arm joint): Flip Bend Direction - off
• Right Arm (Upper/Lower Right Arm joint): Flip Bend Direction - on
• Left Leg (Upper/Lower Left Leg joint): Flip Bend Direction - on
• Right Leg (Upper/Lower Right Leg joint): Flip Bend Direction - off

The harness should have a control to set the direction profile. Maybe we should consider a menubar (Like the stickman editor) If a profile is selected, just set the flags corresponding to the profile. The user will still be free to change the bend direction by right clicking and changing them manually. Changing the profile WILL change the context menu item for each individual joint. Whether the context menu shows 'Normal' or 'Invert' bend depends on the current flag setting on that bone joint.

Task 2: Body part z-order

Implemented (Phase 9 Task 2) — see docs/phase9_task2_zorder_spec.md; the harness reorders the rig's Body/* children from the Facing profile (test harness top-bar "Facing" menu).

When the stickman is facing certain directions, body parts need to be drawn in a certain order:

1. When 'facing' left, the left lower/upper arm and lower/upper leg need to be drawn 'behind' the torso, while others in front
2. When 'facing' right, the right lower/upper arm and lower/upper leg need to be drawn 'behind' the torso, while others in front
3. When 'facing' forward, the legs and arms should be drawn in front of the torso.
4. On the far (behind-torso) side the arm draws behind the leg; on the near (in-front) side the arm draws in front of the leg.
5. In all cases, the head should be drawn in 'front' of the torso.

Task 3: Coordinates display

Implemented (Phase 9 Task 3) — see docs/phase9_task3_coords_spec.md; the harness adds a "Show Coords" checkbox (top bar, default ON) and a code-built top-right readout panel (_coords_panel + monospace _coords_label) showing, per frame, the Skeleton2D position and rotation, all 10 bone positions and rotations, and the 6 IK target positions (world-space values, rotation in degrees). "No rig loaded" when no rig is spawned.

The harness should have a display that can be shown or hidden that will display the following information:

1. Skeleton2D position and rotation
2. Bone positions and rotations

• Torso
• Head
• LeftUpperArm
• LeftLowerArm
• RightUpperArm
• RightLowerArm
• LeftUpperLeg
• LeftLowerLeg
• RightUpperLeg
• RightLowerLeg

3. IK target positions

• Head
• Torso
• Right_Hand
• Left_Hand
• Right_Leg
• Left_Leg

The display should be easy to read to the right side of the screen. There should be a checkmark display like 'show ik bones' to show and hide the coordinate display.

Task 4: Refactor facing direction / bone bend

We need to have facing direction and bone bend to be a part of the master_rig.tscn. This rig will be used for instances of stickmen which will be able to face different directions / have different bone bending at a time. So rather than keeping that data in the harness, we need it in the master rig. These should probably be exported controls too so that they can easily be accessed.