Convert a Meshy/Mixamo-style biped GLB into a helix-humanoid@1 character: conform onto the canonical skeleton, generate LODs, encode KTX2
helix character import [options] <body>
Argument
Required
Description
body
yes
source biped character GLB (skinned body)
Option
Description
--map <json>
bone map JSON file (default: the bundled Meshy->helix map)
--canonical <glb>
canonical helix body GLB (default: the world's installed humanoid-character pack when present, else the embedded helix-humanoid@1 skeleton)
--anim <glb>
also retarget this animation GLB (same source rig) -> <out>/anims/<clipName>.glb
--clip-name <name>
clip name for --anim (default "locomotion.warriorWalk")
-o, --output <dir>
output directory (default "./character-out")
--name <base>
output basename -> <base>.web.glb (default: derived from the input file name)
--provenance <json>
source/license JSON; emits a pinned <name>.avatar-import.json receipt
--face-map <json>
explicit helix/avatar-face@1 semantic mapping (default: conservative known-name detection; avatars with no face channels remain valid)
--fit <mode>
rest fit: 'source' preserves the model; 'canonical' aligns joints/proportions to the pinned HELIX rest (garment fit still requires visual proof) (default "source")
--lod-tris <a,b,c>
triangle target per LOD level, high->low (default "10000,5000,1500")
--tex-size <n>
texture longest-edge cap; the rebake route halves it per LOD level (default "1024")
--ktx-mode <m[,m2..]>
KTX2 codec per LOD level, etc1s or uastc; shorter lists repeat the last entry (default uastc,etc1s — UASTC up close, ETC1S far)
--ktx-quality <n>
etc1s qlevel 1..255 / uastc level 0..4
--no-ktx2
keep the source png/jpeg textures instead of encoding KTX2 (for pipelines that scan or re-encode textures downstream)
--simplify-error <e>
meshopt error budget (imports resist collapse; raise if LODs miss target) (default "0.02")
--lock-border
preserve UV-seam/material-boundary verts during decimation (OFF by default for imports)
--bake
force the weld+unwrap+rebake LOD path (default: AUTO on micro-chart atlases)
--no-bake
disable the weld+unwrap+rebake LOD path
--no-weld
also disable the (non-bake) seam-weld fallback for floored far LODs
--no-split-face
keep each LOD as one mesh (default: head geometry is sliced into a 'FaceMesh' node so first-person mode can hide it)
--no-face-detail
rebake route: decimate and unwrap area-blind (default: the face keeps 20% of each LOD's triangles and ~2.25x texel density)
--limb-bridges <mode>
arm<->leg bridge geometry (a hand fused to the thigh): repair cuts it and re-weights each side, report only measures and logs what repair would change, off skips it (default "repair")
--rest-pose <mode>
joints far off the standard skeleton (foot, ball, calf, clavicle) moved onto it, spine/leg rests made canonical, and the skeleton lifted so the soles clear the floor: repair, report (measure only) or off (default "repair")
--arm-bind <mode>
re-bind arms bound below the platform A-pose (and lift a hanging head) so clips move them like Base Female: repair, report or off (default "repair")
--sleeve-allowance <deg>
extra outward arm angle over the A-pose, or 'auto' (from the measured sleeve thickness) (default "auto")
--head-pitch <deg>
head lift (positive = chin up), or 'auto' (from the measured face profile); 0 = off (default "auto")
--static-weights <mode>
hair and loose cloth skinned static to the body (no arm/clavicle weight in back hair): repair, report or off (default "repair")
Pose-aware poke-through fit for a packaged character add-on GLB: push garment geometry clear of the posed base body across the canonical pose set, gated so the result is kept only if the poke-through check is strictly better
helix character fit [options] <garment>
Argument
Required
Description
garment
yes
packaged add-on GLB (every LOD level is fitted)
Option
Description
--body <glb>
the base body GLB the add-on is worn on (Base Male / Base Female) (required)
-o, --output <glb>
output GLB: the fitted mesh when improved, otherwise a byte-identical copy of the input (required)
--slot-type <slotType>
scope the fit and its gate to this slot type's granted hide regions (e.g. character.top@1)
--hidden-regions <globs>
explicit region scope, comma-separated (e.g. body_torso,body_upperarm_l), or 'none' for unscoped; overrides --slot-type
--clearance-mm <mm>
target clearance: body ends at least this far behind the garment surface (default 3)
--threshold-mm <mm>
gate violation floor, as pokethrough-check --threshold (default 0.5)
--ceiling-mm <mm>
deeper than this is not a coverage defect, as pokethrough-check --ceiling (default 10)
--proximity-mm <mm>
body points farther than this from the garment are not under it, as pokethrough-check --proximity (default 50)
--max-push-mm <mm>
largest total move for an interior garment vertex (default 8)
--hem-max-push-mm <mm>
largest total move on a hem/cuff/collar boundary (default 4)
--hem-band-mm <mm>
surface distance over which the hem cap ramps back to --max-push-mm (default 20)
--smooth-radius-mm <mm>
falloff radius of the smoothing membrane (default 20)
Check (and by default fix) whether the base body's ears poke through a head-zone add-on (headwear, mask, hair, eyewear): measures the clearance between the ear surface and the OUTERMOST garment layer around it, per LOD, and pushes the garment smoothly clear when a wrapped ear has < 1.5 mm. Kept only when no ear pokes afterwards
helix character ear-clearance [options] <garment>
Argument
Required
Description
garment
yes
packaged add-on GLB (every LOD level is measured)
Option
Description
--body <glb>
the base body GLB the add-on is worn on (Base Male / Base Female) (required)
-o, --output <glb>
output GLB: the fixed mesh when improved, otherwise a byte-identical copy of the input (omit with --check)
--check
measure only — write nothing; exit 3 when an ear pokes through
--target-mm <mm>
clearance the fix aims for (default 4)
--trigger-mm <mm>
a wrapped ear sample with less clearance than this is a poke-through (default 1.5)
--max-push-mm <mm>
largest total move for any garment vertex (default 18)
Measure which body regions a packaged character add-on GLB fully occludes and print the hide ops that follow (a granted region is hidden only when >= 98% of its vertices have garment in front of them within 60 mm along the normal, bind pose). Include the ops in a new sealed Package Version
helix character derive-hide [options] <garment>
Argument
Required
Description
garment
yes
packaged add-on GLB (every LOD level is measured; the least-covered LOD decides)
Option
Description
--body <glb>
the base body GLB the add-on is worn on, in bind pose, with the baked _REGION attribute (Base Male / Base Female) (required)
--slot-type <slotType>
the add-on's slot type, e.g. character.bottom@1 — bounds the result to that slot's platform hide grant (required)
--threshold <percent>
occluded share a region needs before it is hidden (default 98)
--standoff-mm <mm>
how far in front of the skin a garment surface may be and still occlude it (default 60)
--ops-out <file>
also write the ops array JSON here for a new sealed Package Version
--json
print the full result (coverage per region, hidden/visible sets, ops) as JSON
Fix an imported character's rig in place of hand scripts (the importer's own stages, in its order): a hand fused to the thigh cut free (judged under the arm re-bind), arm weight on geometry that is not the arm (a coat skirt weighted to the hands) moved to the body it hangs from, the arms re-bound onto the platform A-pose (+ an allowance for thick sleeves) and a hanging head lifted, a shoe skinned to the other foot's bones given back to its own foot, then hair and cloth on the back skinned STATIC to the spine/neck/head — identically on every LOD
helix character fix-rig [options] <glb>
Argument
Required
Description
glb
yes
imported HELIX character GLB (helix-humanoid@1 skeleton)
Option
Description
-o, --output <glb>
output GLB (required)
--rest-pose <mode>
joints far off the standard skeleton (foot, ball, calf, clavicle) moved onto it, spine/leg rests made canonical, and the skeleton lifted so the soles clear the floor: repair, report (measure only) or off (default "repair")
--arm-bind <mode>
arm/head bind normalisation: repair, report (measure only) or off (default "repair")
--sleeve-allowance <deg>
extra outward arm angle over the A-pose, or 'auto' (from the measured sleeve thickness) (default "auto")
--head-pitch <deg>
head correction (positive = chin up), or 'auto' (from the measured face pitch vs Base Female); 0 = off (default "auto")
--no-fused-band
do not feather arm weight across a sleeve fused to the torso before the re-bind
--static-weights <mode>
arm reach (non-arm geometry off the arms) and hair/back-cloth weight cleanup: repair, report or off (default "repair")
--limb-bridges <mode>
arm<->leg (hand fused to the thigh) bridge repair before the re-bind, judged under it: repair, report or off (default "repair")
Repair a packaged multi-LOD add-on whose LOD scenes share one skeleton (helix-creator-cli #219's output, which three.js loads with undefined bones): give every LOD scene its own copy, changing only the node/skin graph
helix character repair-lod-skeletons [options] <glb>
Argument
Required
Description
glb
yes
packaged add-on GLB
Option
Description
-o, --output <glb>
output GLB: the repaired file, or a byte-identical copy when nothing is shared (required)
Check an avatar GLB BEFORE it is published: walk it, run it and stand it still on the production Marketplace viewer (the candidate is swapped in locally, nothing is uploaded), judge it with the hosted gate's own avatar@3 math plus offline stage-1 and run/idle asserts, and write a tool-owned fixed inspection set (sheets beside Base Female). Free, local, headless.
helix character check [options] <glb>
Argument
Required
Description
glb
yes
the avatar GLB (a conformed helix-humanoid@1 character, e.g. the output of helix character import)
Re-frame a packaged add-on's skeleton onto its host's: re-create the host's root_offset wrapper (Base Female: 0,-0.0331,-0.0049 m) above the part's skeleton and rewrite its inverse-bind matrices, so the engine (host bones x PART inverse binds) draws the part where its mesh was authored instead of 33 mm low. Only the node graph and the IBMs change
helix character reframe-skeleton [options] <glb>
Argument
Required
Description
glb
yes
packaged add-on GLB (LOD scenes with their own skeletons; run repair-lod-skeletons first if they share one)
Option
Description
--host <glb>
the host body GLB the add-on rides (Base Female) (required)
-o, --output <glb>
output GLB: the re-framed file, or a byte-identical copy when nothing to do (required)