# GameForge MCP (`gameforge-mcp`)

**The 100% Open-Source Game Studio & AI Asset Consistency Gateway (Model Context Protocol) — `v2.0.0`**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![Version: 2.0.0](https://img.shields.io/badge/Version-2.0.0-00b894.svg)](./package.json)
[![Node.js >= 22.5](https://img.shields.io/badge/Node.js-%3E%3D22.5-339933.svg)](https://nodejs.org)
[![Zero Dependencies](https://img.shields.io/badge/Dependencies-0-success.svg)](./package.json)
[![MCP Tools: 24](https://img.shields.io/badge/MCP_Tools-24-purple.svg)](#the-24-studio-tools)
[![Adversarial QA: 10.0/10](https://img.shields.io/badge/3rd--Party_QA_Crucible-10.0%2F10-brightgreen.svg)](./tests/run-tests.mjs)

Most AI game-art workflows collapse the moment you try to build a playable **2D** or **2.5D** game: armor mutates across 8 directional angles, weapon lengths drift frame-to-frame, camera pitch angles clash (`35.264°` true isometric vs `26.565°` 2:1 pixel-dimetric), semi-transparent AI alpha fringes ruin dark cave backgrounds, feet skate across tiles, and swappable avatar equipment clips through bodies.

**GameForge MCP (`v2.0.0`)** turns any MCP-capable coding agent (Google Antigravity, Claude Code, Claude Desktop, Cursor, Windsurf, Roo Code, Zed) into a deterministic **Technical Art Director, Native Binary PNG/Normal-Map Atlas Compiler, and Multi-Engine Pipeline Builder**—bridging **Blender 4.x**, **ComfyUI (Split FLUX / Merged SDXL / ControlNet / IP-Adapter / BiRefNet)**, **TRELLIS.2 / Hunyuan3D 2.1 / TripoSR**, **UniRig**, **LibreSprite / Aseprite**, **LDtk / Material Maker**, **Godot 4**, **Unity**, and **Unreal Engine 5**.

* **0 External NPM Dependencies** — Built directly on Node.js 22+ native `node:sqlite`, `node:zlib`, `node:net`, and `node:http`. Includes a custom RFC-2083 binary PNG decoder/encoder, CIE `L*a*b*` perceptual palette quantizer, and tangent-space normal-map stitcher with zero `node-gyp` build failures.
* **100% Open-Source Stack** — MIT licensed, built exclusively around open-weights models and open DCC bridges with zero paid cloud credit walls.

---

## Live `v2.0.0` Output Showcase (Generated Out-of-the-Box in `<1s`)

Every asset in [`./examples/valkyrie-25d-showcase/`](./examples/valkyrie-25d-showcase/) was compiled in a single tool call via `gameforge_build_complete_character_slice` + `gameforge_generate_tileset_spec` using **zero external npm packages**:

| 8-Dir × 6-Frame 2.5D Albedo Atlas (`0px` Foot Jitter) | Paired Camera-Space Tangent Normal Atlas (`[0..1]` RGB) |
| :---: | :---: |
| ![Valkyrie 2.5D Albedo Atlas](./examples/valkyrie-25d-showcase/atlases/aegis_paladin_walk_atlas.png) | ![Valkyrie 2.5D Normal Map Atlas](./examples/valkyrie-25d-showcase/atlases/aegis_paladin_walk_normal_atlas.png) |
| **100% CIE `L*a*b*` Palette Locked** • **`0` Semi-Transparent Halo Pixels** • **1px Chromatic Outline** | **Dynamic 2D/2.5D Torchlight Ready** (`Godot CanvasTexture` / `Unity URP _NormalMap` / `UE5 Paper2D`) |

### Canonical 47-Tile Blob Auto-Tile Bitmask Template (`sanctuary_blob47_template_mask.png`)

![47-Tile Blob Auto-Tile Mask](./examples/valkyrie-25d-showcase/tilesets/sanctuary_blob47_template_mask.png)

* **Interactive 2.5D Torchlight & Paper-Doll Studio**: Open [`examples/valkyrie-25d-showcase/atlases/aegis_paladin_preview_studio.html`](./examples/valkyrie-25d-showcase/atlases/aegis_paladin_preview_studio.html) directly in any browser to drag a live 3D point light across the tangent normal map, toggle modular sword/cape Paper-Doll layers with directional Z-sorting, scrub all 8 directions, and inspect the locked foot-pivot crosshair.

---

## What's New in `v2.0.0`

1. **Native RFC-2083 Binary PNG Codec, CIELAB Quantizer & Dual Atlas Stitcher (`src/codec/png-codec.mjs`)** — Pure JavaScript PNG decoder (supporting all 5 PNG scanline filters including Paeth) and `node:zlib` encoder. Strips AI alpha halos (`alpha < threshold → 0`, `>= threshold → 255`), snaps every pixel to your locked `.gpl` palette in perceptual CIE `L*a*b*` space (with optional `4×4` Bayer dithering), injects 1px chromatic outlines, locks every frame's lowest opaque pixel to an exact foot-pivot baseline (`0px` vertical jitter), and stitches paired Albedo + Tangent Normal-Map sprite sheets.
2. **Self-Adapting ComfyUI Live Introspector (`src/wings/comfy-wing.mjs`)** — Queries live `GET /object_info` on your ComfyUI server, supports both split FLUX (`UNETLoader` + `DualCLIPLoader` + `FluxGuidance` + `VAELoader`) and merged single-file checkpoints (`CheckpointLoaderSimple`), auto-selects whichever background-removal node you have installed (`BiRefNet_Hugo`, `BiRefNet`, `RMBG`, `ImageRemoveBackground+`), and cleanly falls back to loop-free stock `LoadImage` submission when `VHS_LoadImagesPath` is absent.
3. **20-Bone Game Humanoid Rig, Mixamo Retargeter & 6 Procedural Clips (`src/wings/blender-wing.mjs`)** — Builds a complete 20-bone game skeleton (`root`, `hips`, `DEF-spine` chain, `shoulder/upper_arm/forearm/DEF-hand.L/R`, `thigh/shin/foot.L/R`), retargets external Mixamo `.fbx` animations (`MIXAMO_MAP`), generates 6 procedural biomechanical Blender Actions (`idle`, `walk`, `run`, `slash_combo_1`, `cast_spell`, `death`), renders Freestyle 1px lineart passes, and bakes remapped `[0..1]` Camera-Space Tangent Normal Maps.
4. **Zero-Placeholder Pre-Sliced Godot 4, Unity C#, and Unreal 5 Exporters + 10-Point Pixel QA Gate (`src/wings/engine-wing.mjs`)** — Godot `.tres` pre-slices every `Cols × Rows` `SubResource("AtlasTexture_...")` `Rect2` region and wires `CanvasTexture` diffuse + normal maps; Unity C# `AssetPostprocessor` slices `SpriteMetaData[]` + binds URP 2D `_NormalMap` while `StudioBuilder.cs` wires `ObjectReferenceKeyframe[]` sprite curves into `.anim` clips + saves `.prefab`; UE5 Python imports Albedo + Normal PNGs into directional `PaperFlipbook` assets; and `gameforge_audit_asset_consistency` verifies binary pixel compliance across 10 deterministic checks.
5. **One-Shot Vertical Slice Compiler & Standalone HTML5 Torchlight Studio (`src/wings/preview-wing.mjs`)** — `gameforge_build_complete_character_slice` executes Vault initialization, Style Bible lock, Character registration, Paper-Doll Z-matrix computation, Combat frame-data, Procedural 2.5D + Normal + Gear synthesis, Binary PNG atlas stitching, Godot/Unity/Unreal exports, Interactive HTML5 Torchlight Studio generation, and the 10-Point Pixel QA Gate in a single call.

---

## How GameForge Solves Multi-Angle & Frame-to-Frame Consistency

Instead of asking a 2D diffusion model to guess poses across 8 directions and 12 animation frames, GameForge enforces **"3D Structural Truth + 2D Style Lock + Binary Pixel Verification"**:

```text
[1. SQLite Style & Scale Vault]
    Locks Camera Pitch (26.565° / 30° / 35.264° / 38° / 0°), PPU, Hue-Shifted .gpl Palette & Safe Denoise Bounds
           │
           ▼
[2. Self-Adapting Canonical 4-View Turnaround (ComfyUI Split FLUX / SDXL + BiRefNet)]
    Locks Front / Right / Back / 3-Quarter Orthographic Identity on Neutral #808080 Matte
           │
           ▼
[3. Open-Source 3D Mesh + 20-Bone Rigging (TRELLIS.2 / Hunyuan3D / TripoSR -> UniRig / Blender 20-Bone + Mixamo)]
    Normalizes exact standing height in meters, plants feet at Z=0, parents Paper-Doll Bone Sockets + 6 Clips
           │
           ▼
[4. Deterministic Blender 4.x Orthographic Multi-Pass Baker]
    Renders 8/16 Directions × N Frames: Beauty + Depth + Freestyle Lineart + [0..1] Tangent Normal + Socket JSON
           │
           ▼
[5. Controlled ComfyUI Style Pass + Native RFC-2083 Binary PNG & CIELAB Atlas Compiler]
    ControlNet (Depth 0.78 + Lineart 0.68) + IP-Adapter (0.60) + Clamped Denoise -> Halo Strip + 0px Foot Lock
           │
           ▼
[6. Pre-Sliced Multi-Engine Exporters + HTML5 2.5D Torchlight Studio + 10-Point Pixel QA Gate]
    • Godot 4.x (Pre-sliced Rect2 SpriteFrames .tres, Normal-Lit CanvasTexture, .tscn, GDScript Controller)
    • Unity (C# SpriteMetaData[] Slicer, _NormalMap Secondary Texture, ObjectReferenceKeyframe[] .anim + .prefab)
    • Unreal Engine 5 (Python Albedo + Normal Import, Directional PaperFlipbook Builder, Ortho SpringArm)
```

---

## 7 Built-In Studio Camera & Genre Presets

| Preset ID | Inspired By | Camera Pitch | Directions | Tile Grid | Core Technique |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `ragnarok_25d_dimetric` | *Ragnarok Online* | `30.0°` Ortho | 8 (`45°`) | `128×64` | 3D World + 8-dir layered Paper-Doll sprites with per-angle Z-order swaps |
| `tos_25d_ortho3d` | *Tree of Savior* | `38.0°` Ortho | 8 / 360° | `256×128` | Live rigged 3D low/mid-poly meshes with hand-painted unlit/toon + inverted-hull outlines |
| `diablo_25d_isometric` | *Diablo II: Resurrected* | `26.565°` (`atan(0.5)`) | 16 (`22.5°`) | `128×64` (`2:1`) | Exact 2:1 pixel-dimetric 16-angle pre-rendered sprites + contact shadows + normal maps |
| `true_isometric_tactics` | *FF Tactics / Tactics Ogre* | `35.264°` (`atan(1/√2)`) | 4 (`90°`) | `64×32` | True CAD isometric grid elevation tactics |
| `hd2d_diorama` | *Octopath Traveler* | `28.0°` Hybrid | 8 (`45°`) | `32×32` | 3D PBR tilt-shift diorama world + point-filtered pixel billboards lit by 3D lights |
| `deadcells_3d_to_2d` | *Dead Cells* | `0.0°` Side Ortho | 2 (`L/R`) | `32×32` | Blender `filter_size=0.01px` zero-AA render + tangent-space Normal Maps for dynamic 2D lights |
| `pixel_platformer_2d` | *Celeste / Hollow Knight* | `0.0°` Side Ortho | 2 (`L/R`) | `32×32` | Crisp 2D sprites + coyote-time/jump-buffer physics + 47-tile Blob auto-tiles |

---

## Quickstart & Installation

Requires **Node.js >= 22.5.0** (uses built-in `node:sqlite` and `node:zlib`).

```bash
git clone https://github.com/Andrew012410/gameforge-mcp.git
cd gameforge-mcp

# Run the built-in open-source ecosystem doctor
node ./bin/gameforge-mcp.mjs --doctor

# Run the full 24-tool adversarial integration & binary pixel QA suite
npm test
```

### Add to MCP Client (`mcp_config.json` / `claude_desktop_config.json` / `.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "gameforge-mcp": {
      "command": "node",
      "args": ["--no-warnings", "/ABSOLUTE/PATH/TO/gameforge-mcp/bin/gameforge-mcp.mjs"],
      "env": {
        "COMFYUI_URL": "http://127.0.0.1:8188",
        "BLENDER_HOST": "127.0.0.1",
        "BLENDER_PORT": "9876"
      }
    }
  }
}
```

---

## The 24 Studio Tools

### Wing A — SQLite Style Vault, Scale Trigonometry & Paper-Doll Math (`src/wings/vault-wing.mjs`)
1. `gameforge_init_project` — Locks camera projection, pitch, PPU, tile diamond ratio, sun vector, and asset folders.
2. `gameforge_lock_style_bible` — Generates hue-shifted 5-step color ramps, `.gpl` GIMP/LibreSprite palettes, and safe ComfyUI denoise bounds.
3. `gameforge_register_character` — Computes foreshortened orthographic pixel height (`height_m × cos(pitch) × PPU`), deterministic seed, and bone sockets.
4. `gameforge_compute_paperdoll_zorder` — Solves 8/16-direction Z-priority draw order for modular gear (`body`, `head`, `hair`, `weapon_r`, `offhand_l`, `cape_wings_back`).
5. `gameforge_define_combat_framedata` — Stores animation FPS, `startup`/`active`/`recovery` combat windows, hitstop ms, and AABB hitboxes.

### Wing B — Self-Adapting ComfyUI Turnaround, Style Lock & FluxGym LoRA (`src/wings/comfy-wing.mjs`)
6. `gameforge_introspect_comfyui` — Queries live ComfyUI `GET /object_info` to detect split FLUX (`UNETLoader`), checkpoints, ControlNet, IP-Adapter, BiRefNet/RMBG, and VHS batch nodes.
7. `gameforge_generate_turnaround_workflow` — Builds/submits split-FLUX or merged-checkpoint + BiRefNet 4-view orthographic turnaround ComfyUI API graphs.
8. `gameforge_generate_consistent_sprites_workflow` — Multi-pass ControlNet (Depth + Lineart) + IP-Adapter + clamped denoise + BiRefNet sprite workflow (with loop-free stock `LoadImage` fallback).
9. `gameforge_generate_lora_dataset_plan` — Generates FluxGym / Kohya `.toml` configs and captioned manifests for local character/world Micro-LoRAs.

### Wing C — Open-Source 3D (`TRELLIS.2` / `Hunyuan3D` / `TripoSR`), 20-Bone Rigging & Ortho Baker (`src/wings/blender-wing.mjs`)
10. `gameforge_generate_3d_from_sheet` — Self-hosted Python runners for TRELLIS.2, Hunyuan3D 2.1, and MIT TripoSR + UniRig follow-up.
11. `gameforge_blender_rig_and_sockets` — Generates/executes Blender 4.x `bpy` scripts for metric scaling, 20-bone game armature binding, Mixamo `.fbx` retargeting, 6 procedural animation clips, Paper-Doll `Empty` sockets, and *Tree of Savior* inverted-hull outlines.
12. `gameforge_blender_ortho_turntable_bake` — Renders 8/16-direction Beauty, Depth, Freestyle 1px Lineart, `[0..1]` Camera-Space Tangent Normal Map, and projected `sockets_per_frame.json` pixel coordinates.

### Wing D — Native Binary PNG Codec, CIELAB Quantizer & LibreSprite Cleanup (`src/wings/sprite-wing.mjs`)
13. `gameforge_synthesize_procedural_frames` — Pure-JS 3D oriented-capsule 2.5D character, tangent normal-map, and modular Paper-Doll gear frame synthesizer for instant zero-GPU vertical slices and pipeline testing.
14. `gameforge_compile_sprite_atlas` — Native RFC-2083 binary PNG decoder/encoder that strips semi-transparent alpha fringes, quantizes to `.gpl` palettes in CIE `L*a*b*`, injects 1px chromatic outlines, locks `0px` foot-pivot jitter, and stitches paired Albedo + Normal-Map sprite sheets.
15. `gameforge_libresprite_cleanup_script` — Lua CLI batch script + native pure-Node fallback (`run_native_fallback`) for alpha cleanup and palette snapping.

### Wing E — Worlds, 47-Tile Auto-Tiles & Procedural PBR (`src/wings/world-wing.mjs`)
16. `gameforge_generate_tileset_spec` — Computes canonical 47-tile Blob & 16-tile Wang bitmasks, renders a pixel-exact `.png` bitmask template (`render_template_png`), and exports LDtk JSON + Material Maker PBR recipes.

### Wing F — Pre-Sliced Multi-Engine Exporters, 10-Point Pixel QA Gate & Studio Codex (`src/wings/engine-wing.mjs`)
17. `gameforge_export_godot_package` — Exports Godot 4 `.tscn`, pre-sliced `Cols × Rows` `AtlasTexture` `SpriteFrames` `.tres`, Normal-Lit `CanvasTexture`, and 2D/2.5D GDScript controllers.
18. `gameforge_export_unity_package` — Exports Unity C# `AssetPostprocessor` (`SpriteMetaData[]` slicer + `_NormalMap` binding), `ObjectReferenceKeyframe[]` `.anim` + 8-way `BlendTree` + `.prefab` builder, and runtime Y-Sort/Hitstop scripts.
19. `gameforge_export_unreal_package` — Exports Unreal Engine 5 Python scripts importing Albedo + Normal PNGs, generating directional `PaperFlipbook` assets, and configuring Orthographic `SpringArm` cameras.
20. `gameforge_audit_asset_consistency` — 10-Point Technical Art & Binary Pixel QA Gate verifying camera math, denoise bounds, scale ratio, foot-pivot jitter (`0px`), binary PNG palette compliance, `0` semi-transparent fringe pixels, normal-map parity, Paper-Doll Z-matrix, and combat frame-data (`0–100`).
21. `gameforge_discover_ecosystem` — Live probe for BlenderMCP socket, Blender CLI, ComfyUI, TRELLIS/UniRig, Godot 4, LibreSprite, and Ollama.
22. `gameforge_query_codex` — Instant search across the built-in Technical Art & Game Engine Studio Codex.

### Wing G — Interactive 2.5D Torchlight Studio & One-Shot Vertical Slice Compiler (`src/wings/preview-wing.mjs`)
23. `gameforge_generate_interactive_preview` — Builds a self-contained HTML5 2.5D Normal-Lit Torchlight & Paper-Doll Inspection Studio with embedded base64 atlases, real-time `N·L` point-light shader math, modular gear toggles, and foot-pivot crosshair overlay.
24. `gameforge_build_complete_character_slice` — Compiles an entire 2.5D character vertical slice end-to-end (Vault → Style Bible → Character → Paper-Doll Z-Matrix → Combat Frame-Data → Albedo + Normal + Gear Atlases → Godot/Unity/Unreal Exports → HTML5 Torchlight Studio → 10-Point QA Gate) in one tool call.

---

## License

MIT © GameForge Open-Source Contributors.