VRM

A character also leaves Dramatis as a VRM 1.0 file (.vrm), the avatar format VTuber apps, VRChat-style worlds and VRM viewers read. A Dramatis VRM is the GLB export with one more extension, VRMC_vrm, in its JSON: the geometry, the skeleton, the face as morph targets, the materials and the licences are byte for byte the GLB's. VRM only names what is already there: which joint is which human bone, which face units make which expression, where the eyes are, and the licence terms in VRM's own words. The profile is normative: Export format, "What VRM adds".

import { loadHumanPack } from 'tosijs-3d/human-pack'
import { exportCharacterVrm, HM08_PACK_URL } from 'dramatis'

const pack = await loadHumanPack(HM08_PACK_URL)
const vrm = await exportCharacterVrm(character, pack, {
  meta: { name: 'Ada', authors: ['Ada L.'] },
})
// vrm is a Uint8Array: save it as ada.vrm

Checked with @pixiv/three-vrm under three.js and with a structural check of its own (below). Not yet tried in UniVRM, a VTuber app or any VRM viewer. The creator has no VRM button yet: make one with the API.

Also exported: writeCharacterVrm(built) (a built character to VRM, synchronously), vrmFromGlb(glb) (any Dramatis GLB under ue naming in the T-pose, to VRM), vrmProblems(bytes) (the structural check below), and the two tables, VRM_HUMAN_BONES and VRM_PRESETS.

What is in it

• Always ue naming and the T-pose rest. VRM 1.0 wants a T-pose, and the profile's bind pose is one. A Mixamo-named GLB, or one built with restPose: 'source', is refused with a reason.
• Faces +Z, as VRM 1.0 (and the profile) say. three-vrm and UniVRM need no turn.
• No MToon, no spring bones. Materials stay plain glTF PBR, which VRM 1.0 allows; hair does not swing. Both can be added later without changing anything here.

Humanoid

UAL's skeleton is a UE mannequin, close to VRM's humanoid already: one joint per VRM bone, 52 in all.

root (the floor joint) and the _leaf tips are not human bones. VRM's leftEye, rightEye and jaw are not mapped: UAL has no eye or jaw joints, so the eyes and jaw move by face units.

Expressions

Each preset is a weighted set of the 59 face units, bound on every mesh that carries the unit (one unit on the body, the lashes, the brows and the teeth is one unit: they move together). A unit the export lacks is left out; a preset with no units left is left out.

"Left" in a unit's name is the character's left (+X), measured, not assumed: every Left unit moves vertices at x > 0, and LeftEyeturnLeft turns the eye's front towards +X. VRM's blinkLeft and lookLeft are the avatar's own left too (three-vrm sends a target on the avatar's +X to lookLeft), so no side is swapped.

The weights are a first cut, judged from what each unit moves; they have not yet been looked at in a VTuber app (see the spike report, reports/spike-3-vrm.md). They live in src/vrm/expressions.ts as data.

neutral is left out: the rest face is neutral. The remaining units (the tongue's, CheeksPump, ChinLeft and the rest) are still morph targets in the file, by name, for apps that drive units directly.

Look-at

By expression, not by bone: UAL has no eye joints, so the eyes turn by the eye units through lookUp, lookDown, lookLeft and lookRight.

• The origin (offsetFromHeadBone) is the point between the eyeballs' centres, measured from the eyes mesh and given in the Head joint's local frame, which is how three-vrm applies it. The head joint is within 2° of the model's axes, so a reader that takes the offset in model axes is off by a few millimetres at most.
• The ranges map the angle each look preset turns the eyes at weight 1 (measured per character: about 18° to 28° on the samples) to weight 1. A target at that angle gets the full unit; one further out is clamped.
• An export without all four eye units gets no look-at, rather than a lopsided one.

Meta and licences

The full entries stay in asset.extras.dramatis.licences too, as in every export.

The use terms are the widest the character's assets allow: anyone may perform as it (avatarPermission: everyone), commercially (commercialUsage: corporation), and redistribute and modify it (allowModificationRedistribution), unless an asset is non-commercial (NC, then personalNonProfit) or no-derivatives (ND, then prohibited). Credit is required when any asset is CC BY (the Monk Skin Tone Scale is, so in practice always), unnecessary otherwise. The content flags (excessively violent or sexual, political or religious, antisocial or hateful use) are left at VRM's default, false: those are the author's to grant, not the assets'. Change them in a VRM editor if you mean to.

How it is checked

Every VRM in the tests (src/vrm/vrm.test.ts, on the committed samples and a fixture) is checked four ways:

1. vrmProblems, the structural check of VRMC_vrm against the 1.0 schema and against the file: required bones present, no node used twice, each bone's nearest human ancestor is the one VRM's hierarchy wants, every morph bind on a mesh node and a real target with a weight in [0, 1], meta's required fields and enums, look-at ranges. Each failure is shown to fire on a broken file.
2. The Khronos glTF validator: zero errors. It reports VRMC_vrm as an extension it cannot validate (an info), which is why (1) exists.
3. The gate-1 profile checks (skeleton, morph targets, licences): a VRM is still a profile GLB.
4. @pixiv/three-vrm under three.js: it loads with every bone and preset; aa sets JawDrop to 0.8 on the body and the teeth; blinkLeft closes only the left lid; looking at a point on the character's left drives lookLeft and LeftEyeturnLeft; the normalized rig is a T-pose facing +Z, and lowering its left upper arm lowers the raw hand_l.

Not yet checked: UniVRM (Unity), VSeeFace, VRoid Hub or any VTuber app. A sample to try by hand is reports/spike-3-vrm/long-hair.vrm.