<div align="center">

ᚺᚨᛗᚱ Hamr

The Shape-Skin Engine

Open-source parametric 3D anime character forge

Linux-native · Headless-first · Agent-orchestrated · VRM 1.0

]() ]() ]() ]()

</div>

Hamr (Old Norse: hamr — the shape-skin, the second body) is the open-source alternative to VRoid Studio. It creates parametric 3D anime characters headlessly, driven by YAML specs and agent commands, and exports VRM 1.0 avatars ready for VRChat, Resonite, and any VRM-compatible platform.

No GUI. No Windows dependency. No closed-source lock-in.

Every vertex, every slider, every algorithm is yours.

✨ Key Features

• 🎨 MToon Anime Shaders — Two-tone cel-shading, rim lighting, outline rendering, emission — full VRM MToon spec in pure Python
• 🌿 Spring Bone Physics — Hair sway, skirt drape, accessory bob — physics presets, parameter blending, and energy estimation
• 🤸 Pose Library — Pre-defined T-pose, A-pose, hand poses, and facial presets with blending and VRM export
• 📦 VRM 1.0 Export — Spring bones, expressions, look-at, first-person annotations — full VRM 1.0 compliance out of the box
• 🔧 YAML-First Spec — Define characters in simple YAML files, not GUI clicks
• 🖥️ Headless Blender — Runs entirely in blender --background, no GUI required
• 🍓 Pi 5 Ready — GPU-adaptive quality profiles for Raspberry Pi 5, desktop, and cloud
• ♿ Accessibility-First — --no-color, --json, --quiet on every command
• ✅ 2,233 Tests (2,206 pass, 27 skip, 0 fail) — Every forge tested, every path validated

🗡️ Quick Start

# Install
pip install hamr

# Build a character from a preset
hamr build --preset anime_girl_default

# Build from a spec file
hamr build my_character.yaml --out output/

# Validate a spec without building
hamr validate my_character.yaml

# Inspect a VRM file
hamr inspect output/avatar.vrm

# Verify a VRM rig
hamr verify-rig output/avatar.vrm

# Check your build environment
hamr check-env

# List available presets
hamr list-presets

# Print version
hamr version

# Generate documentation
hamr docs generate

# Run accessibility audit
hamr docs audit

See CLI Reference below for all 9 commands and flags.

📝 Character Spec

The simplest character spec:

name: Quick Avatar
version: "1.0"

body:
  height_cm: 165
  build: average
  skin:
    base_hex: "#E8B87A"

hair:
  style: wavy
  color:
    roots: "#4A2E14"

export:
  format: vrm1
  title: Quick Avatar
  author: Hamr Forge

Full spec with every option:

name: Runa Gridweaver
version: "1.0"

body:
  height_cm: 172
  build: athletic-slender
  skin:
    base_hex: "#E8B87A"
    undertone: warm
    sss: true
  proportions:
    shoulder_width: 0.40
    bust: 0.45
    waist: 0.32
    hip_width: 0.52
    leg_length: 0.52

hair:
  style: wavy
  length: very-long
  volume: 0.7
  color:
    roots: "#C4A265"
    mid: "#D4B47A"
    tips: "#E8D0A0"
    highlight: "#F0E0B8"

face:
  eyes:
    iris_hex: "#4169E1"
    pupil_hex: "#1A1A2E"
    sclera_hex: "#F8F8F0"
    shape: round
    size: 1.1
  eyebrows:
    color_hex: "#B8944A"
    thickness: 0.07
    shape: arched
  nose:
    bridge_width: 0.35
    tip_width: 0.30
    bridge_height: 0.50
    definition: 0.55
    nostril_width: 0.30
  mouth:
    lip_hex: "#C47070"
    width: 0.38
    fullness: 0.55
    upper_curve: 0.40
    lower_fullness: 0.50
    smile_width: 0.60
  cheeks:
    blush_hex: "#E0A0A0"
    bone_width: 0.60
    fat: 0.30
  ears:
    size: 0.40
    protrusion: 0.20
    elf_factor: 0.0
  chin:
    width: 0.30
    protrusion: 0.40
    jaw_width: 0.40

export:
  format: vrm1
  title: Runa Gridweaver
  author: Volmarr & Runa
  version: "1.0"
  license: CC-BY-4.0

🏗️ Architecture

Hamr is organized as seven forges around a central spec:

┌─────────────┐
│  YAML Spec  │ ← Your character definition
└──────┬──────┘
       │
┌──────▼──────┐
│   Builder   │ ← Validates, orchestrates, wires
└──────┬──────┘
       │
  ┌────┼────┬────────┬─────────┬───────┐
  │    │    │        │         │       │
┌▼─┐ ┌▼─┐ ┌▼──┐ ┌───▼───┐ ┌──▼──┐ ┌▼────┐
│Bd│ │Tx│ │Rig│ │Texture│ │MToo│ │Expt│
│Fo│ │Fo│ │Fo │ │ Forge │ │ Fo  │ │Forge│
│rg│ │rg│ │rge│ │       │ │ rge │ │     │
└──┘ └──┘ └───┘ └───────┘ └─────┘ └─────┘
       │
  ┌────▼────┐
  │ Blender  │ ← Headless subprocess
  │  Bridge  │
  └────┬─────┘
       │
  ┌────▼────┐
  │ VRM 1.0 │ ← Your avatar file
  └─────────┘

📖 CLI Reference

Hamr's CLI provides 9 commands:

All commands support --no-color, --quiet, and --json flags for accessibility. build also supports --preset, --spec, --skip-stages, --dry-run, and --budget.

See hamr <command> --help for detailed options.

🛡️ GPU Profiles

Hamr adapts build quality to your hardware. Three profiles — from anvil to sky:

Auto-detection probes /sys, lspci, and glxinfo. Override with --budget minimal|standard|full.

🗡️ Design Lessons (from Seiðr-Smiðja)

Hamr incorporates hard-won lessons from building Seiðr-Smiðja:

🔧 Installation

# Install from PyPI
pip install hamr

# Or install from source
git clone https://github.com/hrabanazviking/Hamr.git
cd Hamr
pip install -e ".[dev]"

Requirements

• Python 3.10+
• Blender 3.4+ (for full build pipeline — headless mode)
• PyYAML, Pillow, numpy (auto-installed with pip)

🧪 Development

# Clone
git clone https://github.com/hrabanazviking/Hamr.git
cd Hamr

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
python3 -m pytest tests/ -q --tb=short

# Without Blender-dependent tests
python3 -m pytest tests/ -q -m "not blender and not e2e"

# With coverage
python3 -m pytest tests/ --cov=hamr --cov-report=term-missing

# Performance regression
python3 -m pytest tests/ -m perf

# Lint
ruff check src/ tests/

# Type check
mypy src/

See CONTRIBUTING.md for contribution guidelines, code style, and PR checklist.

🆕 What's New in v0.7.0

• MToon Anime Shaders — Full VRM MToon cel-shading spec: two-tone lighting, rim, outline, emission, transparency
• Spring Bone Tuning — Physics parameter presets, blending, validation, and energy estimation
• Pose Library — Pre-defined T-pose, A-pose, hand and facial poses with blending and VRM export
• 14-Stage Build Pipeline — Explicit numbered stages with timing, skip-stages, and dry-run
• 6 Character Presets — Built-in presets with deep merge
• Procedural Hair & Clothing — 5 hair styles, 6 clothing patterns, weight paint transfer
• Face Expressions — Auto-discovery of shape keys, VRM 1.0 expression presets (6+)
• VRM 1.0 Validator — Binary glTF parsing, bone coverage, spring bone validation
• GPU-Adaptive Quality — Pi 5 / Desktop / Cloud profiles with memory budget enforcement
• 2,233 Tests (2,206 pass, 27 skip, 0 fail) — Every forge tested, every path validated

See RELEASE_NOTES.md for the full changelog and MIGRATION.md for upgrade instructions.

📜 License

MIT License — see LICENSE for details.

Every vertex, every slider, every algorithm is yours.

🙏 Acknowledgments

• Seiðr-Smiðja — The predecessor forge that taught us what not to do
• MB-Lab — Open-source character base mesh
• VRM Consortium — VRM 1.0 specification
• Blender Foundation — For making the greatest 3D tool open source
• The Nornir — For weaving the threads that brought us here

<div align="center">

Forged in fire, quenched in ice, sharpened on the grindstone of experience.

ᚺᚨᛗᚱ — hamr — the shape you wear

</div>