lpc-forge 1.0.0

package/README.md

@@ -0,0 +1,281 @@
+<div align="center">
+
+# ⚔️ LPC Forge
+
+**Generate a complete 2D RPG from one command.**
+
+Characters · Maps · Enemy AI · Inventory · Dialog · Menus · SFX · Lighting · Particles · Godot 4.6
+
+[![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-21+-green.svg)](https://nodejs.org)
+[![Godot](https://img.shields.io/badge/Godot-4.6+-purple.svg)](https://godotengine.org)
+[![CI](https://github.com/LaunchDay-Studio-Inc/lpc-forge/actions/workflows/ci.yml/badge.svg)](https://github.com/LaunchDay-Studio-Inc/lpc-forge/actions)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/bJDGXc4DvW)
+
+[Website](https://blueth.online) · [Get Premium](https://launchday.gumroad.com/l/lpc-forge-premium) · [Discord](https://discord.gg/bJDGXc4DvW) · [Report Bug](https://github.com/LaunchDay-Studio-Inc/lpc-forge/issues)
+
+</div>
+
+---
+
+## What is LPC Forge?
+
+LPC Forge generates **playable 2D RPG projects** for Godot 4.6 using [Liberated Pixel Cup](https://lpc.opengameart.org/) assets. Not just sprites — complete game projects with working systems you can customize.
+
+**Free tier** gives you characters, maps, and a basic playable project.
+**Premium** ($10) gives you the full RPG game kit — inventory, dialog, enemy AI, menus, save/load, sound effects, lighting, particles, and more. All from one command.
+
+```bash
+# Free — character + map + basic project
+lpc-forge init my-rpg
+
+# Premium — complete playable RPG
+lpc-forge init my-rpg --full
+```
+
+Open in Godot → Press F5 → **Play.**
+
+---
+
+## Quick Start
+
+```bash
+# Clone and install
+git clone https://github.com/LaunchDay-Studio-Inc/lpc-forge.git
+cd lpc-forge
+npm install && npm run build
+
+# Generate a free project
+npx lpc-forge init my-rpg
+
+# Open in Godot 4.6 → Import → Select my-rpg/project.godot → Press F5
+```
+
+---
+
+## Free vs Premium
+
+| Feature | Free | Premium ($10) |
+|---------|:----:|:-------------:|
+| **Character Compositor** (17 presets, custom specs) | ✅ | ✅ |
+| **Map Generation** (dungeon, cave, overworld, town, WFC, multifloor) | ✅ | ✅ |
+| **Godot Project Scaffold** (player controller, hitbox, camera, HUD) | ✅ | ✅ |
+| **Batch Character Generation** | ✅ | ✅ |
+| **Enemy AI** (patrol, chase, attack, flee, boss patterns) | — | ✅ |
+| **Inventory System** (grid UI, equip, stack, drag-drop, tooltips) | — | ✅ |
+| **Dialog System** (text box, choices, portraits, typing effect) | — | ✅ |
+| **Menu System** (main, pause, settings, game over, credits) | — | ✅ |
+| **Save/Load** (JSON, 3 slots, auto-save) | — | ✅ |
+| **Scene Transitions** (doors, stairs, fade, area loading) | — | ✅ |
+| **Loot & Drop System** (drop tables, item pickup, XP/gold drops) | — | ✅ |
+| **Quest Tracker** (objectives, markers, completion) | — | ✅ |
+| **Day/Night Cycle** (time-of-day modulation, lamp auto-on) | — | ✅ |
+| **Full HUD** (HP, MP, XP, gold, minimap, hotbar, buffs) | — | ✅ |
+| **Sound Effects** (45 procedural SFX: combat, UI, movement, magic) | — | ✅ |
+| **Music Catalog** (curated CC0 BGM tracks for every scene type) | — | ✅ |
+| **UI Kit** (panels, buttons, frames, tooltips, medieval theme) | — | ✅ |
+| **Item Icons** (swords, potions, scrolls, armor, food, keys) | — | ✅ |
+| **Props** (chests, barrels, torches, signs, wells, fences) | — | ✅ |
+| **Character Portraits** (auto-cropped, 3 sizes) | — | ✅ |
+| **Lighting Presets** (8 presets: dungeon, overworld, cave, boss arena) | — | ✅ |
+| **Particle Effects** (8 effects: rain, snow, fireflies, fire, magic) | — | ✅ |
+| **Enemy Characters** (skeleton, guard, thief — full spritesheets) | — | ✅ |
+| **NPC Characters** (merchant, healer, peasant — full spritesheets) | — | ✅ |
+| **Autoload Wiring** (systems auto-registered in project.godot) | — | ✅ |
+| **Input Actions** (inventory, interact, pause, quest log pre-configured) | — | ✅ |
+
+### Get Premium
+
+```bash
+# 1. Purchase at https://launchday.gumroad.com/l/lpc-forge-premium
+# 2. Activate your license key
+lpc-forge activate <your-license-key>
+
+# 3. Generate a complete RPG
+lpc-forge init my-rpg --full
+```
+
+$10. One-time purchase. Unlimited projects. No subscription.
+
+---
+
+## Commands
+
+### Free Commands
+
+```bash
+# Character compositor
+lpc-forge character --preset paladin -o ./output
+lpc-forge character --body female --hair plain:blonde --armor plate:gold
+lpc-forge character --list-layers
+
+# Batch generation
+lpc-forge batch --presets warrior,mage,rogue -o ./output
+
+# Map generation
+lpc-forge map --type dungeon --width 50 --height 50 -o ./output
+lpc-forge map --type overworld --seed "my-world" -o ./output
+
+# List all presets
+lpc-forge list
+
+# Project scaffold (free tier)
+lpc-forge init my-rpg --character warrior --map dungeon
+```
+
+### Premium Commands
+
+```bash
+# Full RPG project (all systems, all assets)
+lpc-forge init my-rpg --full
+
+# Individual premium generators
+lpc-forge systems --list                          # Preview (free)
+lpc-forge systems -o ./output                     # Generate (premium)
+lpc-forge sfx --list                              # Preview (free)
+lpc-forge sfx -o ./output                         # Generate (premium)
+lpc-forge ui --list-themes                        # Preview (free)
+lpc-forge ui -o ./output                          # Generate (premium)
+lpc-forge lighting --list                         # Preview (free)
+lpc-forge lighting -o ./output                    # Generate (premium)
+lpc-forge particles --list                        # Preview (free)
+lpc-forge particles -o ./output                   # Generate (premium)
+lpc-forge icons -o ./output                       # Generate (premium)
+lpc-forge props -o ./output                       # Generate (premium)
+lpc-forge portrait --character warrior -o ./output # Generate (premium)
+
+# License management
+lpc-forge activate <key>          # Activate license
+lpc-forge activate --status       # Check license status
+lpc-forge activate --deactivate   # Remove license
+```
+
+---
+
+## What `init --full` Generates
+
+```
+my-rpg/
+├── project.godot                    # Pre-configured with autoloads + input actions
+├── sprites/
+│   ├── warrior/                     # Player character (8-dir, all animations)
+│   ├── skeleton/                    # Enemy character
+│   ├── guard/                       # Enemy character
+│   ├── thief/                       # Enemy character
+│   ├── npc_merchant/                # NPC character
+│   ├── npc_healer/                  # NPC character
+│   └── npc_peasant/                 # NPC character
+├── scripts/
+│   ├── player.gd                    # State machine player controller
+│   ├── enemy_ai.gd                  # Patrol/chase/attack FSM
+│   ├── inventory_manager.gd         # Grid inventory system (autoload)
+│   ├── inventory_ui.gd              # Drag-drop inventory UI
+│   ├── dialog_manager.gd            # Dialog system (autoload)
+│   ├── dialog_box.gd                # Text box with typing effect
+│   ├── save_manager.gd              # Save/load system (autoload)
+│   ├── scene_manager.gd             # Scene transitions (autoload)
+│   ├── loot_manager.gd              # Drop tables and item pickup (autoload)
+│   ├── quest_manager.gd             # Quest tracker (autoload)
+│   ├── day_night.gd                 # Day/night cycle (autoload)
+│   ├── menu_manager.gd              # Menu system (autoload)
+│   ├── hud.gd                       # Full HUD (autoload)
+│   └── game_config.gd               # Global game constants
+├── dungeon.tscn                     # Generated dungeon map
+├── tileset/                         # Terrain tiles
+├── ui/                              # UI kit (panels, buttons, frames)
+├── icons/                           # Item icon sprites
+├── props/                           # Prop sprites
+├── portraits/                       # Character portraits (3 sizes)
+├── lighting/                        # 8 lighting preset scenes
+├── particles/                       # 8 particle effect scenes
+├── sfx/                             # 45 sound effects (.wav)
+├── music/                           # BGM tracks catalog
+└── map_preview.png                  # Map overview image
+```
+
+**Open in Godot → Press F5 → Walk around, fight enemies, open inventory, talk to NPCs.**
+
+---
+
+## Character Presets
+
+| Preset | Layers | Style |
+|--------|--------|-------|
+| `warrior` | Plate armor, longsword, brown hair | Classic RPG fighter |
+| `mage` | Robe, staff, white hair | Spellcaster |
+| `rogue` | Leather armor, dagger, black hair | Stealth class |
+| `ranger` | Leather, bow, green hood | Ranged fighter |
+| `paladin` | Gold plate, greatsword, blonde hair | Holy knight |
+| `necromancer` | Dark robe, skull staff, bald | Dark magic |
+| `cleric` | White robe, mace, brown hair | Healer |
+| `barbarian` | Fur armor, battleaxe, red hair | Berserker |
+| `monk` | Simple clothes, bo staff, shaved head | Martial arts |
+| `bard` | Fancy clothes, lute, curly hair | Support class |
+| ...and 7 more | | |
+
+```bash
+# See all presets
+lpc-forge list
+```
+
+---
+
+## Map Types
+
+| Type | Algorithm | Features |
+|------|-----------|----------|
+| `dungeon` | BSP (Binary Space Partition) | Rooms, corridors, doors, spawn/treasure/boss POIs |
+| `cave` | Cellular Automata | Organic caverns, varied openness |
+| `overworld` | Multi-octave noise | Biomes, rivers, mountains, forests |
+| `town` | District-based | Houses, shops, roads, town square |
+| `wfc` | Wave Function Collapse | Pattern-based, highly varied |
+| `multifloor` | Stacked BSP | Multi-level dungeons with stairs |
+
+```bash
+lpc-forge map --type dungeon --width 60 --height 60 --seed "my-dungeon" -o ./output
+```
+
+---
+
+## License & Credits
+
+### Tool License
+
+LPC Forge (the CLI tool) is licensed under **GPL-3.0-or-later**. See [LICENSE](LICENSE).
+
+### Asset Licenses
+
+Character sprites use [Liberated Pixel Cup](https://lpc.opengameart.org/) assets under **CC-BY-SA 3.0** and **CC-BY-SA 4.0**. Full artist credits in [CREDITS.csv](CREDITS.csv).
+
+Premium assets include curated content from OpenGameArt.org under CC0/CC-BY-SA licenses. When distributing games made with LPC Forge, include the generated `CREDITS.md` file.
+
+### Premium License
+
+LPC Forge Premium (the `--full` content pack, game systems, SFX presets, and curated assets) is sold separately at [blueth.online](https://launchday.gumroad.com/l/lpc-forge-premium). One-time purchase, unlimited projects, no subscription.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome for the open-source core — character presets, map algorithms, export improvements.
+
+Premium features (systems, SFX, UI, lighting, particles) are maintained by [LaunchDay Studio](https://launchdaystudio.com).
+
+---
+
+## Links
+
+- 🌐 [blueth.online](https://blueth.online) — Blueth Plugin Marketplace
+- 💬 [Discord](https://discord.gg/bJDGXc4DvW) — Community & Support
+- 🐛 [Issues](https://github.com/LaunchDay-Studio-Inc/lpc-forge/issues) — Bug Reports
+- 📖 [LPC Wiki](https://lpc.opengameart.org/) — Liberated Pixel Cup
+
+---
+
+<div align="center">
+
+**Made by [LaunchDay Studio](https://launchdaystudio.com) 🚀**
+
+*Stop spending weeks on placeholder art. Start building your game.*
+
+</div>

package/dist/character/batch.d.ts

@@ -0,0 +1,17 @@
+import type { CharacterSpec } from './types.js';
+export interface BatchEntry {
+    name: string;
+    preset?: string;
+    spec?: CharacterSpec;
+    slice?: boolean;
+    godot?: boolean;
+}
+export interface BatchConfig {
+    characters: BatchEntry[];
+    outputDir?: string;
+}
+export declare function runBatch(configPath: string, repoRoot: string, outputBase: string): Promise<{
+    name: string;
+    success: boolean;
+    error?: string;
+}[]>;

package/dist/character/batch.js

@@ -0,0 +1,48 @@
+import { composeCharacter } from './composer.js';
+import { PRESETS } from './presets.js';
+import { sliceCharacter } from './slicer.js';
+import { exportCharacterToGodot } from '../export/godot.js';
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+export async function runBatch(configPath, repoRoot, outputBase) {
+    const raw = await readFile(configPath, 'utf-8');
+    const config = JSON.parse(raw);
+    const results = [];
+    for (const entry of config.characters) {
+        const outDir = resolve(outputBase, entry.name);
+        await mkdir(outDir, { recursive: true });
+        try {
+            let spec;
+            if (entry.preset) {
+                const preset = PRESETS[entry.preset];
+                if (!preset)
+                    throw new Error(`Unknown preset: ${entry.preset}`);
+                spec = preset.spec;
+            }
+            else if (entry.spec) {
+                spec = entry.spec;
+            }
+            else {
+                throw new Error('Each entry needs either "preset" or "spec"');
+            }
+            const buffer = await composeCharacter(spec, repoRoot);
+            await writeFile(join(outDir, 'spritesheet.png'), buffer);
+            if (entry.slice) {
+                await sliceCharacter(buffer, join(outDir, 'frames'));
+            }
+            if (entry.godot) {
+                await exportCharacterToGodot(buffer, outDir, entry.name);
+            }
+            results.push({ name: entry.name, success: true });
+        }
+        catch (err) {
+            results.push({
+                name: entry.name,
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=batch.js.map

package/dist/character/batch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.js","sourceRoot":"","sources":["../../src/character/batch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAe1C,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,UAAkB,EAClB,QAAgB,EAChB,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAChD,MAAM,MAAM,GAAgB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAyD,EAAE,CAAC;IAEzE,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC/C,MAAM,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAEzC,IAAI,CAAC;YACH,IAAI,IAAmB,CAAC;YACxB,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;gBACjB,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBACrC,IAAI,CAAC,MAAM;oBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;gBAChE,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;YACrB,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBACtB,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;YACpB,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;YAChE,CAAC;YAED,MAAM,MAAM,GAAG,MAAM,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACtD,MAAM,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC,CAAC;YAEzD,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBAChB,MAAM,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;YACvD,CAAC;YAED,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;gBAChB,MAAM,sBAAsB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YAC3D,CAAC;YAED,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,KAAK,CAAC,IAAI;gBAChB,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/character/composer.d.ts

@@ -0,0 +1,3 @@
+import { type CharacterSpec } from './types.js';
+/** Compose a complete character spritesheet from a CharacterSpec */
+export declare function composeCharacter(spec: CharacterSpec, repoRoot: string): Promise<Buffer>;

package/dist/character/composer.js

@@ -0,0 +1,164 @@
+import sharp from 'sharp';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { ANIMATIONS, FRAME_SIZE, SHEET_WIDTH, SHEET_HEIGHT, ANIMATION_FOLDER_MAP, } from './types.js';
+import { loadDefinitions, findDefinition } from './definitions.js';
+/** Compose a complete character spritesheet from a CharacterSpec */
+export async function composeCharacter(spec, repoRoot) {
+    const registry = await loadDefinitions(repoRoot);
+    const spritesDir = join(repoRoot, 'spritesheets');
+    // Resolve all layers to concrete sprite paths
+    const resolvedLayers = [];
+    for (const layer of spec.layers) {
+        const def = findDefinition(registry, layer.category, layer.subcategory);
+        if (!def) {
+            console.warn(`Warning: No definition found for ${layer.category}/${layer.subcategory}, skipping`);
+            continue;
+        }
+        for (const entry of def.layers) {
+            // Skip custom animation layers for now (oversize attacks, etc.)
+            if (entry.customAnimation)
+                continue;
+            const basePath = entry.paths[spec.bodyType];
+            if (!basePath) {
+                // Try to find a fallback body type
+                const fallback = findFallbackBodyType(entry.paths, spec.bodyType);
+                if (!fallback) {
+                    console.warn(`Warning: ${def.name} layer has no path for body type "${spec.bodyType}", skipping`);
+                    continue;
+                }
+                resolvedLayers.push({
+                    zPos: entry.zPos,
+                    basePath: fallback,
+                    variant: layer.variant,
+                    animations: def.animations,
+                });
+            }
+            else {
+                resolvedLayers.push({
+                    zPos: entry.zPos,
+                    basePath,
+                    variant: layer.variant,
+                    animations: def.animations,
+                });
+            }
+        }
+    }
+    // Sort by zPos ascending (back to front)
+    resolvedLayers.sort((a, b) => a.zPos - b.zPos);
+    // Build universal sheets for each resolved layer
+    const layerBuffers = [];
+    for (const layer of resolvedLayers) {
+        const buffer = await buildUniversalSheet(layer, spritesDir);
+        if (buffer) {
+            layerBuffers.push(buffer);
+        }
+    }
+    if (layerBuffers.length === 0) {
+        throw new Error('No valid layers could be loaded. Check your CharacterSpec.');
+    }
+    // Composite all layers together
+    const composites = layerBuffers.map((input) => ({
+        input,
+        top: 0,
+        left: 0,
+        blend: 'over',
+    }));
+    return sharp({
+        create: {
+            width: SHEET_WIDTH,
+            height: SHEET_HEIGHT,
+            channels: 4,
+            background: { r: 0, g: 0, b: 0, alpha: 0 },
+        },
+    })
+        .png()
+        .composite(composites)
+        .toBuffer();
+}
+function findFallbackBodyType(paths, bodyType) {
+    // Fallback chain
+    const fallbacks = {
+        muscular: ['male'],
+        pregnant: ['female'],
+        teen: ['male', 'female'],
+        child: ['teen', 'male'],
+    };
+    const chain = fallbacks[bodyType] ?? [];
+    for (const fb of chain) {
+        if (paths[fb])
+            return paths[fb];
+    }
+    return null;
+}
+/** Build a universal 832×3456 sheet from individual animation PNGs */
+async function buildUniversalSheet(layer, spritesDir) {
+    const composites = [];
+    // Map animation names used in definitions to folder names
+    const animationList = Object.keys(ANIMATIONS);
+    for (const animName of animationList) {
+        const animInfo = ANIMATIONS[animName];
+        // Check if this layer supports this animation
+        const defAnimNames = layer.animations.map((a) => {
+            const mapped = ANIMATION_FOLDER_MAP[a];
+            return mapped ?? a;
+        });
+        // The folder name might differ from the animation name
+        const folderName = ANIMATION_FOLDER_MAP[animName] ?? animName;
+        // Check if the definition lists this animation (using either name)
+        const supportsAnim = layer.animations.length === 0 || // no filter = all
+            layer.animations.some((a) => {
+                const mapped = ANIMATION_FOLDER_MAP[a] ?? a;
+                return mapped === animName || mapped === folderName || a === animName;
+            });
+        if (!supportsAnim)
+            continue;
+        // Convert variant name: spaces to underscores for filenames
+        const variantFile = layer.variant.replace(/ /g, '_');
+        // Try to find the animation PNG
+        const animPath = join(spritesDir, layer.basePath, folderName, `${variantFile}.png`);
+        if (!existsSync(animPath)) {
+            // Also try without folder mapping
+            const altPath = join(spritesDir, layer.basePath, animName, `${variantFile}.png`);
+            if (existsSync(altPath)) {
+                try {
+                    const buf = await sharp(altPath).png().toBuffer();
+                    composites.push({
+                        input: buf,
+                        top: animInfo.row * FRAME_SIZE,
+                        left: 0,
+                    });
+                }
+                catch {
+                    // Skip unreadable files
+                }
+            }
+            continue;
+        }
+        try {
+            const buf = await sharp(animPath).png().toBuffer();
+            composites.push({
+                input: buf,
+                top: animInfo.row * FRAME_SIZE,
+                left: 0,
+            });
+        }
+        catch {
+            // Skip unreadable files
+        }
+    }
+    if (composites.length === 0)
+        return null;
+    return sharp({
+        create: {
+            width: SHEET_WIDTH,
+            height: SHEET_HEIGHT,
+            channels: 4,
+            background: { r: 0, g: 0, b: 0, alpha: 0 },
+        },
+    })
+        .png()
+        .composite(composites)
+        .toBuffer();
+}
+//# sourceMappingURL=composer.js.map

package/dist/character/composer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composer.js","sourceRoot":"","sources":["../../src/character/composer.ts"],"names":[],"mappings":"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"}

package/dist/character/definitions.d.ts

@@ -0,0 +1,16 @@
+import type { LayerDefinition } from './types.js';
+export interface DefinitionRegistry {
+    /** All parsed definitions keyed by "category/subcategory" */
+    definitions: Map<string, LayerDefinition>;
+    /** All categories (body, hair, torso, etc.) */
+    categories: string[];
+}
+/** Recursively read all JSON definitions from sheet_definitions/ */
+export declare function loadDefinitions(repoRoot: string): Promise<DefinitionRegistry>;
+/** List all available layers grouped by category */
+export declare function listLayers(registry: DefinitionRegistry): Record<string, {
+    name: string;
+    variants: string[];
+}[]>;
+/** Find a definition by searching category and subcategory patterns */
+export declare function findDefinition(registry: DefinitionRegistry, category: string, subcategory: string): LayerDefinition | undefined;

package/dist/character/definitions.js

@@ -0,0 +1,116 @@
+import { readFile, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Recursively read all JSON definitions from sheet_definitions/ */
+export async function loadDefinitions(repoRoot) {
+    const defsDir = join(repoRoot, 'sheet_definitions');
+    const definitions = new Map();
+    const categories = await readdir(defsDir);
+    for (const category of categories) {
+        const categoryPath = join(defsDir, category);
+        const s = await stat(categoryPath);
+        if (!s.isDirectory())
+            continue;
+        await loadCategoryDefinitions(categoryPath, category, definitions);
+    }
+    return {
+        definitions,
+        categories: [...new Set([...definitions.values()].map((d) => d.name))],
+    };
+}
+async function loadCategoryDefinitions(dirPath, categoryPrefix, definitions) {
+    const entries = await readdir(dirPath);
+    for (const entry of entries) {
+        const fullPath = join(dirPath, entry);
+        const s = await stat(fullPath);
+        if (s.isDirectory()) {
+            // Recurse into subdirectories
+            await loadCategoryDefinitions(fullPath, categoryPrefix, definitions);
+        }
+        else if (entry.endsWith('.json') && !entry.startsWith('meta_')) {
+            try {
+                const def = await parseDefinitionFile(fullPath, categoryPrefix);
+                if (def) {
+                    definitions.set(def.name, def);
+                }
+            }
+            catch {
+                // Skip invalid JSON files
+            }
+        }
+    }
+}
+async function parseDefinitionFile(filePath, category) {
+    const content = await readFile(filePath, 'utf-8');
+    const json = JSON.parse(content);
+    if (!json.name)
+        return null;
+    // Extract layer entries (layer_1, layer_2, etc.)
+    const layers = [];
+    for (let i = 1; i <= 20; i++) {
+        const layerKey = `layer_${i}`;
+        const layerData = json[layerKey];
+        if (!layerData)
+            break;
+        const paths = {};
+        const bodyTypes = ['male', 'muscular', 'female', 'pregnant', 'teen', 'child'];
+        for (const bt of bodyTypes) {
+            if (layerData[bt]) {
+                paths[bt] = layerData[bt];
+            }
+        }
+        layers.push({
+            zPos: layerData.zPos ?? 0,
+            paths,
+            customAnimation: layerData.custom_animation,
+        });
+    }
+    if (layers.length === 0)
+        return null;
+    // Derive a subcategory key from the filename
+    const fileName = filePath.split('/').pop().replace('.json', '');
+    return {
+        name: `${category}/${fileName}`,
+        priority: json.priority ?? 0,
+        layers,
+        variants: json.variants ?? [],
+        animations: json.animations ?? [],
+        matchBodyColor: json.match_body_color ?? false,
+        typeName: json.type_name,
+    };
+}
+/** List all available layers grouped by category */
+export function listLayers(registry) {
+    const result = {};
+    for (const [key, def] of registry.definitions) {
+        const category = key.split('/')[0];
+        if (!result[category])
+            result[category] = [];
+        result[category].push({
+            name: key,
+            variants: def.variants,
+        });
+    }
+    return result;
+}
+/** Find a definition by searching category and subcategory patterns */
+export function findDefinition(registry, category, subcategory) {
+    // Try exact key match first
+    const exactKey = `${category}/${subcategory}`;
+    if (registry.definitions.has(exactKey)) {
+        return registry.definitions.get(exactKey);
+    }
+    // Try partial matching
+    for (const [key, def] of registry.definitions) {
+        if (key.startsWith(category + '/') && key.includes(subcategory)) {
+            return def;
+        }
+    }
+    // Try matching by type_name
+    for (const [, def] of registry.definitions) {
+        if (def.typeName === subcategory) {
+            return def;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=definitions.js.map