Rpg Character

RPG character pipeline

One idea ("a dwarf miner") → a rigged voxel humanoid with 33 game-ready clips, weapon slots on both hands and voxel props (sword, axe, pickaxe, staff), exported as glTF. The animations are not authored per character: a CC0 humanoid clip library is retargeted onto a skeleton that is derived from the voxel grid, so the same command works on a chibi dwarf and a lanky elf. Four stages, each with a gate.

Exactly ONE gate is a manual user pick — present the material, then stop and wait:

1. concept selection (stage 1): the user picks one of four generated concept images.

Skip stage 1 entirely when the user already has a mesh (--glb) or a MagicaVoxel model (--vox).

Layout

assets//                      (PascalCase name)
  concept/candidate_{1..4}.png      stage 1 + concept_sheet.png + concept.json (fal CDN urls)
  _mesh.glb                   stage 2: Hunyuan-3D output
  .vox                        stage 3: 5 cm voxels, standing, facing -Y
  previews/_vox_{front,side,top}.png     + _.png frames with --render
  layout.json, _rules.py      stage 4: derived body plan + exact voxel->bone table
  _rigged.blend               stage 4: rig, every clip stashed in the NLA
  _animated.glb               EXPORT: mesh + 19-bone rig + 33 animations + Prop_* meshes on handslotR
  clips.json                        per clip: frames, fps, loop, hit_frame, prop
  report.json, run.log              guards, timings, everything that was run

Tools: tools/pipeline/concept.py --kind humanoid, tools/pipeline/run_character.py, tools/biped/ (bipedrig.py, biped_build.py, retarget_lib.py, maps/, presets/, anims/kaykit/Knight.glb). Requirements: Blender 5.2 LTS (BLENDER=/path if not on PATH), the voxelizer built once with CMake, Python 3.10+ with Pillow, a fal key (FAL_KEY or ~/.fal/key) for stages 1-2 only.

Stage 1 — concept (fal Seedream)

python tools/pipeline/concept.py  --kind humanoid --idea "a stout dwarf miner with a braided beard" \
       --height-m 1.5 --colors "rust beard, brown apron, grey shirt" [--anatomy "..."]

The humanoid template asks for a standing A-pose (arms hanging a little away from the body, legs apart, feet flat), front three-quarter view, chunky cubes, plain background. Auto QA first: reject candidates whose arms touch the torso or each other, whose legs are fused, that hold objects (props come later), or that crop the feet. USER PICK (mandatory): show concept_sheet.png, stop, keep the picked CDN url.

Stages 2-4 — one command

python tools/pipeline/run_character.py  --image-url  --height-m 1.5 --render

• Mesh — Hunyuan-3D v3.1 (face_count 100000, PBR). ~2.5 min, ~$0.68.
• Voxelize — the voxelizer cuts the mesh at 5 cm on the vertical axis (--axis y --long-axis H/0.05)

and sweeps the yaw over 0/180/90/270 until the grid stands on two legs, is wider than deep, and the toes point -Y. Check previews/_vox_side.png: toes must point LEFT. Fix a wrong pick by running the voxelizer by hand with --yaw and passing --vox.

• Body plan — bipedrig.py reads the grid bottom-up: feet (bottom layers that reach forward), legs

(lowest band with two blobs either side of the midline, plus a chibi pelvis block), torso split 1/6 : 1/3 : 1/2 into hips / spine / chest, arms (free-hanging outboard columns, then the merged shoulder layers; T-pose bands also work), head (first layer above the shoulder line narrower than the trunk), hands (bottom 20% of each arm). It writes bone heads/tails and an exact per-voxel bone table.

• Rig + retarget — biped_build.py builds the voxel mesh with rigid weights, a 17-bone rig

(root, hips, spine, chest, head, arm upper/lower/hand x2, leg upper/lower/foot x2), imports the CC0 KayKit rig, adds handslotL/R from the source's own slot offsets, re-rolls every mapped bone into the source's frame convention and copies the source's world rotation per frame (see [references/retargeting.md](references/retargeting.md)). Hips translation is scaled by leg height; feet are clamped to the floor through the hips. Props are voxel meshes from tools/biped/props/*.py (sword, axe, pickaxe, staff; grip at the slot origin, length along the slot's +y, one cell = height/27), bone-parented to handslotR. Chop carries an additive forward bend (preset add) so the axe lands on a log at the ground while Mine swings at a rock face at chest height.

• Chunky sleeves that read as raised arms in Idle (the KayKit idle holds the upper arms ~45° out):

pass --relax-arms 20..30 to pull hanging upper arms toward the body; the pull fades out as an arm is raised, so attacks are untouched. Check previews/Idle_0.png and decide.

QA gate (numeric, never visual): every CLIP line in run.log must end in OK: dir 0.000 deg (the target bone points exactly where the source bone points, an identity check on the maths), no NaNs, hips excursion under 60% of the height, floor fix reported. clips.json gives the loop flag and the hit frame of each attack (peak weapon-slot speed) for gameplay events. With --render, clip_sheet_*.png are for the user to enjoy, not for you to grade a walk by.

The clip set (presets/rpg_kaykit.json)

Idle · Walk · Run · JumpStart · JumpLoop · JumpLand · SwordIdle · Slash · SlashDiag · Stab · Overhead · Chop (axe) · Mine (pickaxe) · Slice2H · Spin · Block · BlockHit · CastRaise · Cast · CastLong · Casting (staff) · Punch · Kick · Interact · PickUp · UseItem · Throw · Hit · Death · Cheer · DodgeBack · SitDown · SitIdle. Add one by adding a line to the preset (any of the 76 source actions listed in anims/kaykit/SOURCE.md). Other sources: --source your.fbx --map maps/mixamo.json for Mixamo downloads (not redistributable — keep them out of repos), maps/ual.json for the Quaternius library.

Stage 5 — use it

_animated.glb imports into Godot / Unity / Unreal / three.js with named animations; the Prop_* nodes are children of handslotR — show the one clips.json names for the playing clip, or attach your own item to the slot. For tiny-voxel's rigid-part runtime, bake with the engine's baker (not in this repo).

Scope

Standing humanoids with two arms and two legs. Arms may hang or be in T-pose. Capes, tails, wings, skirts and held objects in the concept confuse the body plan — keep them out of the concept and add them as props. No facial animation, no fingers (rigid mitten hands carry the slot).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: rehan-remade
• Source: rehan-remade/animated-asset-skill
• License: MIT

Install and usage instructions live in the source repository linked above.