Export format

Normative. This page is the profile every Dramatis GLB and VRM export follows, version 1. The writer (writeCharacterGlb), the three.js adapter (characterObject) and the gate-1 harness (test/gate1/) are all built to it. Where it says MUST, a file that does otherwise is a bug in the writer; the harness fails it. The same names are in code, in src/contracts/profile.ts (UE_JOINTS, MIXAMO_NAMES, FACE_UNITS, checkExportExtras), and a test pins them to tosijs-3d.

Where today's writer falls short of it (each is a known bug, tracked on the board, and listed on Export under "Not yet"):

• Materials are only partly baked: the skin is one flat colour, and body and eyelashes carry no TEXCOORD_0. The eyes are textured: Tonio Loewald's eye art (CC0, basic or anime by the character's eyeStyle), its iris recoloured to irisColour, both eyeballs mapped onto one picture with the iris straight ahead.
• The floor. The body is placed so that its whole skin would touch y = 0, but where shoes cover the feet that skin is cut away, so the exported skin's lowest point is higher and the shoe soles go below the floor (by up to 36 mm on the samples).

The file

• A GLB (binary glTF 2.0): one JSON chunk and one binary chunk. Every buffer and image is embedded; there are no external URIs.
• extensionsRequired is empty, so every glTF loader opens the file. KHR_materials_sheen may be in extensionsUsed (cloth); a loader that lacks it draws the cloth without sheen.
• The Khronos glTF validator reports zero errors. Warnings are allowed but are bugs to fix.
• One scene. Its top nodes are the root joint and one node per mesh. No node carries a transform except the joints, and mesh nodes are never parented under a joint (glTF ignores a skinned mesh's parent transforms, and engines disagree about it).

Units, axes, root

• Metres, Y up, right-handed, as glTF defines it.
• The character faces +Z, its left hand on +X.
• Root at the feet. The root joint is at the origin, on the floor directly under the pelvis. Its rotation is UAL's: -90° about X, a relic of Blender's Z-up armature, which its children's rest rotations undo (the profile copies UAL's joint frames, so it copies this too). The soles touch y = 0: the lowest point of the body's skin is at y = 0 within a millimetre.

Nodes and meshes

One mesh per part of the character, each its own node, the node and the mesh sharing a name:

Names are ASCII letters, digits and _. Each mesh has one primitive per material (usually one), mode 4 (triangles), indexed, with POSITION, NORMAL, TEXCOORD_0 (when textured), JOINTS_0 and WEIGHTS_0. The order of the meshes is the order above, garments by asset name.

Skeleton

• One skin, named skeleton, used by every mesh node, with skeleton set to the root joint and inverseBindMatrices given.
• Its joints are exactly the 65 below, in this order, named per the file's naming profile (ue, the default, or mixamo). Parents are as listed; a parent always comes before its children.
• These are UE mannequin names as Quaternius' Universal Animation Library (UAL) spells them: tosijs-3d's HM08_UAL. Note Head (capital H) and the _leaf tips, which carry no skin weight and exist so engines know where a finger or a toe ends.
• Joints carry translation and rotation only (scale 1).
• The Mixamo profile renames joints and nothing else. Mixamo has no joint above the hips, so root keeps its name there, as a non-humanoid parent. three.js strips the : when binding (mixamorigHips), as it does for Mixamo's own files. Whether Unity's Humanoid needs it at all is spike 1's question.

Skinning

• At most four influences per vertex: JOINTS_0 (unsigned byte or short) and WEIGHTS_0 (float), weights renormalised to sum to 1 and unused slots 0.
• Garments, hair, brows and the rest are skinned to the same skeleton as the body, so clothing deforms with it.

Rest pose: the T-pose

The bind pose is a T-pose: arms straight out along ±X, palms down, legs straight and slightly apart, as UAL's mannequin stands. Every joint's rest rotation is UAL's own joint frame (the bone along the joint's local +Y, as Blender exports it); only the translations are the character's.

Why, decided for version 1:

1. UAL clips then play by name, unretargeted. A clip's rotation keys are relative to its skeleton's rest frames. With the same frames, they mean the same thing on our skeleton, so a three.js AnimationMixer or a Godot AnimationPlayer plays UAL's clips on an export as is. This is the gate's test (below).
2. VRM requires a T-pose, and Unity's Humanoid and Unreal's IK Retargeter both prefer one: their auto-mapping assumes it.
3. UAL is a T-pose already (measured from UAL1.glb: the hands at the shoulders' height, 0.74 m out). MakeHuman's own rest holds the arms angled down, so the export re-poses MakeHuman's bind to the T-pose; that is linear-blend skinning of the baked mesh, done once at export.

restPose: 'source' (an option, not the default) keeps MakeHuman's rest instead, with UAL's frames re-aimed along its bones. Clips then need retargeting; it exists for tools that want the sculpted rest.

Playing UAL clips

A UAL clip's translation keys hold the mannequin's bone lengths, so played on another body they stretch it. Play its rotation tracks on every joint and its translation tracks on root and pelvis only (ideally scaling the pelvis's by the ratio of the hips' heights). That is what characterClip in dramatis/three does (its translationScale is the ratio), and the gate's clip check plays the clip through it.

Morph targets: the face units

• The face goes out as morph targets, one per face unit: MakeHuman's face pose units as the hm08 pack bakes them, named exactly as below (no prefix; MakeHuman's own spelling, lowerLipUp and LeftEyeturnRight included).
• Names are in mesh.extras.targetNames, one per target, in the order below. That is the convention three.js, Babylon, Blender, Godot, Unity's glTFast and Unreal's Interchange read.
• Each mesh carries the units that move it: the body most, the lashes, brows, beard, teeth, tongue and eyes theirs. One name on several meshes is one unit: drive them together. mesh.weights are all 0.
• POSITION deltas, metres; NORMAL deltas optional. Sparse accessors are allowed (most units move a few hundred vertices).
• The units in the file are listed in asset.extras.dramatis.faceUnits; the harness checks that they are exactly the ones on the meshes. Exporting without face units (faceUnits: false) lists none and writes no targets.

The 59 units, in order:

LeftBrowDown, RightBrowDown, LeftOuterBrowUp, RightOuterBrowUp, LeftInnerBrowUp, RightInnerBrowUp, NoseWrinkler, LeftUpperLidOpen, RightUpperLidOpen, LeftUpperLidClosed, RightUpperLidClosed, LeftLowerLidUp, RightLowerLidUp, LeftEyeDown, RightEyeDown, LeftEyeUp, RightEyeUp, LeftEyeturnRight, RightEyeturnRight, LeftEyeturnLeft, RightEyeturnLeft, LeftCheekUp, RightCheekUp, CheeksPump, CheeksSuck, NasolabialDeepener, ChinLeft, ChinRight, ChinDown, ChinForward, lowerLipUp, lowerLipDown, lowerLipBackward, lowerLipForward, UpperLipUp, UpperLipBackward, UpperLipForward, UpperLipStretched, JawDrop, JawDropStretched, LipsKiss, MouthMoveLeft, MouthMoveRight, MouthLeftPullUp, MouthRightPullUp, MouthLeftPullSide, MouthRightPullSide, MouthLeftPullDown, MouthRightPullDown, MouthLeftPlatysma, MouthRightPlatysma, TongueOut, TongueUshape, TongueUp, TongueDown, TongueLeft, TongueRight, TonguePointUp, TonguePointDown

Materials

• glTF metallic-roughness PBR, nothing else required. Base colour textures are sRGB, PNG or JPEG, embedded.
• The creator's Babylon shading (skin scatter, hair highlights, cloth) does not travel. What it computes is baked into textures: skin albedo with lips and stubble, eyes drawn into an eye texture, recoloured cloth. Losing scatter is the honest cost; the creator keeps it.
• Fabric MAY add KHR_materials_sheen. Hair cards and lashes use alphaMode: MASK (with alphaCutoff); BLEND only where a mask cannot work. doubleSided where the asset says so.
• A material is named for its mesh (body, garment_<asset>).

Licences in the file

Every asset in the file is listed, with its source and licence, in asset.extras.dramatis. asset.copyright repeats it as one line for tools that show only that: <title>: <licence> per asset, joined with ; . A CC BY asset's credit line (attribution) is copied word for word.

asset.extras.dramatis MUST match this schema (checkExportExtras is the same schema in code):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://dramatis.tosijs.net/schema/export-extras-1.json",
  "type": "object",
  "required": ["format", "version", "generator", "naming", "restPose",
               "faceUnits", "character", "licences"],
  "properties": {
    "format": { "const": "dramatis-export" },
    "version": { "const": 1 },
    "generator": { "type": "string", "minLength": 1,
                   "description": "dramatis@<version>" },
    "naming": { "enum": ["ue", "mixamo"] },
    "restPose": { "enum": ["t-pose", "source"] },
    "faceUnits": { "type": "array", "uniqueItems": true,
                   "items": { "$ref": "#/$defs/faceUnit" } },
    "character": { "type": "string" },
    "licences": {
      "type": "array", "minItems": 1,
      "items": { "$ref": "#/$defs/licence" },
      "contains": { "properties": { "kind": { "const": "base" } } }
    }
  },
  "$defs": {
    "faceUnit": { "type": "string",
                  "description": "one of the 59 face units above" },
    "licence": {
      "type": "object",
      "required": ["asset", "title", "kind", "licence", "licenceUrl",
                   "source", "author"],
      "properties": {
        "asset": { "type": "string", "minLength": 1,
                   "description": "<source>:<kind>/<name>, e.g. makehuman:base/hm08" },
        "title": { "type": "string", "minLength": 1 },
        "kind": { "enum": ["base", "eyes", "eyelashes", "teeth", "tongue",
                           "brows", "beard", "hair", "garment", "texture",
                           "animation", "skin-tone", "other"] },
        "licence": { "type": "string", "minLength": 1,
                     "description": "SPDX id: CC0-1.0, CC-BY-4.0, ..." },
        "licenceUrl": { "type": "string", "minLength": 1 },
        "source": { "type": "string", "minLength": 1 },
        "author": { "type": "string", "minLength": 1 },
        "attribution": { "type": "string", "minLength": 1,
                         "description": "required for any CC BY licence" },
        "modified": { "type": "boolean" }
      }
    }
  }
}

An asset with no entry in the licence manifest is never exported: buildCharacter throws UnlicensedAssetError instead.

What VRM adds

A VRM export (exportCharacterVrm, .vrm) is this profile, always ue naming and the T-pose, plus the VRMC_vrm 1.0 extension (in extensionsUsed):

• humanoid.humanBones maps VRM's bones to the joints: hips pelvis, spine spine_01, chest spine_02, upperChest spine_03, neck neck_01, head Head; per side shoulder clavicle, upperArm upperarm, lowerArm lowerarm, hand hand, upperLeg thigh, lowerLeg calf, foot foot, toes ball; fingers thumbMetacarpal, thumbProximal, thumbDistal on thumb_01..03, and Proximal, Intermediate, Distal on index|middle|ring|pinky_01..03. root and the _leaf joints are not human bones.
• expressions.preset from the face units: blinkLeft LeftUpperLidClosed, blinkRight RightUpperLidClosed, blink both, the visemes aa ih ou ee oh and the moods happy angry sad relaxed surprised as weighted sets of units (spike 3 settles the weights).
• lookAt of type expression, through the eye units (LeftEyeUp, LeftEyeDown, LeftEyeturnLeft, LeftEyeturnRight and the right's) as lookUp, lookDown, lookLeft, lookRight. UAL's skeleton has no eye joints, so look-at is by expression, not by bone.
• meta: name, authors, licenseUrl (https://vrm.dev/licenses/1.0/), and otherLicenseUrl and copyrightInformation carrying the licence entries above (which stay in asset.extras.dramatis too).

How it is checked

bun test test/gate1 runs six checks on every GLB in samples/out/: the validator (zero errors); the skeleton's names, order and parents; the morph targets' names; the licence block; three.js's GLTFLoader loading it under Bun; and UAL's Walk_Loop (Quaternius, CC0) binding by name to the major joints (spine, neck, head, each limb to the hand and foot) and moving them. With nothing in samples/out/, every check reports NOT RUN. Each check is shown able to fail on a hand-made bad file (test/gate1/fixtures.test.ts).

The engine imports are spike 1's (tools/engines/, reports/spike-1.md): Godot 4.5, Babylon.js 9.33 (headless) and Blender 5.2 have passed on every sample; Unity and Unreal 5 have not been run. Each engine's guide says what was checked there.