agentleFS
szlayszlay/roblox-base/.claude/skills/roblox-animated-models/SKILL.md

roblox-animated-models

Skill1 starsChanged 4 months agoMITView on GitHub

Use when an animated model comes in from outside Roblox - a glTF/FBX character or creature from Kenney, Quaternius or Mixamo - and its animations have to play in game.

  • Installs packages

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every leg should land on the opposite extreme, and diagonal pairs should agree - that is a trot, and it cannot happen by accident.

    line 158
  2. Distinctive:

    Check the rest pose too: right at rest and wrong in motion is a joint problem, wrong at rest is a coordinate problem.

    line 168
  3. Very specific:

    One RunService connection for all of them,: not one per pet. RigAnimator already does this.

    line 224

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Roblox animated models

When to Load

Load when a model from outside Roblox is supposed to move: a pet, a creature, a crowd character, an animated prop. Pair with roblox-assets for getting the geometry in and roblox-animation-vfx for Roblox-native animation of player characters, which is a different problem with a different answer.

First, which kind of animated model is it

This decides everything after it, and it is decided by the file, not by preference. Look for a skins array.

Node animation (rigid parts)Rigged / skinned mesh
In the fileskins is empty, each body part is its own mesh with its own keyframesskins is non-empty, bones deform one mesh
Typical ofKenney kits, most low-poly "cube" packsKenney's animated characters, Quaternius, Mixamo
Rig comes fromthe game builds it from raw meshesonly the uploaded Model asset - a raw mesh has skin weights but no Bone
What you driveMotor6D.TransformBone.Transform
Resize witha -Scale pass in the bakerModel:ScaleTo - never Size
Moves in edit modeno (needs the physics step)yes (skinning is render-time)
Pipeline belowAB
python -c "import json,struct,sys;d=open(sys.argv[1],'rb').read();\
n=struct.unpack('<I',d[12:16])[0];j=json.loads(d[20:20+n]);\
print('skins',len(j.get('skins',[])),'meshes',len(j.get('meshes',[])),\
'clips',[a.get('name') for a in j.get('animations',[])])" animal-fox.glb

If the pack ships .fbx and no .glb, convert first - both bakers read glTF. There is no converter in this repo's toolchain, so fetch one; it is a build-time tool, like StyLua:

npm install fbx2gltf
node_modules/fbx2gltf/bin/Windows_NT/FBX2glTF.exe -i in.fbx -o out --binary

Roblox's own importer accepts .fbx directly, so the upload still takes the original file. The conversion exists only so the baker can read the clips.

Count the clips before choosing. The whole reason to bake is that Roblox has no API to upload an Animation asset, so 24 animals x 8 clips would be 192 manual publishes. A single character with three clips is three manual publishes, and the official Animation Editor route gets blending, events and IK for free. Bake when the count is large, when the repo must stay the source of truth, or when nobody can be asked to click through Studio. Say which reason applies.

The problem with the official route

Roblox has no API that uploads an Animation asset. KeyframeSequence can be built in code, but publishing one needs Studio's UI, by hand, per clip. A kit of 24 animals with 8 clips each is 192 manual uploads, and none of it is reproducible from the repo.

Open Cloud does accept the .glb as a Model, and - usefully - Roblox's importer builds a real rig out of node animation: a RootPart, one MeshPart per node, a Motor6D per part, and an InitialPoses folder. It just does not bring the clips along.

So: get the rig geometry and the clips out of the file yourself, and write the transform property an Animator would have written. This template has one pair of pieces per kind of model:

rigid partsskinned
Bakerscripts/bake-gltf-animation.ps1scripts/bake-skinned-animation.py
Runtimesrc/shared/RigAnimator.luausrc/shared/SkinnedAnimator.luau
Worked exampleexamples/pets/examples/characters/

Pipeline A: rigid parts

download .glb -> upload once as Model + texture -> read the raw mesh IDs
    -> catalogue the IDs -> bake the clips -> build and play -> verify in Studio
  1. Download to _assets/<kit>/ (gitignored). CC0 sources only; see roblox-assets.
  2. Upload once. The Model upload is a discovery step, not a runtime dependency:

    pwsh scripts/upload-asset.ps1 -Path _assets/kenney_cube-pets/animal-fox.glb -Name CubePetFox
    pwsh scripts/upload-asset.ps1 -Path _assets/kenney_cube-pets/colormap.png -Name CubePetsColormap -AssetType Image

    Kit textures are a separate file and must be uploaded as Image, never Decal - MeshPart.TextureID silently ignores a Decal.

  3. Read the raw mesh IDs. Insert the Model once in Studio, read MeshId off every MeshPart, then throw the inserted copy away.

    local model = game:GetService("InsertService"):LoadAsset(140078852623094)
    model.Parent = workspace
    for _, d in model:GetDescendants() do
        if d:IsA("MeshPart") then print(d.Name, d.MeshId) end
    end
  4. Catalogue the mesh IDs and the texture ID (examples/pets/PetAssets.luau is the worked shape). From here on the game builds the rig from raw meshes and never loads the Model asset again - a raw mesh cannot carry a script, a Model can.
  5. Bake the clips.

    pwsh scripts/bake-gltf-animation.ps1 -Path _assets/kenney_cube-pets/animal-fox.glb `
        -Out examples/pets/FoxRig.luau -Name Fox

    The output is version-controlled text: node tree, part sizes, joint offsets, and one line per keyframe. Never hand-edit it; re-run the script.

    -Clips walk,idle bakes a subset. Call the script with & rather than pwsh -File for that - with -File every argument arrives as a string, so walk,idle becomes one clip name that matches nothing and the script stops with "has no animation clips to bake".

  6. Build and play.

    local model = RigAnimator.build(FoxRig, asset.meshIds, { textureId = asset.textureId })
    model.Parent = workspace
    local pet = RigAnimator.new(model, FoxRig)
    pet:play("walk", { fadeTime = 0.25 })
  7. Verify in Studio - in Play mode. Edit mode runs no physics step, so nothing moves there however correct the maths is (see Sharp edges). Start play, build the rig in the Client datamodel, and prove the motion two ways:

    -- Cheap and decisive: freeze two phases half a cycle apart and compare.
    local animator = RigAnimator.new(model, rig)
    animator.clipName = "walk"          -- bypass play(), stay out of the updater
    animator.time = 0                   -- then 0.5 * rig.clips.walk.duration
    animator:step(0)

    Every leg should land on the opposite extreme, and diagonal pairs should agree - that is a trot, and it cannot happen by accident. Then one capture per phase for how it looks. Two captures of a live clip are a weak test: they land on arbitrary phases and often look identical.

    Find the extremes, do not assume them. t = 0 and t = duration / 2 are the extremes of the fox's walk and the zero crossings of Kenney's blocky walk, where the pose is genuinely identical at both. Scan the track for the largest and smallest rotation first, or a working clip reads as a dead one.

    Check the rest pose too: right at rest and wrong in motion is a joint problem, wrong at rest is a coordinate problem.

The three facts that make pipeline A work

Everything hard about this route is in these, and the baker handles all three. Details and the derivation are in references/full.md.

  1. Roblox imports glTF turned 180 degrees around Y. Both are right-handed and Y-up, so it is a pure change of basis: negate x and z on positions and on the quaternion's axis. Do it to every local transform and the parent chain still composes, so the runtime never has to know.
  2. A MeshPart is centred on its own bounding box, not on the glTF node. The node is what the animation rotates around; the part sits some constant hop away from it. Both have to be kept: joint (where the part rests, which becomes C0) and offset (node frame -> part frame).
  3. Motor6D puts the part at Part0.CFrame * C0 * Transform. So the transform to write is

    Transform = C0:Inverse() * animatedNodeWorld * offset

    which is the identity at rest. The baker asserts exactly that before it writes anything, which is what catches a bad rig before Studio does.

Sharp edges, rigid parts

  • Edit mode does not move the parts. Motor6D.Transform is applied by the physics step, and Studio's Edit mode does not run one: the values change every frame and the meshes stay exactly where they were. This looks precisely like a broken rig. Read Motor6D.Transform to confirm the maths in Edit mode, but judge the motion in Play mode only.
  • The rig root is not at ground level. The glTF origin sits wherever the artist left it - the fox's feet are 0.079 studs above its root. Place the model by measuring, not by guessing:

    local lowest = math.huge
    for _, p in model:GetChildren() do
        if p:IsA("MeshPart") then lowest = math.min(lowest, p.Position.Y - p.Size.Y / 2) end
    end
    model:PivotTo(model:GetPivot() + Vector3.new(0, groundTop - lowest, 0))
  • A constant node scale is folded in; an animated one is dropped. A Motor6D cannot scale, but a rest scale is a constant, so the baker multiplies it into the part size and into every translation below the node. This is not cosmetic: Kenney's blocky characters author the head mesh ten times too big and scale it down by 0.1 at the node, so dropping it gives a head the size of the body. Only animated scale is really lost, and the baker says so. Non-uniform rest scale is refused rather than approximated.
  • Run it on the client. This is cosmetic motion. Writing Motor6D.Transform on the server replicates every joint of every pet to every player for nothing.
  • One RunService connection for all of them, not one per pet. RigAnimator already does this; keep it that way when adding to it.
  • Never load the Model asset at runtime. It works, and it quietly gives up the "geometry only, never Models" rule that keeps backdoor scripts out. Build from raw mesh IDs.
  • Check the scale against a character. Kenney's pets come out around 1.5 studs tall against a 5-stud player, which is right for a pet and wrong for anything meant to be ridden. Rescaling means rescaling size, joint and offset together - a -Scale pass in the baker, not a model:ScaleTo().
  • Anchor the root, and only the root. The limbs must stay unanchored or the joints cannot move them; the root must be anchored or physics pulls the assembly apart.
  • CanCollide = false on every limb. Six colliding meshes inside one pet is a physics bill for nothing.

Pipeline B: skinned characters

Roblox's importer does the hard part here: hand it the .fbx or .glb and it produces one MeshPart with HasSkinnedMesh = true and a Bone per joint, plus an InitialPoses folder recording every joint's rest transform. What it still will not bring is the clips.

download -> upload the model as Model + skins as Image -> convert the clips to glTF
    -> dump the rig's bone rest pose out of Studio -> bake -> play -> verify
  1. Upload the model and the skins. The model upload is not only discovery this time - the Model asset is where the skeleton lives, so it stays a runtime dependency. Skins go up as Image, one per look.
  2. Convert the animation files to glTF (see above). The clips usually arrive as separate files - idle.fbx, run.fbx - carrying the skeleton and curves but no mesh.
  3. Dump the rig's bone rest pose. Insert the Model once in Studio and write this out; commit it next to the clips so the bake never needs Studio again. It is the calibration the whole bake hangs on.

    local mesh = model:FindFirstChildWhichIsA("MeshPart", true)
    local rows = {}
    for _, d in mesh:GetDescendants() do
        if d:IsA("Bone") then
            d.Transform = CFrame.identity
            local parent = if d.Parent:IsA("Bone") then d.Parent.Name else "-"
            local x, y, z, r00, r01, r02, r10, r11, r12, r20, r21, r22 = d.CFrame:GetComponents()
            table.insert(rows, string.format("%s|%s|%f,%f,%f|%f,%f,%f,%f,%f,%f,%f,%f,%f",
                d.Name, parent, x, y, z, r00, r01, r02, r10, r11, r12, r20, r21, r22))
        end
    end
    table.sort(rows)
    return table.concat(rows, "\n")

    Insert a fresh copy for this. See the InitialPoses sharp edge below.

  4. Bake.

    python scripts/bake-skinned-animation.py --model glb/characterMedium.glb `
        --rest examples/characters/CharacterRest.txt `
        --out examples/characters/CharacterClips.luau --name CharacterMedium `
        --clip glb/idle.glb=idle --clip glb/run.glb=run
  5. Play. SkinnedAnimator.fit sizes it and puts the skin on; SkinnedAnimator.new(model, clips):play("run") drives the bones.

The two facts that make pipeline B work

  1. Bone.TransformedCFrame is Bone.CFrame * Bone.Transform, and TransformedWorldCFrame is the parent's times that. So Transform is the bone's motion in its own rest frame - the same shape as Motor6D, and the reason no world composition is needed at runtime.
  2. A skinning matrix is a world-space transform of geometry, so the glTF space and the Roblox rig's space are related by one global similarity M. Roblox's importer picks different bone axes than the glTF does, and those per-bone differences cancel:

    skin(B,t)      = worldAnim_gltf(B,t) * inverseBindMatrix(B)
    TWC(B,t)       = M * skin(B,t) * M^-1 * worldRest_roblox(B)
    Transform(B,t) = restLocal(B)^-1 * TWC(parent,t)^-1 * TWC(B,t)

    M is fitted from the dumped rest pose and then checked - the baker refuses to write if the two skeletons do not line up, or if any bone changes length in any frame. Both failures otherwise show up as a mangled or tipped-over character.

Sharp edges, skinned

These two cost an afternoon each, and both fail by looking like a broken rig while every number checks out.

  • A baked Transform translation is in the rig's original bone space. Model:ScaleTo scales Bone.CFrame but not the Transform you write onto it, so a hip that rises 13 studs on the 376-stud import still rises 13 studs on the 5-stud copy and throws the character off its feet. Multiply the translation by model:GetScale(); SkinnedAnimator does. It reads as a stumble or a jump, not as a bug.
  • Model:PivotTo twists an imported skinned model. Its pivot carries the importer's Z-up frame, not the mesh's, so PivotTo(CFrame.new(p) * CFrame.Angles(0, y, 0)) comes out as a -90 degree turn about X: the character lies face-down while every limb still looks correctly articulated. Position-only PivotTo is fine, which is why this hides until something needs to face a direction. Place through model.PrimaryPart.CFrame instead.
  • Size destroys a skinned mesh. It stretches the geometry and leaves the bones behind: a featureless tube. Model:ScaleTo scales the bones with it and is the only correct resize.
  • A raw mesh ID gives no bones. CreateMeshPartAsync returns HasSkinnedMesh = true and zero Bone children. This is the one case where the game must load its own uploaded Model - run AssetLoader.sanitize on it and report anything stripped. An FBX cannot contain a script, so the count should always be zero; if it is not, the asset is wrong.
  • Do not restore bone CFrames from InitialPoses. The values there are in the importer's Z-up space. For child bones they happen to match Bone.CFrame, for the root bone they do not, and writing them back tips the character over while every child still looks articulated. Re-insert the asset instead.
  • The bind pose is baked into the mesh, not into the bones. Moving a Bone.CFrame deforms the character rather than redefining its rest, so the skeleton cannot be re-oriented to match the glTF. That is what forces the M fit above.
  • FBX is usually in centimetres. This character imported 376 studs tall. It does not look wrong until something 5 studs tall stands next to it.
  • One FBX holds more than one clip. These exports carry a one- or two-frame 0.Targeting Pose beside the real animation. Pick by keyframe count, not by order.
  • Bone lengths belong to the model, not to the clip. Kenney's animation files come from a rig whose finger bones differ from the model's by a few percent; trusting the clip shortens the fingers by a third. Take rotations from the clip, translations from the model, and translation channels only on the root bone.
  • Roblox drops the IK and helper bones. 45 joints in the file, 33 Bones in Studio; the run clip animates ten that do not exist. Harmless here because the deforming (FK) bones are keyed too - but check that before assuming.
  • TransformedWorldCFrame is stale in edit mode. It does not propagate a parent's Transform down the chain, so it cannot be used to check a pose. Compose TransformedCFrame yourself, which is reliable.

Need the details? Load references/full.md for the coordinate derivation, the baked data format, and the full RigAnimator API.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.