Setup

Everything you need to start building pallets with DigitalHeaven.

Install the CLI

Build from source or grab a release binary. Either way, add it to your PATH so you can run dh from anywhere.

Windows: Add the folder containing dh.exe to your system PATH via Settings → System → Advanced system settings → Environment Variables → Path.

macOS / Linux: Move the dh binary to /usr/local/bin/ or add its directory to your shell profile (~/.bashrc, ~/.zshrc).

Verify it works:

dh help

Initialize Your Workspace

Run the init command to create a fresh workspace:

dh init

Or double-click Initialize DigitalHeaven Workspace.bat if you have the repo cloned.

This creates the following in Documents/DigitalHeaven/:

What	Purpose
`Pallets/`	Your source pallets — this is where you work
`Build/`	Compiled output — generated, don’t edit
`.dh/`	Cache directory (hidden on Windows)
`dh-config.jsonc`	Workspace configuration
`build.bat` / `build.sh`	Shortcut: runs `dh build`
`watch.bat` / `watch.sh`	Shortcut: runs `dh watch`
`validate.bat` / `validate.sh`	Shortcut: runs `dh validate`
`help.bat` / `help.sh`	Shortcut: runs `dh help`
`.gitignore`	Ignores `Build/`, temp files, IDE files
`.gitattributes`	LFS tracking for binary assets (`.glb`, `.fbx`, `.png`, etc.)

If the scripts don’t work, dh.exe probably isn’t in your PATH. See the install step above.

Workspace Layout

Documents/DigitalHeaven/
├── Pallets/                  # Your source pallets
│   ├── io.mltn/
│   │   └── mltn-mayu/
│   │       ├── pallet.dh
│   │       ├── avatar.dh-avatar
│   │       ├── textures/
│   │       │   ├── body-diffuse.png
│   │       │   ├── body-normal.png
│   │       │   └── body-orm.dh-tex
│   │       ├── materials/
│   │       │   ├── skin.dh-mat
│   │       │   └── eyes.dh-mat
│   │       ├── models/
│   │       │   └── body.glb
│   │       └── rigs/
│   │           └── humanoid.dh-rig
│   └── tech.azuki/
│       └── mayu/
│           ├── pallet.dh
│           └── avatar.dh-avatar
├── Build/                    # Compiled output (don't edit)
│   ├── io.mltn.mltn-mayu.pallet
│   └── tech.azuki.mayu.pallet
├── .dh/                      # Cache (hidden on Windows)
│   ├── temp/                 # Temp files (auto-cleaned after 1 day)
│   ├── fbx-cache/            # FBX→GLB conversion cache
│   └── fbx_to_glb.py        # Blender conversion script
└── dh-config.jsonc            # Configuration

Pallets are organized by reverse-DNS ID: io.mltn.mltn-mayu lives at Pallets/io.mltn/mltn-mayu/. See Pallets & Assets for details.

Blender (FBX → GLB)

If your pallets contain .fbx models, the compiler converts them to .glb using Blender in headless mode.

The compiler auto-detects Blender from your PATH and common install locations
If it can’t find Blender, it’ll prompt you to set the path (saved to dh-config.jsonc)
You can also set blenderPath in dh-config.jsonc manually

The Conversion Script

The compiler copies fbx_to_glb.py into your .dh/ cache directory. This script:

Imports FBX files into Blender
Exports as GLB with animations, morphs, skins, and materials
Ignores leaf bones by default

This script is yours to customize. The compiler won’t overwrite it once it exists. If you need custom import/export settings, edit .dh/fbx_to_glb.py directly.

Unity Integration

DigitalHeaven ships as pre-compiled DLLs. Three scripts manage getting them into your Unity project (found in the Unity project folder):

Script	What it does
`link-plugins.bat`	Creates symlinks from published DLLs to `Assets/Plugins/DigitalHeaven/`. Changes propagate instantly. Requires Windows 10+ Developer Mode or Admin.
`copy-plugins.bat`	Copies DLLs instead. Use this if symlinks aren’t available. Re-run after rebuilding the library.
`unlink-plugins.bat`	Removes symlinks and cleans up the Plugins folder.

These scripts are Windows .bat files. On macOS/Linux, adapt the commands in each script to shell equivalents.

File Extensions

Definition files use custom .dh-* extensions. Each type has its own:

Asset Type	Extension	Type ID
Pallet manifest	`pallet.dh`	—
Avatar	`.dh-avatar`	`dh.avatar`
Object	`.dh-obj`	`dh.object`
Material	`.dh-mat`	`dh.material`
Texture	`.dh-tex`	`dh.texture`
Rig	`.dh-rig`	`dh.rig`

See the Definition Types pages for what goes in each file.

File Format

All definition files are JSONC — JSON with two extras:

Comments: // line and /* block */
Trailing commas: allowed in arrays and objects

{
  // This is fine
  "name": "My Avatar",
  "tags": [
    "custom",
    "v2",  // trailing comma OK
  ],
}

Parsed with System.Text.Json — relaxed on formatting, strict on validation. The compiler catches errors at build time with file paths, line numbers, and helpful messages.