CLI & Config

The dh command-line tool compiles, validates, and watches your pallets.

Commands

Command	Description
dh build	Compile all pallets (default if no command given)
dh watch	Watch for changes and auto-compile
dh validate	Validate pallets without writing output
dh clean	Clear the .dh/ cache directory
dh init	Initialize a new workspace
dh help	Show available commands

Flags

Flag	Short	Works with	Description
--verbose	-v	build, watch, validate, clean	Show detailed output (Blender logs, file-level progress)
--clean	-c	build, watch	Clear cache before building

Example:

dh build --verbose --clean

Watch Mode

dh watch monitors your Pallets/ directory and recompiles when files change.

Debounce: waits for changes to settle before compiling (default: 1000ms, configurable via watchDebounceMs).

Manual controls:

Key	Action
Space, Enter, R, C	Trigger manual compile
Q, Ctrl+C	Exit watch mode

Build Output

Success

Building io.mltn.mltn-mayu...
  ✓ Parsing definitions
  ✓ Validating references
  ✓ Processing textures
  ✓ Converting models
  ✓ Bundling assets
  ✓ Writing output

Build succeeded in 1.2s

Failure

Building io.mltn.mltn-mayu...
  ✓ Parsing definitions
  ✗ Validating references

Error in io.mltn.mltn-mayu/avatar.dh-avatar:12:5
  Missing required property 'name' in material definition

    10 |   "materials": {
    11 |     "body": {
  > 12 |       "diffuseTexture": "textures/body.png"
       |       ^
    13 |     }
    14 |   }

Build failed with 1 error

Config: dh-config.jsonc

Lives in your workspace root. All properties are optional — omit them to use defaults.

Property	Type	Default	Description
workspaceRoot	string?	Documents/DigitalHeaven	Workspace root directory
palletsDirectory	string?	{workspaceRoot}/Pallets	Source pallets location
buildDirectory	string?	{workspaceRoot}/Build	Compiled output location
cacheDirectory	string?	{workspaceRoot}/.dh	Cache directory
watchDebounceMs	int?	1000	Milliseconds to wait before auto-compiling
additionalPalletPaths	string[]	[]	Extra paths to search for pallets (cross-pallet refs)
blenderPath	string?	auto-detect	Path to Blender executable

Example:

dh-config.jsonc

{
  "watchDebounceMs": 500,
  "additionalPalletPaths": [
    "D:/SharedPallets"
  ],
  "blenderPath": "C:/Program Files/Blender Foundation/Blender 4.0/blender.exe"
}

Build Pipeline

What dh build does under the hood:

1. Parse — Read all JSONC/.dh-* definition files
2. Validate — Check schemas, references, types, inheritance chains
3. Process textures — Channel packing, extraction, and resize from dh.texture definitions and @channel references
4. Convert models — FBX → GLB via Blender (cached by content hash)
5. Bundle — LZ4-compress assets into the output pallet
6. Output — Write compiled .pallet file to Build/