Rigging & animation

An AnimFile whose name contains a hyphen never reaches the compiled model. The fbx bakes, the animation list writes, the vmdl compiles green with no errors and no warnings, and the sequence is simply absent at runtime. The SkinnedModelRenderer.Sequence.Name setter accepts the missing name and echoes it back, so the obvious guard cannot fire. Sanitise the typed name to one hyphen-free word, and check Sequence.SequenceNames before you assign.

A SkinnedModelRenderer created this frame has no attachment objects yet, and reading a bone before the first pose evaluates returns the bind pose. Resolving a mount in OnStart silently gets nulls or T-pose transforms, no exception either way. Defer and retry.

The stock citizen animgraph ships combat params that CitizenAnimationHelper does NOT wrap -- drive them with renderer.Set() directly, and replicate them yourself because the engine only networks locomotion.

The Citizen animgraph drives body aim from SetLookDirection("aim_body", dir, weight), not from the aim_body_pitch / aim_body_yaw floats. Writing only the floats reads back perfectly and moves the pose zero degrees.

HoldType shapes arm+fingers, body aim tilts via SetLookDirection (the aim_body_pitch/yaw floats are readback-only), and an IK hand target OWNS hand position, overriding the holdtype arm pose. Move the IK target to place a held item, use holdtype only for the fist.

Set Sequence.Blending = true once: per-clip fade_in/fade_out times in the vmdl shape the blend; no AnimGraph required.

Foot-slide happens when PlaybackRate is tied to movement top speed instead of the clip's own authored stride distance.

Converting euler poses per-key can land on q vs -q. The interpolation takes a violent 360-degree detour. Negate the quat if dot(prev, new) < 0.

The citizen's locomotion clips each carry their own authored ground speed in the animgraph's m_blendValue coordinates. Pacing every clip's PlaybackRate against one guessed nominal speed foot-slides every variant except the one it was tuned for.

PhysicsShapeList + PhysicsJointList in the vmdl + ModelPhysics toggle. No collapse clips, no SetBoneTransform. On current builds ModelPhysics.PhysicsGroup reads NULL: enumerate ModelPhysics.Bodies directly and resolve bones by name→index.

Transfer rest-delta rotations parent-relative (not world): avoid the forward-hunch bug and never transform_apply scale on Mixamo armatures.

Bone-heat auto-weights fail on AI meshes. Use scripted geodesic (along-surface) weights, then FBX + animated vmdl.

When a clip already poses hands in a grip and the prop moves/rescales, offset the rendered visual child instead of using IK or SetBoneTransform -- sequence-only rigs have no AnimGraph.

Direct citizen sequence playback needs no AnimGraph, but SkinnedModelRenderer.UseAnimGraph must be set false BEFORE the first Sequence.Name write, or the write silently no-ops while the model's own animgraph keeps driving the pose. The citizen model exposes 466 sequences (raw directional locomotion + IdlePose family), enough for a full movement set with no rig work.

Model compiler rewrites upper_arm.L → upper_arm_L; physics KV3 that still says .L makes limb bodies unknown while the torso works.

The Citizen ragdoll physics rig has 18 shapes (17 capsules plus 1 cylinder) and 16 joints (12 conical ballsockets plus 4 revolute hinges). A common folk estimate lands near 9 to 13 bodies, roughly half the real count, so it undercounts per-body and joint-solve cost. Both prefab files are plain KV3 text, so you count them offline with no editor running.

Default −Z/Y axes, bake_space_transform, no leaf bones, X/Z bone axes, mesh FBX + per-clip armature FBX; scale via ScaleAndMirror 0.3937.

SetIk is AnimGraph-gated; SetBoneTransform is unsound on clip-keyed bones. Use proxy props, whole-visual motion, or commit to AnimGraph.