roblox-box-animal

Roblox box-rig animals

You write one small data file for each animal: palette, bones, boxes and clips. scripts/boxrig.py turns that file into the mesh, studs, rig, animations, mutations, renders and exports.

Examples, with previews in examples/previews/:

• examples/penguin.py: a biped.
• examples/dragon.py: a full-size dragon: smooth voxel body/S-neck/tail + box-built head, horns, plates and bat wings, with a jaw and a fire-breath idle.
• examples/lion.py: an anatomy-correct lion with the chunky look: smooth voxel body, big studs, pixel-art face drawn on the voxel grid. examples/lion_chibi.py is the old chibi lion, kept as a box-API example.

Requirements

• Blender 4.2 or later, run headless. On Windows look in C:\Program Files\Blender Foundation\Blender */blender.exe; on Mac, /Applications/Blender.app/Contents/MacOS/Blender. Tested on 5.1.
• Python 3 with Pillow and numpy: py -m pip install --user pillow numpy. Don't run the scripts with py -I.
• Placeholders below: <B> = the Blender executable, <S> = this skill's folder.

Workflow

1. Spec, anatomy first (user rule). Every animal gets the structure of the real animal: its real body plan, proportions and silhouette, built from blocks. Never a cube character with features stuck on.
   • Read reference/anatomy.md. Look up the real animal, or use the user's reference.
   • Write its proportions in shoulder heights as comments in the data file: body length, head, neck, legs, tail.
   • Block out the side silhouette with big shapes, and match it before adding detail.
   • Chibi or "cute pet" proportions (big head, stub legs) only when the user asks for them.
   • Note 2–4 signature traits and the clips (default Walk, Run, Idle). A user's reference image or model is the spec.
   • Decide the scale: a Roblox character is about 5 studs tall; pets are 4–8 studs; real-size creatures are life-sized (a dragon is about 40 studs long). Don't shrink big animals.
2. Copy the closest example into the user's folder, or run py <S>/scripts/new_animal.py <Name> quad|biped <folder>. Never edit inside the skill.
3. Edit the data. Read reference/design_guide.md first.
4. Build and render:

   <B> -b --factory-startup --python <S>/scripts/boxrig.py -- <animal.py> all
   py <S>/scripts/make_sheet.py <out_dir> _v1
   

   • <out_dir> is out_<Name> next to the file.
   • The modes are views (fast, for shaping), gif, export, mutations (views, export and mutations) and all.
5. Review <Name>_sheet_vN.png, review_<Clip>_vN.png and <Name>_mutations_vN.png. Fix the data and rebuild with a new tag, because the Read tool caches images by path. Usually 3–5 rounds.
6. Verify: <B> -b --factory-startup --python <S>/scripts/verify_fbx.py -- <out_dir> must print VERIFY_OK.
7. Deliver the sheet, the mutation sheet and the GIFs.
8. Studio, if the Roblox Studio MCP is connected. Follow reference/roblox_studio.md: import, fix-up, BoxRigAnim plus <Name>Clips for poses and KeyframeSequences, MutationFX, then a measured playtest.

Data file cheat sheet

• Units and axes: studs, Z up, front = -Y, the animal's left = +X.
• Boxes: box(x0,x1, y0,y1, z0,z1, colour, bone). sym(...) mirrors the box to the right side, with % becoming L or R in the bone name; box with % in the bone does the same. A later box wins where boxes overlap.
• Voxel sculpting (the default for creature bodies): set VOXEL small enough for smooth curves (about 1/90 of body length: 0.5 on a big dragon, 0.2 on a lion) and STUD_SIZE bigger (2–4 cells, e.g. 1.0 / 0.8) so studs stay chunky and readable. Then:
  • vell(cx,cy,cz, rx,ry,rz, col, bone): ellipsoid.
  • vcap(p0, p1, r0, r1, col, bone): tapered capsule, for necks, legs, tails, horns and snouts.
  • vbox(...): box.
  • vsheet(origin, u, v, pts, thick, col, bone): flat polygon, for wings, fins and frills; bone ('a', split, low, high) splits it between two bones.
  • Options: paint=True recolours existing voxels only (belly stripe, eyes, markings); paint='belly' recolours only cells of that colour (bands across a stripe); '%' in the bone mirrors to L and R; mirror=True mirrors on the same bone (horns, teeth).
  • Everything is voxelized on one grid and greedily meshed. Keep radii at or above one voxel, or thin parts break up. Read "The default style = smooth SHAPE + chunky LOOK" in reference/design_guide.md.
• Organic shapes, box-based (older chunky style):
  • ell(cx,cy,cz, rx,ry,rz, colour, bone) is a rounded stepped blob made of 3 boxes. Use it for bodies, chests, hips, neck segments, thighs and tail segments.
  • poly([(x,y),...], z0, z1, colour, bone, step=1.0) fills a top-view outline. Use it for wing membranes, fins, frills and tail spades. bone can be a function of x, to split a membrane across Wing and WingTip.
  • beam(p0, p1, width, z0, z1, colour, bone) is a straight bar, for arm bones, wing fingers and horns.
• Winged animals: model the wings spread flat, then fold them in the clips with wing_rest=(raise, tip_droop, sweep); the dragon uses (58, 24, 22). Set VIEW_POSE = ('Idle', 0) so the sheet shows the animal standing with its wings folded.
• Bones: BONES[name] = (parent, head, tail). Exactly one root at (0,0,0), which has no boxes. The head point is the pivot.
  • Quad clips need Body, Head, FrontUpper/Lower_L/R and BackUpper/Lower_L/R. Optional: a tail chain, a neck chain, wings=('Wing','WingTip') and a jaw.
  • Biped clips need Body, Head and Leg_L/R. Optional: Foot_L/R, Wing_L/R and a tail.
• Clips: CLIPS = {'Walk': (fn, frames), ...} at 30 fps, seamless, in place.
  • Ready-made factories (keyword arguments only):
    • quad_walk, quad_run, quad_idle(jaw=, yawn=), quad_fly
    • biped_walk, biped_run, biped_idle, biped_fly
  • Animals that fly (dragons, birds, griffins, bats, anything with working wings), a user rule:
    • Walk is a ground walk: the legs move and the wings stay still. Use quad_walk(..., wings=..., wing_flap=0), or biped_walk(..., wing_flap=0).
    • Run is flying: the wings beat and the legs don't run; they stay tucked and still. Use quad_fly(...) or biped_fly(...), never quad_run or biped_run.
    • Never flap the wings while the legs run.
  • Fire breath (dragons and other breathers): quad_idle(jaw='Jaw', yawn=26, fire=(0.55, 0.75)) plus MOUTH = (x, y, z) and MOUTH_BONE = 'Head' in the data file.
    • The clip rears back and inhales, then thrusts forward with the jaw open from t0 to t1.
    • The GIFs show a stand-in flame. In Studio, assets/FireBreath.lua drives real flames from the clip's FireStart and FireStop markers, coloured per mutation.
    • Fire never shows in the Animation Editor, which plays bones only. To show it in Edit mode, use assets/BoxRigPreview.lua.
    • A forward-pointing jaw opens down with rx +. rx - swings it up into the skull, where it looks like it vanished.
  • Typical lengths: walk 32–40 frames, run 18–24, idle 90–150.
  • Big animals move slower and heavier: more frames, larger bob and bounce in studs, and a lower pitch.
  • A custom clip is fn(t) -> {bone: ((rx,ry,rz) degrees about world axes at the joint, (tx,ty,tz) studs)}. Signs: rx + swings a foot back, nods a head down and lifts a tail.
• Mutations (Gold, Diamond and Shadow by default) come from MUTATIONS in boxrig.py.
  • Each one maps the palette's brightness onto a smooth colour ramp.
  • ROLES names the eye parts (iris, eye, shine, blush) so they get the mutation's complementary eye colours. keep leaves keys such as teeth unchanged.
  • Override them with MUTATIONS = {...} and pick a subset with MUTATIONS_USE.

Roblox-friendly by construction (don't break these)

• One draw call: one mesh, one material and one shared 512 px tiling stud texture. Colours are vertex colours, which Roblox multiplies by the TextureID.
• Rigid skinning (1.0 weights) and culling of faces hidden by another box on the same bone.
• Size: about 800 triangles for a pet and about 1,600 for a dragon. Keep mobs under about 3k; the hard limit is 20k.
• Mutations are separate meshes on the same rig: every animation works on every variant. The effects come from one emitter and at most one light per model.
• Export: FBX with no leaf bones, FBX unit scale, -Z forward and Y up, the root at the origin, one clip per FBX.

More detail: reference/design_guide.md, reference/roblox_rules.md, reference/roblox_studio.md and reference/pitfalls.md.