dh.rig

Extension: .dh-rig
Type ID: dh.rig

A rig definition maps DigitalHeaven standard bone names to model-specific bone names. This lets the system understand your armature regardless of what naming convention the original model uses (Mixamo, Blender, custom, etc.).

Properties

Property	Type	Required	Description
$type	"dh.rig"	no	Type identifier
name	string	no	Display name
description	string	no	Description
inherits	string	no	Barcode of the rig to inherit from
bones	object	yes	Maps standard bone names → model bone names
customBones	object	no	Maps custom (non-standard) bone names → model bone names
eyeRotationLimits	object	no	Eye rotation limits as local Euler angles (see Eye Look-At)
viewPosition	[x, y, z]	no	First-person camera offset in local space (see View Position)
visemes	object	no	Maps standard viseme keys to blendshape names (see Visemes)
eyelids	object	no	Eyelid blendshape names for blink tracking (see Eyelids)

The type is inferred from the file extension, so $type is not needed in source files. The compiler adds it automatically during builds.

Example

Mapping a Mixamo-rigged model:

humanoid.dh-rig

{
  "name": "Mayu Humanoid Rig",
  "bones": {
    "Hips": "mixamorig:Hips",
    "Spine": "mixamorig:Spine",
    "Chest": "mixamorig:Spine1",
    "UpperChest": "mixamorig:Spine2",
    "Neck": "mixamorig:Neck",
    "Head": "mixamorig:Head",
    "LeftEye": "mixamorig:LeftEye",
    "RightEye": "mixamorig:RightEye",
    "LeftShoulder": "mixamorig:LeftShoulder",
    "LeftUpperArm": "mixamorig:LeftArm",
    "LeftLowerArm": "mixamorig:LeftForeArm",
    "LeftHand": "mixamorig:LeftHand",
    "RightShoulder": "mixamorig:RightShoulder",
    "RightUpperArm": "mixamorig:RightArm",
    "RightLowerArm": "mixamorig:RightForeArm",
    "RightHand": "mixamorig:RightHand",
    "LeftUpperLeg": "mixamorig:LeftUpLeg",
    "LeftLowerLeg": "mixamorig:LeftLeg",
    "LeftFoot": "mixamorig:LeftFoot",
    "LeftToes": "mixamorig:LeftToeBase",
    "RightUpperLeg": "mixamorig:RightUpLeg",
    "RightLowerLeg": "mixamorig:RightLeg",
    "RightFoot": "mixamorig:RightFoot",
    "RightToes": "mixamorig:RightToeBase"
  },
  "customBones": {
    "Tail1": "mixamorig:Tail.001",
    "Tail2": "mixamorig:Tail.002",
    "EarL": "mixamorig:EarL",
    "EarR": "mixamorig:EarR"
  }
}

You only need to map bones that exist in your model. Missing optional bones are simply skipped.

Standard Bones

DigitalHeaven defines 56 standard bones organized into groups. 17 are required for a valid humanoid rig; the rest are optional.

Core

Bone	Required
Root
Hips	yes
Spine	yes
Chest	yes
UpperChest
Neck	yes
Head	yes

Face

Bone	Required
LeftEye
RightEye
Jaw

Left Arm

Bone	Required
LeftShoulder
LeftUpperArm	yes
LeftLowerArm	yes
LeftHand	yes

Right Arm

Bone	Required
RightShoulder
RightUpperArm	yes
RightLowerArm	yes
RightHand	yes

Left Hand

Bone	Required
LeftThumbMetacarpal
LeftThumbProximal
LeftThumbDistal
LeftIndexProximal
LeftIndexIntermediate
LeftIndexDistal
LeftMiddleProximal
LeftMiddleIntermediate
LeftMiddleDistal
LeftRingProximal
LeftRingIntermediate
LeftRingDistal
LeftLittleProximal
LeftLittleIntermediate
LeftLittleDistal

Right Hand

Bone	Required
RightThumbMetacarpal
RightThumbProximal
RightThumbDistal
RightIndexProximal
RightIndexIntermediate
RightIndexDistal
RightMiddleProximal
RightMiddleIntermediate
RightMiddleDistal
RightRingProximal
RightRingIntermediate
RightRingDistal
RightLittleProximal
RightLittleIntermediate
RightLittleDistal

Left Leg

Bone	Required
LeftUpperLeg	yes
LeftLowerLeg	yes
LeftFoot	yes
LeftToes

Right Leg

Bone	Required
RightUpperLeg	yes
RightLowerLeg	yes
RightFoot	yes
RightToes

Summary

17 required bones: Hips, Spine, Chest, Neck, Head, LeftUpperArm, LeftLowerArm, LeftHand, RightUpperArm, RightLowerArm, RightHand, LeftUpperLeg, LeftLowerLeg, LeftFoot, RightUpperLeg, RightLowerLeg, RightFoot

39 optional bones: Root, UpperChest, face bones, shoulders, fingers, toes, and everything else.

Custom Bones

The customBones property handles bones that aren’t part of the humanoid standard: tails, ears, wings, extra joints, whatever your model needs.

{
  "customBones": {
    "Tail1": "Armature_Tail.001",
    "Tail2": "Armature_Tail.002",
    "WingL": "Armature_Wing.L",
    "WingR": "Armature_Wing.R"
  }
}

Custom bone names are freeform; use whatever makes sense for your model. They’re used for armature linking and platform-specific features.

Setting a Null Mapping

Set a bone to null to explicitly mark it as unmapped (useful when inheriting from a rig and you need to remove a mapping):

humanoid.dh-rig

{
  "inherits": "base:rigs/humanoid.dh-rig",
  "bones": {
    "Jaw": null
  }
}

Eye Look-At

If your model has LeftEye and/or RightEye bones mapped, you can define rotation limits that control how far the eyes can rotate when tracking a target. This is used by supported game mods to make your avatar’s eyes follow nearby players or points of interest.

Each direction specifies the eye bone’s local Euler rotation [X, Y, Z] when looking fully in that direction:

Property	Description
up	Local rotation when looking fully upward
down	Local rotation when looking fully downward
left	Local rotation when looking fully left
right	Local rotation when looking fully right

humanoid.dh-rig

{
  "bones": {
    "LeftEye": "mixamorig:LeftEye",
    "RightEye": "mixamorig:RightEye"
  },
  "eyeRotationLimits": {
    "up": [12, 0, 0],
    "down": [-12, 0, 0],
    "left": [0, -12, 0],
    "right": [0, 12, 0]
  }
}

For most models, eye bones rotate around the X axis for pitch (up/down) and the Y axis for yaw (left/right). A value of 12° in each direction is a good starting point. Adjust per-axis if your model’s bone orientation differs.

If eyeRotationLimits is omitted, no eye tracking is applied even if eye bones are mapped.

Runtime API (Eye Look-At)

Game mods can drive eye rotation through two APIs on DigitalHeavenEyeLook:

Property	Type	Description
LookTarget	Vector3?	World-space position to look at. The system computes pitch/yaw from geometry.
NormalizedLook	Vector2?	Normalized look direction: X = yaw (-1 left, +1 right), Y = pitch (-1 down, +1 up).

Both are set-per-frame: the system clears them after each LateUpdate, so eyes smoothly return to rest if the mod stops driving them. If both are set in the same frame, NormalizedLook takes priority.

LookTarget is the natural choice when a game already provides a world-space look-at position (e.g. ScheduleOne’s NPC gaze system). NormalizedLook is useful for face tracking integrations where you have raw pitch/yaw data rather than a world-space target.

View Position

The viewPosition property defines the first-person camera offset in the avatar’s local space as an [x, y, z] float array. Platforms use this to position the player’s viewpoint (e.g. VRChat’s ViewPosition on the avatar descriptor).

humanoid.dh-rig

{
  "viewPosition": [0, 1.32, 0.07]
}

If omitted, the platform uses its own default viewpoint.

Visemes

The visemes property maps 15 standard Oculus viseme keys to blendshape names on the avatar’s target mesh. These are used by platforms that support lip sync (e.g. VRChat).

Key	Phoneme
sil	Silence
PP	P, B, M
FF	F, V
TH	Th
DD	D, T, N
kk	K, G, NG
CH	Ch, J, Sh
SS	S, Z
nn	N (nasal)
RR	R
aa	A
E	E
ih	I
oh	O
ou	U

Each key maps to the name of a blendshape on the mesh specified by the mesh property on dh.set-rig. Missing keys are skipped.

humanoid.dh-rig

{
  "visemes": {
    "sil": "vrc.v_sil",
    "PP": "vrc.v_PP",
    "FF": "vrc.v_FF",
    "TH": "vrc.v_TH",
    "DD": "vrc.v_DD",
    "kk": "vrc.v_kk",
    "CH": "vrc.v_CH",
    "SS": "vrc.v_SS",
    "nn": "vrc.v_nn",
    "RR": "vrc.v_RR",
    "aa": "vrc.v_aa",
    "E": "vrc.v_E",
    "ih": "vrc.v_ih",
    "oh": "vrc.v_oh",
    "ou": "vrc.v_ou"
  }
}

Eyelids

The eyelids property maps eyelid states to blendshape names on the target mesh. Used by platforms that support eyelid tracking or blink animation.

Property	Type	Description
blink	string?	Blendshape for closed eyes
lookUp	string?	Blendshape for eyelids when looking up
lookDown	string?	Blendshape for eyelids when looking down

All three are optional — omit a key to skip that eyelid state.

humanoid.dh-rig

{
  "eyelids": {
    "lookUp": "Eye Look Up",
    "lookDown": "Eye Look Down"
  }
}

Unity Integration

DigitalHeaven bone names are automatically mapped to Unity’s HumanBone names at runtime. You don’t need to think about Unity naming. Just use the standard names above and the runtime handles the translation.

The runtime component (DigitalHeavenRig) can:

• Create a Unity Avatar from the bone mappings
• Set up an Animator with the generated avatar
• Build a HumanDescription for humanoid configuration

All 56 standard bones (except Root) have direct Unity equivalents.