GameForge v0.2.0 - gradio.Server with custom frontend + ZeroGPU

DEPLOY.md

@@ -0,0 +1,42 @@
+# GameForge Space - HF Spaces Deployment
+#
+# To deploy this to Hugging Face Spaces:
+#
+# 1. Create a new Space on huggingface.co/new-space
+#    - SDK: Gradio
+#    - Hardware: ZeroGPU (free quota, 3.5 min/day)
+#
+# 2. Push this space/ directory:
+#    huggingface-cli upload jkorstad/gameforge-space ./space/
+#
+# 3. The app will be live at:
+#    https://huggingface.co/spaces/jkorstad/gameforge-space
+#
+# What you get:
+# - Custom HTML/JS frontend (not Gradio components)
+# - gradio.Server backend with FastAPI routes
+# - ZeroGPU for model inference (free!)
+# - Queuing and concurrency management
+# - gradio_client API compatibility
+# - MCP tool registration
+# - SSE streaming support
+#
+# API endpoints (all gradio_client compatible):
+# - /registry_info    - List all models
+# - /get_route        - Get routing for a model
+# - /list_pipelines   - List pipeline definitions
+# - /format_prompt    - Format prompt with templates
+# - /format_npc       - Format NPC dialogue
+# - /generate_image   - Generate image via FLUX (ZeroGPU)
+# - /generate_3d      - Generate 3D mesh via TRELLIS.2 (ZeroGPU)
+# - /generate_voice   - Generate voice via MeloTTS (ZeroGPU)
+# - /generate_video   - Generate video via LTX 2.3 (ZeroGPU)
+# - /generate_music   - Generate music via ACE-Step (ZeroGPU)
+# - /generate_sfx     - Generate SFX via TangoFlux (ZeroGPU)
+# - /list_assets      - Browse generated assets
+# - /validate_asset   - Validate asset quality
+# - /convert_asset    - Convert asset format
+#
+# MCP tools:
+# - gameforge_generate  - Generate any asset type
+# - gameforge_list_models - List available models

Dockerfile

@@ -0,0 +1,19 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install system deps for ffmpeg (audio conversion)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy and install Python deps
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy app
+COPY . .
+
+EXPOSE 7860
+
+CMD ["python", "app.py"]

README.md

@@ -1,15 +1,67 @@
 ---
-title: Gameforge
-emoji: 🏆
-colorFrom: blue
-colorTo: pink
+title: GameForge
+emoji: ⚔️
+colorFrom: purple
+colorTo: blue
 sdk: gradio
-sdk_version: 6.12.0
-python_version: '3.12'
+sdk_version: 5.25.0
 app_file: app.py
 pinned: false
 license: apache-2.0
-short_description: Open Source Asset Creation Platform
+tags:
+  - game-development
+  - asset-generation
+  - ai-pipeline
+  - text-to-image
+  - text-to-3d
+  - text-to-video
+  - text-to-speech
+  - text-to-music
+  - zerogpu
+models:
+  - black-forest-labs/FLUX.1-schnell
+  - microsoft/TRELLIS.2
+  - myshell-ai/MeloTTS
+short_description: "AI Game Asset Pipeline - Free open-source models"
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# GameForge - AI Game Asset Pipeline
+
+Generate production-ready game assets using best-in-class open-source AI models.
+Images, video, 3D meshes, audio, voice, music -- all from text prompts.
+
+**26 of 27 models are FREE** via Hugging Face ZeroGPU Spaces.
+
+## Asset Types
+
+| Type | Model | License |
+|------|-------|---------|
+| Images | FLUX.1-schnell | Apache 2.0 |
+| Video | LTX 2.3 Turbo | Apache 2.0 |
+| 3D | TRELLIS.2 | MIT |
+| Voice | MeloTTS | MIT |
+| Music | ACE-Step | Apache 2.0 |
+| SFX | TangoFlux | Apache 2.0 |
+
+## API
+
+This Space exposes a REST API via `gradio.Server`. You can call it programmatically:
+
+```python
+from gradio_client import Client
+
+client = Client("jkorstad/gameforge")
+
+# Generate an image
+result = client.predict("/generate_image", {"prompt": "fantasy knight"})
+
+# Generate NPC voice
+result = client.predict("/generate_voice", {"text": "Welcome, traveler!"})
+
+# List all models
+result = client.predict("/registry_info")
+```
+
+## License
+
+Apache-2.0

app.py

@@ -0,0 +1,476 @@
+"""
+GameForge Space Backend
+=======================
+HF Space using gradio.Server for custom frontend + ZeroGPU.
+Serves the GameForge web app with queued, concurrent-safe API endpoints.
+
+Deploy: push to HF Spaces with ZeroGPU hardware.
+"""
+
+import os
+import sys
+import json
+import asyncio
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+
+import spaces
+from gradio import Server
+from gradio.data_classes import FileData
+from fastapi.responses import HTMLResponse, FileResponse, JSONResponse
+import yaml
+
+# Add current dir to path for gameforge package
+sys.path.insert(0, str(Path(__file__).parent))
+
+# Import GameForge modules
+from gameforge.config.registry_loader import get_registry
+from gameforge.config.prompts import get_template_for_asset, format_npc_dialogue, list_templates
+from gameforge.engine.router import get_router
+from gameforge.engine.validator import validate_asset
+from gameforge.engine.converter import convert_asset, export_for_engine
+
+# Initialize
+registry = get_registry()
+router = get_router()
+
+# Storage for generated assets
+STORAGE_DIR = Path("/tmp/gameforge_assets")
+STORAGE_DIR.mkdir(parents=True, exist_ok=True)
+
+# Create the Server app
+app = Server()
+
+
+# ============================================================================
+# Static file serving
+# ============================================================================
+
+STATIC_DIR = Path(__file__).parent / "static"
+
+
+@app.get("/")
+async def homepage():
+    """Serve the main frontend."""
+    html_path = STATIC_DIR / "index.html"
+    if html_path.exists():
+        return HTMLResponse(html_path.read_text(encoding="utf-8"))
+    return HTMLResponse("<h1>GameForge</h1><p>Frontend not found</p>")
+
+
+@app.get("/static/{path:path}")
+async def static_files(path: str):
+    """Serve static assets (CSS, JS, fonts)."""
+    file_path = STATIC_DIR / path
+    if file_path.exists() and file_path.is_file():
+        media_types = {
+            ".css": "text/css",
+            ".js": "application/javascript",
+            ".png": "image/png",
+            ".jpg": "image/jpeg",
+            ".svg": "image/svg+xml",
+            ".woff2": "font/woff2",
+            ".woff": "font/woff",
+            ".ttf": "font/ttf",
+        }
+        ext = file_path.suffix.lower()
+        media_type = media_types.get(ext, "application/octet-stream")
+        return FileResponse(str(file_path), media_type=media_type)
+    return JSONResponse({"error": "Not found"}, status_code=404)
+
+
+# ============================================================================
+# API Endpoints (gradio_client compatible via @app.api)
+# ============================================================================
+
+@app.api()
+def registry_info() -> Dict[str, Any]:
+    """Get registry summary and all models."""
+    summary = registry.summary()
+    models = []
+    for asset_type in registry.list_asset_types():
+        asset = registry.get_asset(asset_type)
+        if asset:
+            for variant, model in asset.variants.items():
+                models.append({
+                    "asset_type": asset_type,
+                    "variant": variant,
+                    "model": model.model,
+                    "type": model.type,
+                    "license": model.license,
+                    "hardware": model.hardware,
+                    "status": model.status,
+                    "free": model.is_free,
+                    "commercial_safe": model.is_commercial_safe,
+                    "space_id": model.space_id,
+                })
+    return {"summary": summary, "models": models}
+
+
+@app.api()
+def get_route(asset_type: str, variant: str = "primary") -> Dict[str, Any]:
+    """Get routing info for a model."""
+    decision = router.route(asset_type, variant)
+    return decision.to_dict()
+
+
+@app.api()
+def list_pipelines() -> List[Dict[str, Any]]:
+    """List available pipeline definitions."""
+    pipes_dir = Path(__file__).parent / "pipelines"
+    result = []
+    for path in sorted(pipes_dir.glob("*.yaml")):
+        try:
+            with open(path) as f:
+                data = yaml.safe_load(f)
+            result.append({
+                "name": path.stem,
+                "description": data.get("description", ""),
+                "version": data.get("version", ""),
+                "steps": len(data.get("steps", [])),
+                "defaults": data.get("defaults", {}),
+            })
+        except Exception:
+            pass
+    return result
+
+
+@app.api()
+def get_pipeline(name: str) -> Dict[str, Any]:
+    """Get full pipeline definition."""
+    pipes_dir = Path(__file__).parent / "pipelines"
+    for path in pipes_dir.glob(f"{name}.yaml"):
+        with open(path) as f:
+            return yaml.safe_load(f)
+    return {"error": f"Pipeline not found: {name}"}
+
+
+@app.api()
+def format_prompt(asset_type: str, user_prompt: str, model_family: str = "") -> Dict[str, str]:
+    """Format a prompt using game-specific templates."""
+    template = get_template_for_asset(asset_type, model_family)
+    if template:
+        return template.format(user_prompt)
+    return {"prompt": user_prompt, "negative_prompt": ""}
+
+
+@app.api()
+def format_npc(text: str, emotion: str = "neutral", speaker: str = "") -> Dict[str, str]:
+    """Format NPC dialogue with emotion."""
+    return {"formatted": format_npc_dialogue(text, emotion, speaker)}
+
+
+@app.api()
+def list_templates_api() -> List[Dict[str, str]]:
+    """List all prompt templates."""
+    templates = list_templates()
+    return [
+        {
+            "name": t.name,
+            "asset_type": t.asset_type,
+            "model_family": t.model_family,
+            "examples": t.example_prompts[:3],
+        }
+        for t in templates
+    ]
+
+
+# ============================================================================
+# GPU-accelerated generation endpoints (ZeroGPU)
+# ============================================================================
+
+@spaces.GPU(duration=60)
+def _generate_image(prompt: str, negative_prompt: str = "", steps: int = 4) -> str:
+    """Generate an image using the HF Inference API."""
+    from huggingface_hub import InferenceClient
+    import tempfile
+
+    token = os.environ.get("HF_TOKEN", "")
+    if not token:
+        for tp in [os.path.expanduser("~/.cache/huggingface/token"),
+                    os.path.expanduser("~/.huggingface/token")]:
+            if os.path.isfile(tp):
+                token = open(tp).read().strip()
+                break
+
+    client = InferenceClient(token=token, provider="hf-inference")
+    image = client.text_to_image(
+        prompt,
+        model="black-forest-labs/FLUX.1-schnell",
+        negative_prompt=negative_prompt or None,
+        num_inference_steps=steps,
+    )
+
+    out_path = str(STORAGE_DIR / f"img_{hash(prompt) % 100000}.png")
+    image.save(out_path)
+    return out_path
+
+
+@app.api()
+def generate_image(prompt: str, negative_prompt: str = "", steps: int = 4) -> FileData:
+    """Generate an image from text. Returns PNG."""
+    out_path = _generate_image(prompt, negative_prompt, steps)
+    return FileData(path=out_path)
+
+
+@spaces.GPU(duration=120)
+def _generate_3d(image_path: str) -> str:
+    """Generate 3D mesh from image via TRELLIS.2 Space."""
+    from gradio_client import Client
+    import shutil
+
+    client = Client("microsoft/TRELLIS.2")
+    result = client.predict(image_path, api_name="/generate")
+
+    # Result is typically a file path or tuple
+    if isinstance(result, tuple):
+        mesh_path = result[0]
+    elif isinstance(result, str) and os.path.isfile(result):
+        mesh_path = result
+    else:
+        return None
+
+    out_path = str(STORAGE_DIR / f"mesh_{hash(image_path) % 100000}.glb")
+    if isinstance(mesh_path, str) and os.path.isfile(mesh_path):
+        shutil.copy2(mesh_path, out_path)
+        return out_path
+    return None
+
+
+@app.api()
+def generate_3d(image_path: FileData) -> Optional[FileData]:
+    """Generate 3D mesh from an image. Returns GLB."""
+    result = _generate_3d(image_path["path"])
+    if result:
+        return FileData(path=result)
+    return None
+
+
+@spaces.GPU(duration=60)
+def _generate_voice(text: str) -> str:
+    """Generate voice via MeloTTS."""
+    from gradio_client import Client
+    import shutil
+
+    client = Client("mrfakename/MeloTTS")
+    result = client.predict(text, api_name="/synthesize")
+
+    if isinstance(result, tuple):
+        audio_path = result[0]
+    elif isinstance(result, str) and os.path.isfile(result):
+        audio_path = result
+    else:
+        return None
+
+    out_path = str(STORAGE_DIR / f"voice_{hash(text) % 100000}.wav")
+    if os.path.isfile(audio_path):
+        shutil.copy2(audio_path, out_path)
+        return out_path
+    return None
+
+
+@app.api()
+def generate_voice(text: str) -> Optional[FileData]:
+    """Generate NPC voice from text. Returns WAV."""
+    result = _generate_voice(text)
+    if result:
+        return FileData(path=result)
+    return None
+
+
+@spaces.GPU(duration=120)
+def _generate_video(prompt: str) -> str:
+    """Generate video via LTX-2 Turbo."""
+    from gradio_client import Client
+    import shutil
+
+    client = Client("alexnasa/ltx-2-TURBO")
+    result = client.predict(prompt, api_name="/generate")
+
+    if isinstance(result, tuple):
+        video_path = result[0]
+    elif isinstance(result, str) and os.path.isfile(result):
+        video_path = result
+    else:
+        return None
+
+    out_path = str(STORAGE_DIR / f"video_{hash(prompt) % 100000}.mp4")
+    if os.path.isfile(video_path):
+        shutil.copy2(video_path, out_path)
+        return out_path
+    return None
+
+
+@app.api()
+def generate_video(prompt: str) -> Optional[FileData]:
+    """Generate a video from text. Returns MP4."""
+    result = _generate_video(prompt)
+    if result:
+        return FileData(path=result)
+    return None
+
+
+@spaces.GPU(duration=120)
+def _generate_music(prompt: str) -> str:
+    """Generate music via ACE-Step."""
+    from gradio_client import Client
+    import shutil
+
+    client = Client("victor/ace-step-jam")
+    result = client.predict(prompt, api_name="/predict")
+
+    if isinstance(result, tuple):
+        audio_path = result[0]
+    elif isinstance(result, str) and os.path.isfile(result):
+        audio_path = result
+    else:
+        return None
+
+    out_path = str(STORAGE_DIR / f"music_{hash(prompt) % 100000}.wav")
+    if os.path.isfile(audio_path):
+        shutil.copy2(audio_path, out_path)
+        return out_path
+    return None
+
+
+@app.api()
+def generate_music(prompt: str) -> Optional[FileData]:
+    """Generate music from text. Returns WAV."""
+    result = _generate_music(prompt)
+    if result:
+        return FileData(path=result)
+    return None
+
+
+@spaces.GPU(duration=60)
+def _generate_sfx(prompt: str) -> str:
+    """Generate sound effect via TangoFlux."""
+    from gradio_client import Client
+    import shutil
+
+    client = Client("declare-lab/TangoFlux")
+    result = client.predict(prompt, api_name="/predict")
+
+    if isinstance(result, tuple):
+        audio_path = result[0]
+    elif isinstance(result, str) and os.path.isfile(result):
+        audio_path = result
+    else:
+        return None
+
+    out_path = str(STORAGE_DIR / f"sfx_{hash(prompt) % 100000}.wav")
+    if os.path.isfile(audio_path):
+        shutil.copy2(audio_path, out_path)
+        return out_path
+    return None
+
+
+@app.api()
+def generate_sfx(prompt: str) -> Optional[FileData]:
+    """Generate sound effect from text. Returns WAV."""
+    result = _generate_sfx(prompt)
+    if result:
+        return FileData(path=result)
+    return None
+
+
+# ============================================================================
+# Asset management
+# ============================================================================
+
+@app.api()
+def list_assets(folder: str = "") -> List[Dict[str, Any]]:
+    """List generated assets."""
+    search_dir = STORAGE_DIR / folder if folder else STORAGE_DIR
+    if not search_dir.exists():
+        return []
+    assets = []
+    for f in sorted(search_dir.rglob("*")):
+        if f.is_file():
+            stat = f.stat()
+            assets.append({
+                "name": f.name,
+                "path": str(f),
+                "size": stat.st_size,
+                "format": f.suffix.lower(),
+                "modified": stat.st_mtime,
+            })
+    return assets
+
+
+@app.api()
+def delete_asset(path: str) -> Dict[str, bool]:
+    """Delete a generated asset."""
+    p = Path(path)
+    if p.exists() and p.is_file() and p.is_relative_to(STORAGE_DIR):
+        p.unlink()
+        return {"deleted": True}
+    return {"deleted": False}
+
+
+@app.api()
+def validate_asset_api(path: str, checks: str = "file_exists,non_empty") -> Dict[str, Any]:
+    """Validate an asset file."""
+    check_list = [c.strip() for c in checks.split(",")]
+    return validate_asset(path, check_list)
+
+
+@app.api()
+def convert_asset_api(input_path: str, target_format: str, engine: str = "") -> Optional[FileData]:
+    """Convert an asset format."""
+    eng = engine if engine else None
+    result = convert_asset(input_path, target_format, engine=eng)
+    if result:
+        return FileData(path=result)
+    return None
+
+
+# ============================================================================
+# MCP Tool Registration (for HF Spaces MCP support)
+# ============================================================================
+
+@app.mcp.tool()
+def gameforge_generate(
+    asset_type: str,
+    prompt: str,
+) -> str:
+    """Generate a game asset (image, 3D, voice, music, video, SFX).
+
+    Args:
+        asset_type: Type of asset - "image", "3d", "voice", "music", "video", "sfx"
+        prompt: Description of the asset to generate
+    """
+    generators = {
+        "image": _generate_image,
+        "3d": lambda p: _generate_3d(p),  # Takes image path, would need intermediate
+        "voice": _generate_voice,
+        "music": _generate_music,
+        "video": _generate_video,
+        "sfx": _generate_sfx,
+    }
+    fn = generators.get(asset_type)
+    if fn:
+        result = fn(prompt)
+        return result or "Generation failed"
+    return f"Unknown asset type: {asset_type}"
+
+
+@app.mcp.tool()
+def gameforge_list_models() -> str:
+    """List all available AI models for game asset generation."""
+    models = []
+    for asset_type in registry.list_asset_types():
+        asset = registry.get_asset(asset_type)
+        if asset:
+            for variant, model in asset.variants.items():
+                free = "FREE" if model.is_free else "PAID"
+                models.append(f"{asset_type}/{variant}: {model.model} [{free}]")
+    return "\n".join(models)
+
+
+# ============================================================================
+# Launch
+# ============================================================================
+
+if __name__ == "__main__":
+    app.launch(show_error=True)

gameforge/config/__init__.py

@@ -0,0 +1 @@
+# GameForge Config

gameforge/config/prompts.py

@@ -0,0 +1,313 @@
+"""
+Prompt Templates - Game-specific prompt engineering for each model and asset type.
+Provides optimized prompts that extract the best quality from each model.
+"""
+
+from __future__ import annotations
+from typing import Dict, Optional, Any, List
+from dataclasses import dataclass, field
+
+
+@dataclass
+class PromptTemplate:
+    """A prompt template for a specific asset type and model."""
+    name: str
+    asset_type: str
+    model_family: str  # e.g. "flux", "tts", "3d", "video"
+    system_prefix: str = ""
+    style_suffix: str = ""
+    negative_prompt: str = ""
+    quality_keywords: List[str] = field(default_factory=list)
+    example_prompts: List[str] = field(default_factory=list)
+
+    def format(self, user_prompt: str, **kwargs) -> Dict[str, str]:
+        """Format the template with a user prompt."""
+        parts = []
+        if self.system_prefix:
+            parts.append(self.system_prefix.format(**kwargs))
+        parts.append(user_prompt)
+        if self.style_suffix:
+            parts.append(self.style_suffix.format(**kwargs))
+
+        return {
+            "prompt": ", ".join(parts),
+            "negative_prompt": self.negative_prompt,
+        }
+
+
+# ============================================================================
+# IMAGE TEMPLATES
+# ============================================================================
+
+CHARACTER_FLUX = PromptTemplate(
+    name="character_flux",
+    asset_type="images",
+    model_family="flux",
+    system_prefix=(
+        "game character concept art, full body, T-pose, clean studio background, "
+        "highly detailed, professional game asset"
+    ),
+    style_suffix="4k, sharp focus, studio lighting",
+    negative_prompt="blurry, low quality, watermark, text, signature, cropped, deformed",
+    quality_keywords=["detailed", "sharp", "professional", "studio"],
+    example_prompts=[
+        "fantasy knight in silver armor with a glowing sword",
+        "cyberpunk female hacker with neon implants",
+        "forest elf archer in green leather armor",
+    ],
+)
+
+PROP_FLUX = PromptTemplate(
+    name="prop_flux",
+    asset_type="images",
+    model_family="flux",
+    system_prefix=(
+        "game prop, single object, clean gray background, PBR-ready, "
+        "studio lighting, game asset"
+    ),
+    style_suffix="high detail, sharp focus, turntable view",
+    negative_prompt="blurry, multiple objects, text, watermark, background clutter",
+    quality_keywords=["PBR", "clean", "detailed", "turntable"],
+    example_prompts=[
+        "enchanted longsword with blue runes glowing along the blade",
+        "wooden treasure chest with iron bands and a golden lock",
+        "health potion in a red glass flask with cork stopper",
+    ],
+)
+
+UI_ICON_FLUX = PromptTemplate(
+    name="ui_icon_flux",
+    asset_type="images",
+    model_family="flux",
+    system_prefix=(
+        "game UI icon, flat design, clean edges, transparent background, "
+        "readable at small size, game interface element"
+    ),
+    style_suffix="vector style, sharp edges, 128x128",
+    negative_prompt="photo, realistic, 3d render, text, blurry, gradient mess",
+    quality_keywords=["flat", "clean", "icon", "readable"],
+    example_prompts=[
+        "health potion icon, red flask with bubbles",
+        "shield icon, medieval steel buckler",
+        "map icon, rolled parchment with ribbon",
+    ],
+)
+
+SKYBOX_FLUX = PromptTemplate(
+    name="skybox_flux",
+    asset_type="images",
+    model_family="flux",
+    system_prefix="game skybox, 360 degree equirectangular panorama, seamless",
+    style_suffix="atmospheric, high resolution, game environment",
+    negative_prompt="text, watermark, border, frame, seams, objects in foreground",
+    quality_keywords=["panorama", "seamless", "atmospheric"],
+    example_prompts=[
+        "dark fantasy night sky with two moons and purple aurora",
+        "sunset over a tropical ocean with scattered clouds",
+        "post-apocalyptic orange haze sky with distant city ruins",
+    ],
+)
+
+TEXTURE_FLUX = PromptTemplate(
+    name="texture_flux",
+    asset_type="images",
+    model_family="flux",
+    system_prefix="seamless tileable texture, top-down view, PBR diffuse map",
+    style_suffix="high resolution, no seams, game texture",
+    negative_prompt="seams, borders, edges, frame, text, perspective, 3d objects",
+    quality_keywords=["seamless", "tileable", "PBR"],
+    example_prompts=[
+        "mossy cobblestone path with small plants growing between stones",
+        "rusty medieval iron plate with rivets and scratches",
+        "oak wood grain planks, warm brown tones",
+    ],
+)
+
+# ============================================================================
+# VIDEO TEMPLATES
+# ============================================================================
+
+CUTSCENE_LTX = PromptTemplate(
+    name="cutscene_ltx",
+    asset_type="video",
+    model_family="ltx",
+    system_prefix="cinematic game cutscene",
+    style_suffix="smooth camera movement, game engine quality, 24fps",
+    negative_prompt="static, still, blurry, watermark, text",
+    quality_keywords=["cinematic", "smooth", "dynamic"],
+    example_prompts=[
+        "A dragon lands on a castle tower at sunset, camera slowly circles",
+        "Hero draws sword and charges across a battlefield, tracking shot",
+        "Mystical portal opens in a dark cave, camera pushes in",
+    ],
+)
+
+CUTSCENE_WAN = PromptTemplate(
+    name="cutscene_wan",
+    asset_type="video",
+    model_family="wan",
+    system_prefix="high quality cinematic video",
+    style_suffix="smooth motion, detailed, realistic lighting",
+    negative_prompt="static, blurry, artifacts, low quality",
+    quality_keywords=["cinematic", "detailed", "smooth"],
+    example_prompts=[
+        "A knight walks through a burning village at night",
+        "Camera flies through an enchanted forest at golden hour",
+    ],
+)
+
+# ============================================================================
+# 3D TEMPLATES
+# ============================================================================
+
+MESH_TRELLIS = PromptTemplate(
+    name="mesh_trellis",
+    asset_type="3d",
+    model_family="trellis",
+    system_prefix="",
+    style_suffix="",
+    negative_prompt="",
+    quality_keywords=["clean", "watertight", "manifold"],
+    example_prompts=[],  # TRELLIS takes image input, not text
+)
+
+MESH_HUNYUAN = PromptTemplate(
+    name="mesh_hunyuan",
+    asset_type="3d",
+    model_family="hunyuan",
+    system_prefix="high quality 3D model",
+    style_suffix="detailed geometry, clean topology, game-ready",
+    negative_prompt="low poly, broken mesh, artifacts",
+    quality_keywords=["detailed", "clean", "game-ready"],
+    example_prompts=[
+        "fantasy sword with ornate crossguard",
+        "wooden barrel with metal bands",
+    ],
+)
+
+# ============================================================================
+# VOICE / TTS TEMPLATES
+# ============================================================================
+
+NPC_VOICE_MeloTTS = PromptTemplate(
+    name="npc_voice_melotts",
+    asset_type="voice",
+    model_family="melotts",
+    system_prefix="",
+    style_suffix="",
+    negative_prompt="",
+    quality_keywords=["clear", "natural", "expressive"],
+    example_prompts=[
+        "Welcome, traveler. What brings you to our humble village?",
+        "The dungeon lies beyond the northern gate. Be careful.",
+        "I have wares if you have coin, friend.",
+    ],
+)
+
+# Pre-format NPC dialogue with emotion markers
+NPC_EMOTIONS = {
+    "neutral": "{dialogue}",
+    "friendly": "*cheerful tone* {dialogue}",
+    "threatening": "*menacing whisper* {dialogue}",
+    "mysterious": "*cryptic tone* {dialogue}",
+    "excited": "*enthusiastic* {dialogue}",
+    "sad": "*sorrowful* {dialogue}",
+}
+
+# ============================================================================
+# MUSIC TEMPLATES
+# ============================================================================
+
+BGM_ACE = PromptTemplate(
+    name="bgm_ace",
+    asset_type="music",
+    model_family="ace_step",
+    system_prefix="game background music",
+    style_suffix="loop-friendly, game soundtrack quality",
+    negative_prompt="vocals, speech, silence, abrupt ending",
+    quality_keywords=["loop", "atmospheric", "immersive"],
+    example_prompts=[
+        "epic orchestral battle theme, 120 bpm, horns and strings",
+        "ambient exploration music, gentle piano and soft strings",
+        "tense dungeon atmosphere, low drones and distant echoes",
+        "victorious fanfare, brass and timpani, triumphant",
+    ],
+)
+
+SFX_TANGO = PromptTemplate(
+    name="sfx_tango",
+    asset_type="sfx",
+    model_family="tangoflux",
+    system_prefix="game sound effect",
+    style_suffix="clean, isolated, game audio quality",
+    negative_prompt="music, speech, background noise",
+    quality_keywords=["clean", "isolated", "crisp"],
+    example_prompts=[
+        "sword slash whoosh with metallic ring",
+        "door creaking open slowly in a dungeon",
+        "health potion pickup, glass clink and magical sparkle",
+        "footsteps on gravel path, steady walking pace",
+        "fireball cast, rushing flame burst with explosion",
+    ],
+)
+
+# ============================================================================
+# TEMPLATE REGISTRY
+# ============================================================================
+
+TEMPLATES: Dict[str, PromptTemplate] = {
+    "character_flux": CHARACTER_FLUX,
+    "prop_flux": PROP_FLUX,
+    "ui_icon_flux": UI_ICON_FLUX,
+    "skybox_flux": SKYBOX_FLUX,
+    "texture_flux": TEXTURE_FLUX,
+    "cutscene_ltx": CUTSCENE_LTX,
+    "cutscene_wan": CUTSCENE_WAN,
+    "mesh_trellis": MESH_TRELLIS,
+    "mesh_hunyuan": MESH_HUNYUAN,
+    "npc_voice_melotts": NPC_VOICE_MeloTTS,
+    "bgm_ace": BGM_ACE,
+    "sfx_tango": SFX_TANGO,
+}
+
+
+def get_template(name: str) -> Optional[PromptTemplate]:
+    """Get a prompt template by name."""
+    return TEMPLATES.get(name)
+
+
+def list_templates(asset_type: Optional[str] = None) -> List[PromptTemplate]:
+    """List templates, optionally filtered by asset type."""
+    if asset_type:
+        return [t for t in TEMPLATES.values() if t.asset_type == asset_type]
+    return list(TEMPLATES.values())
+
+
+def get_template_for_asset(
+    asset_type: str,
+    model_family: str = "",
+) -> Optional[PromptTemplate]:
+    """Get the best template for an asset type and model family."""
+    # Try exact match first
+    if model_family:
+        for t in TEMPLATES.values():
+            if t.asset_type == asset_type and t.model_family == model_family:
+                return t
+    # Fall back to asset type match
+    for t in TEMPLATES.values():
+        if t.asset_type == asset_type:
+            return t
+    return None
+
+
+def format_npc_dialogue(
+    dialogue: str,
+    emotion: str = "neutral",
+    speaker: str = "",
+) -> str:
+    """Format NPC dialogue with emotion and speaker context."""
+    template = NPC_EMOTIONS.get(emotion, NPC_EMOTIONS["neutral"])
+    formatted = template.format(dialogue=dialogue)
+    if speaker:
+        formatted = f"[{speaker}] {formatted}"
+    return formatted

gameforge/config/registry.yaml

@@ -0,0 +1,401 @@
+# GameForge Model Registry
+# ========================
+# Maps asset types to "best-in-class" free/commercially viable models.
+# Update this file to swap models without touching code.
+#
+# Each entry has:
+#   model: HF model ID or Space repo_id
+#   type: "inference" (free API), "space" (Gradio Space), "pipeline" (local transformers)
+#   license: Commercial license type
+#   hardware: Required hardware tier
+#   params: Default parameters for generation
+#
+# STATUS KEY:
+#   production = verified working, commercial-safe
+#   beta = working but may have rough edges
+#   alpha = early stage, needs testing
+
+version: "1.0.0"
+updated: "2026-04-20"
+
+# ============================================================
+# IMAGES - 2D concept art, sprites, textures, UI elements
+# ============================================================
+images:
+  # Primary: Fast, Apache 2.0, great quality
+  primary:
+    model: "black-forest-labs/FLUX.1-schnell"
+    type: inference
+    license: apache-2.0
+    status: production
+    hardware: free
+    params:
+      num_inference_steps: 4
+      guidance_scale: 0.0
+
+  # Alternative: Higher quality SD 3.5
+  alternative:
+    model: "stabilityai/stable-diffusion-3.5-large"
+    type: inference
+    license: stability-community
+    status: production
+    hardware: free
+    params:
+      num_inference_steps: 28
+      guidance_scale: 5.0
+
+  # Texture specialist: Seamless tile generation
+  texture:
+    model: "black-forest-labs/FLUX.1-schnell"
+    type: inference
+    license: apache-2.0
+    status: production
+    hardware: free
+    params:
+      num_inference_steps: 4
+      prompt_prefix: "seamless tileable texture, top-down view, "
+      negative_prompt: "seams, borders, edges, frame"
+
+# ============================================================
+# VIDEO - Cutscenes, effects, animated sequences
+# ============================================================
+video:
+  # Primary: LTX 2.3 Distilled - cinematic with audio, ZeroGPU (free!)
+  primary:
+    model: "Lightricks/LTX-2.3"
+    type: space
+    space_id: "Lightricks/LTX-2-3"
+    license: apache-2.0
+    status: production
+    hardware: zerogpu
+    params:
+      num_frames: 121
+      fps: 24
+      api_name: "/generate"
+
+  # Fast: LTX-2 Turbo - rapid iteration, ZeroGPU
+  fast:
+    model: "Lightricks/LTX-2-Turbo"
+    type: space
+    space_id: "alexnasa/ltx-2-TURBO"
+    license: apache-2.0
+    status: production
+    hardware: zerogpu
+    params:
+      num_frames: 49
+      fps: 24
+      api_name: "/generate"
+
+  # Cinematic: Wan 2.2 14B - highest quality, ZeroGPU
+  cinematic:
+    model: "Wan-AI/Wan2.2-14B"
+    type: space
+    space_id: "r3gm/wan2-2-fp8da-aoti-preview"
+    license: apache-2.0
+    status: production
+    hardware: zerogpu
+    params:
+      num_frames: 81
+      fps: 24
+      api_name: "/predict"
+
+  # Animation: Wan 2.2 Animate - video editing, ZeroGPU
+  animate:
+    model: "Wan-AI/Wan2.2-Animate"
+    type: space
+    space_id: "alexnasa/Wan2.2-Animate-ZEROGPU"
+    license: apache-2.0
+    status: production
+    hardware: zerogpu
+    params:
+      api_name: "/predict"
+
+# ============================================================
+# 3D ASSETS - Characters, props, environment objects
+# ============================================================
+threed:
+  # Primary: TRELLIS.2 - high-fidelity 3D, ZeroGPU (free!)
+  primary:
+    model: "microsoft/TRELLIS.2"
+    type: space
+    space_id: "microsoft/TRELLIS.2"
+    license: mit
+    status: production
+    hardware: zerogpu
+    params:
+      ss_guidance_strength: 7.5
+      slat_guidance_strength: 3
+      api_name: "/generate"
+
+  # Fast: TripoSG - image to textured 3D, ZeroGPU
+  fast:
+    model: "VAST-AI/TripoSG"
+    type: space
+    space_id: "VAST-AI/TripoSG"
+    license: mit
+    status: production
+    hardware: zerogpu
+    params:
+      api_name: "/generate"
+
+  # Text-to-3D: Hunyuan3D-2.0, ZeroGPU
+  text_to_3d:
+    model: "tencent/Hunyuan3D-2"
+    type: space
+    space_id: "tencent/Hunyuan3D-2"
+    license: tencent-hunyuan
+    status: production
+    hardware: zerogpu
+    params:
+      mode: "text"
+      steps: 50
+      api_name: "/generation_with texture"
+
+  # Mesh: CraftsMan3D - high-fidelity mesh generation, ZeroGPU
+  mesh:
+    model: "wyysf/CraftsMan3D"
+    type: space
+    space_id: "wyysf/CraftsMan3D"
+    license: apache-2.0
+    status: production
+    hardware: zerogpu
+    params:
+      api_name: "/generate"
+
+  # World/Environment generation, ZeroGPU
+  world:
+    model: "tencent/HY-World-2.0"
+    type: space
+    space_id: "prithivMLmods/HY-World-2.0-Demo"
+    license: tencent-hunyuan
+    status: alpha
+    hardware: zerogpu
+    params:
+      mode: "text_to_world"
+
+# ============================================================
+# AUDIO - NPC voices, voice cloning
+# ============================================================
+voice:
+  # Primary: MeloTTS - MIT, simple text-to-speech, no reference needed
+  primary:
+    model: "myshell-ai/MeloTTS"
+    type: space
+    space_id: "mrfakename/MeloTTS"
+    license: mit
+    status: production
+    hardware: cpu-basic
+    params:
+      speed: 1.0
+      language: "EN"
+      api_name: "/synthesize"
+
+  # Voice cloning: F5-TTS - needs reference audio
+  clone:
+    model: "SWivid/F5-TTS"
+    type: space
+    space_id: "mrfakename/E2-F5-TTS"
+    license: mit
+    status: production
+    hardware: cpu-basic
+    params:
+      clone_mode: true
+      ref_audio_required: true
+      api_name: "/predict"
+
+  # Alternative: MeloTTS (same as primary, alias)
+  alternative:
+    model: "myshell-ai/MeloTTS"
+    type: space
+    space_id: "mrfakename/MeloTTS"
+    license: mit
+    status: production
+    hardware: cpu-basic
+    params:
+      speed: 1.0
+      language: "JP"
+      api_name: "/synthesize"
+
+# ============================================================
+# MUSIC - Background scores, themes, ambient
+# ============================================================
+music:
+  # Primary: ACE-Step - full music generation, ZeroGPU (free!)
+  primary:
+    model: "ACE-Step/ACE-Step"
+    type: space
+    space_id: "victor/ace-step-jam"
+    license: apache-2.0
+    status: production
+    hardware: zerogpu
+    params:
+      duration: 60
+      api_name: "/predict"
+
+  # Fast: DiffRhythm - blazing fast song generation, ZeroGPU
+  fast:
+    model: "ASLP-lab/DiffRhythm"
+    type: space
+    space_id: "ASLP-lab/DiffRhythm"
+    license: apache-2.0
+    status: production
+    hardware: zerogpu
+    params:
+      api_name: "/predict"
+
+  # Alternative: YuE music generator, ZeroGPU
+  alternative:
+    model: "YuE-music"
+    type: space
+    space_id: "innova-ai/YuE-music-generator-demo"
+    license: apache-2.0
+    status: production
+    hardware: zerogpu
+    params:
+      api_name: "/predict"
+
+  # Local fallback: MusicGen via transformers pipeline
+  local:
+    model: "facebook/musicgen-medium"
+    type: pipeline
+    license: cc-by-nc-4.0
+    status: production
+    hardware: local
+    params:
+      max_new_tokens: 256
+
+# ============================================================
+# SOUND EFFECTS
+# ============================================================
+sfx:
+  # Primary: TangoFlux - text to audio/SFX, ZeroGPU (free!)
+  primary:
+    model: "declare-lab/TangoFlux"
+    type: space
+    space_id: "declare-lab/TangoFlux"
+    license: apache-2.0
+    status: production
+    hardware: zerogpu
+    params:
+      api_name: "/predict"
+
+  # Alternative: Stable Audio Open, ZeroGPU
+  alternative:
+    model: "stabilityai/stable-audio-open-1.0"
+    type: space
+    space_id: "ameerazam08/stableaudio-open-1.0"
+    license: stability-community
+    status: production
+    hardware: zerogpu
+    params:
+      seconds_total: 10
+      api_name: "/predict"
+
+  # Local fallback
+  local:
+    model: "facebook/musicgen-small"
+    type: pipeline
+    license: cc-by-nc-4.0
+    status: production
+    hardware: local
+    params:
+      prompt_prefix: "SFX: "
+      max_new_tokens: 128
+
+# ============================================================
+# ANIMATION / RIGGING
+# ============================================================
+animation:
+  # Primary: AniGen - animatable 3D assets, ZeroGPU
+  primary:
+    model: "ani-gen"
+    type: space
+    space_id: "AniGen/AniGen"
+    license: unknown
+    status: alpha
+    hardware: zerogpu
+    params:
+      steps: 50
+
+  # Character animation via Wan 2.2 Animate, ZeroGPU
+  animate:
+    model: "Wan-AI/Wan2.2-Animate"
+    type: space
+    space_id: "alexnasa/Wan2.2-Animate-ZEROGPU"
+    license: apache-2.0
+    status: production
+    hardware: zerogpu
+    params:
+      api_name: "/predict"
+
+  # Auto-rig via Mixamo (external API)
+  rigging:
+    model: "mixamo"
+    type: external
+    license: adobe-free
+    status: production
+    hardware: cloud
+    params:
+      auto_detect_face: true
+      skeleton_type: "mixamo_game"
+
+# ============================================================
+# ENVIRONMENT / SKYBOX
+# ============================================================
+environment:
+  # 360 skybox generation
+  skybox:
+    model: "black-forest-labs/FLUX.1-schnell"
+    type: inference
+    license: apache-2.0
+    status: production
+    hardware: free
+    params:
+      prompt_suffix: ", 360 degree equirectangular panorama, seamless"
+      width: 2048
+      height: 1024
+
+  # 3D world generation, ZeroGPU
+  world:
+    model: "tencent/HY-World-2.0"
+    type: space
+    space_id: "prithivMLmods/HY-World-2.0-Demo"
+    license: tencent-hunyuan
+    status: alpha
+    hardware: zerogpu
+    params:
+      resolution: 512
+
+# ============================================================
+# UTILITY MODELS (used by orchestrator)
+# ============================================================
+utility:
+  # Image captioning for pipeline chaining
+  captioner:
+    model: "Salesforce/blip-image-captioning-large"
+    type: pipeline
+    license: bsd-3
+    status: production
+    hardware: local
+    params: {}
+
+  # Text enhancement for prompts
+  prompt_enhancer:
+    model: "Qwen/Qwen2.5-72B-Instruct"
+    type: inference
+    license: apache-2.0
+    status: production
+    hardware: free
+    params:
+      max_tokens: 512
+      temperature: 0.8
+
+  # Image upscaler
+  upscaler:
+    model: "stabilityai/stable-diffusion-x4-upscaler"
+    type: inference
+    license: stability-community
+    status: production
+    hardware: free
+    params:
+      num_inference_steps: 20

gameforge/config/registry_loader.py

@@ -0,0 +1,165 @@
+"""
+Registry Loader - Loads and validates the model registry YAML.
+Provides lookup by asset type and variant.
+"""
+
+from __future__ import annotations
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass, field
+import yaml
+
+
+REGISTRY_PATH = Path(__file__).parent.parent / "config" / "registry.yaml"
+
+
+@dataclass
+class ModelEntry:
+    """A single model entry from the registry."""
+    model: str
+    type: str  # inference, space, pipeline, external
+    license: str
+    status: str
+    hardware: str
+    params: Dict[str, Any] = field(default_factory=dict)
+    space_id: Optional[str] = None
+
+    @property
+    def is_free(self) -> bool:
+        return self.hardware in ("free", "local", "cpu-basic", "zerogpu")
+
+    @property
+    def is_commercial_safe(self) -> bool:
+        safe_licenses = {"apache-2.0", "mit", "bsd-3", "stability-community", "adobe-free"}
+        return self.license.lower() in safe_licenses
+
+
+@dataclass
+class AssetConfig:
+    """Configuration for an asset type (images, video, 3d, etc.)."""
+    name: str
+    variants: Dict[str, ModelEntry] = field(default_factory=dict)
+
+    def get(self, variant: str = "primary") -> Optional[ModelEntry]:
+        return self.variants.get(variant)
+
+    def list_variants(self) -> List[str]:
+        return list(self.variants.keys())
+
+
+class Registry:
+    """Loads and queries the GameForge model registry."""
+
+    def __init__(self, path: Optional[str] = None):
+        self.path = Path(path) if path else REGISTRY_PATH
+        self._data: Dict[str, Any] = {}
+        self._assets: Dict[str, AssetConfig] = {}
+        self._utility: Dict[str, ModelEntry] = {}
+        self.load()
+
+    def load(self) -> None:
+        """Load or reload the registry from YAML."""
+        with open(self.path) as f:
+            self._data = yaml.safe_load(f)
+
+        # Parse asset types (skip version, updated, utility)
+        skip = {"version", "updated", "utility"}
+        for key, value in self._data.items():
+            if key in skip or not isinstance(value, dict):
+                continue
+            variants = {}
+            for var_name, var_data in value.items():
+                if isinstance(var_data, dict) and "model" in var_data:
+                    variants[var_name] = ModelEntry(
+                        model=var_data.get("model", ""),
+                        type=var_data.get("type", "inference"),
+                        license=var_data.get("license", "unknown"),
+                        status=var_data.get("status", "alpha"),
+                        hardware=var_data.get("hardware", "free"),
+                        params=var_data.get("params", {}),
+                        space_id=var_data.get("space_id"),
+                    )
+            if variants:
+                self._assets[key] = AssetConfig(name=key, variants=variants)
+
+        # Parse utility models
+        util_data = self._data.get("utility", {})
+        for name, data in util_data.items():
+            if isinstance(data, dict) and "model" in data:
+                self._utility[name] = ModelEntry(
+                    model=data.get("model", ""),
+                    type=data.get("type", "inference"),
+                    license=data.get("license", "unknown"),
+                    status=data.get("status", "alpha"),
+                    hardware=data.get("hardware", "free"),
+                    params=data.get("params", {}),
+                )
+
+    @property
+    def version(self) -> str:
+        return self._data.get("version", "unknown")
+
+    @property
+    def updated(self) -> str:
+        return self._data.get("updated", "unknown")
+
+    def list_asset_types(self) -> List[str]:
+        """List all registered asset types."""
+        return list(self._assets.keys())
+
+    def get_asset(self, asset_type: str) -> Optional[AssetConfig]:
+        """Get the full config for an asset type."""
+        return self._assets.get(asset_type)
+
+    def get_model(self, asset_type: str, variant: str = "primary") -> Optional[ModelEntry]:
+        """Get a specific model entry."""
+        asset = self._assets.get(asset_type)
+        if asset:
+            return asset.get(variant)
+        return None
+
+    def get_utility(self, name: str) -> Optional[ModelEntry]:
+        """Get a utility model (captioner, prompt_enhancer, etc.)."""
+        return self._utility.get(name)
+
+    def find_commercial_safe(self) -> Dict[str, List[str]]:
+        """Find all commercially safe models grouped by asset type."""
+        result = {}
+        for asset_type, config in self._assets.items():
+            safe = [v for v, m in config.variants.items() if m.is_commercial_safe]
+            if safe:
+                result[asset_type] = safe
+        return result
+
+    def find_free(self) -> Dict[str, List[str]]:
+        """Find all free-tier models grouped by asset type."""
+        result = {}
+        for asset_type, config in self._assets.items():
+            free = [v for v, m in config.variants.items() if m.is_free]
+            if free:
+                result[asset_type] = free
+        return result
+
+    def summary(self) -> Dict[str, Any]:
+        """Get a summary of the registry."""
+        return {
+            "version": self.version,
+            "updated": self.updated,
+            "asset_types": len(self._assets),
+            "total_models": sum(len(a.variants) for a in self._assets.values()),
+            "utility_models": len(self._utility),
+            "commercial_safe": len(self.find_commercial_safe()),
+            "free_tier": len(self.find_free()),
+        }
+
+
+# Singleton
+_registry: Optional[Registry] = None
+
+
+def get_registry(path: Optional[str] = None) -> Registry:
+    """Get the global registry singleton."""
+    global _registry
+    if _registry is None or path:
+        _registry = Registry(path)
+    return _registry

gameforge/engine/__init__.py

@@ -0,0 +1 @@
+# GameForge Engine

gameforge/engine/batch.py

@@ -0,0 +1,178 @@
+"""
+Batch Generator - Generate multiple variants of assets in one call.
+Supports parallel generation and variant management.
+"""
+
+from __future__ import annotations
+import logging
+from pathlib import Path
+from typing import Optional, Dict, Any, List, Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from gameforge.engine.orchestrator import Orchestrator, PipelineRun, get_orchestrator
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class BatchConfig:
+    """Configuration for a batch generation run."""
+    pipeline: str
+    base_prompt: str
+    count: int = 3
+    variant_seeds: List[int] = field(default_factory=list)
+    inputs_overrides: Dict[str, Any] = field(default_factory=dict)
+    output_prefix: str = "variant"
+
+
+@dataclass
+class BatchResult:
+    """Result of a batch generation run."""
+    batch_name: str
+    pipeline: str
+    total: int
+    succeeded: int
+    failed: int
+    runs: List[PipelineRun] = field(default_factory=list)
+    started_at: str = ""
+    completed_at: str = ""
+
+    @property
+    def success_rate(self) -> float:
+        return self.succeeded / self.total if self.total > 0 else 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "batch": self.batch_name,
+            "pipeline": self.pipeline,
+            "total": self.total,
+            "succeeded": self.succeeded,
+            "failed": self.failed,
+            "success_rate": f"{self.success_rate:.0%}",
+            "runs": [r.to_dict() for r in self.runs],
+        }
+
+
+class BatchGenerator:
+    """
+    Generate multiple asset variants using pipelines.
+    """
+
+    def __init__(self, output_dir: Optional[str] = None):
+        self.orchestrator = get_orchestrator(output_dir)
+
+    def generate_variants(
+        self,
+        pipeline: str,
+        base_prompt: str,
+        count: int = 3,
+        variation_fn: Optional[Callable[[str, int], str]] = None,
+        dry_run: bool = False,
+        **kwargs,
+    ) -> BatchResult:
+        """
+        Generate N variants of an asset.
+
+        Args:
+            pipeline: Pipeline name
+            base_prompt: Base prompt to vary
+            count: Number of variants
+            variation_fn: Function to create prompt variations (prompt, index) -> varied_prompt
+            dry_run: Preview without executing
+        """
+        if variation_fn is None:
+            variation_fn = self._default_variation
+
+        batch = BatchResult(
+            batch_name=f"{pipeline}_{datetime.now().strftime('%Y%m%d_%H%M%S')}",
+            pipeline=pipeline,
+            total=count,
+            succeeded=0,
+            failed=0,
+            started_at=datetime.now().isoformat(),
+        )
+
+        for i in range(count):
+            varied_prompt = variation_fn(base_prompt, i)
+            inputs = {"prompt": varied_prompt, **kwargs}
+
+            run = self.orchestrator.run(pipeline, inputs=inputs, dry_run=dry_run)
+            batch.runs.append(run)
+
+            if run.success:
+                batch.succeeded += 1
+            else:
+                batch.failed += 1
+
+            logger.info(f"Variant {i+1}/{count}: {'OK' if run.success else 'FAIL'}")
+
+        batch.completed_at = datetime.now().isoformat()
+        return batch
+
+    def generate_from_themes(
+        self,
+        pipeline: str,
+        themes: List[str],
+        dry_run: bool = False,
+        **kwargs,
+    ) -> BatchResult:
+        """
+        Generate one asset per theme.
+
+        Args:
+            pipeline: Pipeline name
+            themes: List of theme descriptions
+        """
+        batch = BatchResult(
+            batch_name=f"{pipeline}_themes_{datetime.now().strftime('%Y%m%d_%H%M%S')}",
+            pipeline=pipeline,
+            total=len(themes),
+            succeeded=0,
+            failed=0,
+            started_at=datetime.now().isoformat(),
+        )
+
+        for i, theme in enumerate(themes):
+            inputs = {"prompt": theme, **kwargs}
+            run = self.orchestrator.run(pipeline, inputs=inputs, dry_run=dry_run)
+            batch.runs.append(run)
+
+            if run.success:
+                batch.succeeded += 1
+            else:
+                batch.failed += 1
+
+            logger.info(f"Theme {i+1}/{len(themes)}: {'OK' if run.success else 'FAIL'}")
+
+        batch.completed_at = datetime.now().isoformat()
+        return batch
+
+    def generate_asset_pack_batch(
+        self,
+        themes: List[str],
+        dry_run: bool = False,
+    ) -> BatchResult:
+        """
+        Generate multiple complete asset packs, one per theme.
+        """
+        return self.generate_from_themes("asset_pack", themes, dry_run=dry_run)
+
+    @staticmethod
+    def _default_variation(prompt: str, index: int) -> str:
+        """Create default prompt variations."""
+        styles = [
+            "",
+            ", highly detailed",
+            ", stylized, painterly",
+            ", photorealistic",
+            ", pixel art style",
+            ", low poly",
+        ]
+        style = styles[index % len(styles)]
+        return f"{prompt}{style}"
+
+
+def get_batch_generator(output_dir: Optional[str] = None) -> BatchGenerator:
+    """Get a BatchGenerator instance."""
+    return BatchGenerator(output_dir)

gameforge/engine/browser.py

@@ -0,0 +1,166 @@
+"""
+Asset Browser - Browse, search, and manage generated assets.
+"""
+
+from __future__ import annotations
+import os
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+from dataclasses import dataclass
+from datetime import datetime
+
+STORAGE_DIR = Path(__file__).parent.parent / "storage" / "local"
+
+
+@dataclass
+class AssetInfo:
+    """Information about a generated asset."""
+    path: str
+    name: str
+    asset_type: str
+    size_bytes: int
+    created: str
+    format: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "path": self.path,
+            "name": self.name,
+            "asset_type": self.asset_type,
+            "size": self.size_bytes,
+            "size_human": self._human_size(self.size_bytes),
+            "created": self.created,
+            "format": self.format,
+        }
+
+    @staticmethod
+    def _human_size(n: int) -> str:
+        for unit in ["B", "KB", "MB", "GB"]:
+            if n < 1024:
+                return f"{n:.1f} {unit}"
+            n /= 1024
+        return f"{n:.1f} TB"
+
+
+class AssetBrowser:
+    """
+    Browse and manage generated game assets.
+    """
+
+    def __init__(self, storage_dir: Optional[str] = None):
+        self.storage_dir = Path(storage_dir) if storage_dir else STORAGE_DIR
+
+    def list_assets(
+        self,
+        asset_type: Optional[str] = None,
+        format_filter: Optional[str] = None,
+        sort_by: str = "created",
+    ) -> List[AssetInfo]:
+        """
+        List all generated assets.
+
+        Args:
+            asset_type: Filter by subfolder (characters, voices, etc.)
+            format_filter: Filter by file extension (.png, .wav, etc.)
+            sort_by: Sort by "name", "created", or "size"
+        """
+        assets = []
+        search_dir = self.storage_dir / asset_type if asset_type else self.storage_dir
+
+        if not search_dir.exists():
+            return []
+
+        for path in search_dir.rglob("*"):
+            if not path.is_file():
+                continue
+
+            if format_filter and not path.suffix.lower() == format_filter.lower():
+                continue
+
+            stat = path.stat()
+            rel_path = path.relative_to(self.storage_dir)
+            type_folder = rel_path.parts[0] if len(rel_path.parts) > 1 else "root"
+
+            assets.append(AssetInfo(
+                path=str(path),
+                name=path.name,
+                asset_type=type_folder,
+                size_bytes=stat.st_size,
+                created=datetime.fromtimestamp(stat.st_mtime).isoformat(),
+                format=path.suffix.lower(),
+            ))
+
+        if sort_by == "name":
+            assets.sort(key=lambda a: a.name)
+        elif sort_by == "size":
+            assets.sort(key=lambda a: a.size_bytes, reverse=True)
+        else:
+            assets.sort(key=lambda a: a.created, reverse=True)
+
+        return assets
+
+    def list_types(self) -> Dict[str, int]:
+        """List asset types with counts."""
+        types = {}
+        if not self.storage_dir.exists():
+            return types
+
+        for subdir in self.storage_dir.iterdir():
+            if subdir.is_dir():
+                count = sum(1 for f in subdir.rglob("*") if f.is_file())
+                if count > 0:
+                    types[subdir.name] = count
+        return types
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get storage statistics."""
+        if not self.storage_dir.exists():
+            return {"total_files": 0, "total_size": 0, "types": {}}
+
+        types = self.list_types()
+        total_files = sum(types.values())
+        total_size = sum(
+            f.stat().st_size
+            for f in self.storage_dir.rglob("*")
+            if f.is_file()
+        )
+
+        return {
+            "total_files": total_files,
+            "total_size": total_size,
+            "total_size_human": AssetInfo._human_size(total_size),
+            "types": types,
+            "storage_path": str(self.storage_dir),
+        }
+
+    def search(self, query: str) -> List[AssetInfo]:
+        """Search assets by name."""
+        return [
+            a for a in self.list_assets()
+            if query.lower() in a.name.lower()
+        ]
+
+    def delete(self, path: str) -> bool:
+        """Delete an asset file."""
+        p = Path(path)
+        if p.exists() and p.is_file() and p.is_relative_to(self.storage_dir):
+            p.unlink()
+            return True
+        return False
+
+    def clear_type(self, asset_type: str) -> int:
+        """Clear all assets of a type. Returns count deleted."""
+        type_dir = self.storage_dir / asset_type
+        if not type_dir.exists():
+            return 0
+        count = 0
+        for f in type_dir.rglob("*"):
+            if f.is_file():
+                f.unlink()
+                count += 1
+        return count
+
+
+def get_browser(storage_dir: Optional[str] = None) -> AssetBrowser:
+    """Get an AssetBrowser instance."""
+    return AssetBrowser(storage_dir)

gameforge/engine/converter.py

@@ -0,0 +1,299 @@
+"""
+Converter - Converts assets between formats for game engine compatibility.
+Handles images, 3D models, audio, and video formats.
+"""
+
+from __future__ import annotations
+import subprocess
+import logging
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+
+logger = logging.getLogger(__name__)
+
+# Format conversion map: (source_ext, target_ext) -> converter function name
+CONVERSION_MAP = {
+    # Image conversions
+    (".png", ".jpg"): "convert_image",
+    (".png", ".webp"): "convert_image",
+    (".png", ".tga"): "convert_image",
+    (".jpg", ".png"): "convert_image",
+    (".webp", ".png"): "convert_image",
+    (".bmp", ".png"): "convert_image",
+
+    # Audio conversions
+    (".wav", ".ogg"): "convert_audio",
+    (".wav", ".mp3"): "convert_audio",
+    (".wav", ".flac"): "convert_audio",
+    (".mp3", ".ogg"): "convert_audio",
+    (".mp3", ".wav"): "convert_audio",
+    (".ogg", ".wav"): "convert_audio",
+
+    # Video conversions
+    (".mp4", ".webm"): "convert_video",
+    (".webm", ".mp4"): "convert_video",
+    (".avi", ".mp4"): "convert_video",
+
+    # 3D model conversions
+    (".glb", ".fbx"): "convert_3d",
+    (".glb", ".obj"): "convert_3d",
+    (".gltf", ".glb"): "convert_3d",
+    (".obj", ".glb"): "convert_3d",
+    (".fbx", ".glb"): "convert_3d",
+    (".stl", ".glb"): "convert_3d",
+}
+
+
+# Game engine specific export presets
+ENGINE_PRESETS = {
+    "unity": {
+        "image": {".png": {"max_size": 4096}, ".jpg": {"quality": 90}},
+        "3d": {".fbx": {"scale": 1.0}},
+        "audio": {".ogg": {"quality": 6}},
+        "video": {".mp4": {"codec": "h264"}},
+    },
+    "unreal": {
+        "image": {".png": {"max_size": 4096}, ".tga": {}},
+        "3d": {".fbx": {"scale": 1.0}},
+        "audio": {".wav": {"sample_rate": 44100}},
+        "video": {".mp4": {"codec": "h264"}},
+    },
+    "godot": {
+        "image": {".png": {"max_size": 4096}, ".webp": {"quality": 85}},
+        "3d": {".glb": {}},
+        "audio": {".ogg": {"quality": 6}, ".wav": {}},
+        "video": {".webm": {"codec": "vp9"}},
+    },
+}
+
+
+def convert_asset(
+    input_path: str,
+    target_format: str,
+    engine: Optional[str] = None,
+    **kwargs,
+) -> Optional[str]:
+    """
+    Convert an asset to a target format.
+
+    Args:
+        input_path: Path to the input file
+        target_format: Target format (e.g., ".png", ".ogg", ".fbx", ".glb")
+        engine: Optional game engine name ("unity", "unreal", "godot")
+    Returns:
+        Path to the converted file, or None on failure
+    """
+    inp = Path(input_path)
+    if not inp.exists():
+        logger.error(f"Input file not found: {input_path}")
+        return None
+
+    src_ext = inp.suffix.lower()
+    tgt_ext = target_format.lower() if target_format.startswith(".") else f".{target_format}"
+
+    # No conversion needed
+    if src_ext == tgt_ext:
+        return str(inp)
+
+    # Find converter
+    converter_name = CONVERSION_MAP.get((src_ext, tgt_ext))
+    if not converter_name:
+        # Try same-family conversion (e.g., image->image)
+        converter_name = _infer_converter(src_ext, tgt_ext)
+
+    if not converter_name:
+        logger.error(f"No converter for {src_ext} -> {tgt_ext}")
+        return None
+
+    converter_fn = CONVERTERS.get(converter_name)
+    if not converter_fn:
+        logger.error(f"Converter not implemented: {converter_name}")
+        return None
+
+    # Build output path
+    output_path = inp.with_suffix(tgt_ext)
+
+    # Apply engine preset if specified
+    if engine and engine in ENGINE_PRESETS:
+        engine_type = _guess_asset_type(tgt_ext)
+        preset = ENGINE_PRESETS.get(engine, {}).get(engine_type, {}).get(tgt_ext, {})
+        kwargs.update(preset)
+
+    try:
+        result = converter_fn(str(inp), str(output_path), **kwargs)
+        if result:
+            logger.info(f"Converted: {inp.name} -> {output_path.name}")
+        return result
+    except Exception as e:
+        logger.error(f"Conversion failed: {e}")
+        return None
+
+
+def export_for_engine(
+    input_path: str,
+    engine: str,
+    **kwargs,
+) -> Optional[str]:
+    """
+    Export an asset in the best format for a game engine.
+
+    Args:
+        input_path: Path to the input file
+        engine: "unity", "unreal", or "godot"
+    """
+    inp = Path(input_path)
+    asset_type = _guess_asset_type(inp.suffix)
+    preset = ENGINE_PRESETS.get(engine, {}).get(asset_type, {})
+
+    if not preset:
+        logger.warning(f"No preset for {engine}/{asset_type}, keeping original")
+        return str(inp)
+
+    # Pick the first (preferred) format
+    target_ext = list(preset.keys())[0]
+    return convert_asset(input_path, target_ext, engine=engine)
+
+
+def batch_convert(
+    input_dir: str,
+    target_format: str,
+    engine: Optional[str] = None,
+    pattern: str = "*",
+) -> List[str]:
+    """Convert all matching files in a directory."""
+    results = []
+    for f in Path(input_dir).glob(pattern):
+        result = convert_asset(str(f), target_format, engine=engine)
+        if result:
+            results.append(result)
+    return results
+
+
+# === Individual Converters ===
+
+
+def convert_image(src: str, dst: str, quality: int = 95, max_size: int = 0, **kw) -> Optional[str]:
+    """Convert image using Pillow."""
+    try:
+        from PIL import Image
+        img = Image.open(src)
+        if img.mode == "RGBA" and dst.endswith((".jpg",)):
+            img = img.convert("RGB")
+        if max_size > 0:
+            img.thumbnail((max_size, max_size), Image.LANCZOS)
+        save_kw = {}
+        if dst.endswith(".jpg") or dst.endswith(".jpeg"):
+            save_kw["quality"] = quality
+        elif dst.endswith(".webp"):
+            save_kw["quality"] = quality
+        img.save(dst, **save_kw)
+        return dst
+    except Exception as e:
+        logger.error(f"Image conversion failed: {e}")
+        return None
+
+
+def convert_audio(src: str, dst: str, sample_rate: int = 44100, quality: int = 5, **kw) -> Optional[str]:
+    """Convert audio using ffmpeg."""
+    try:
+        cmd = ["ffmpeg", "-y", "-i", src]
+        if dst.endswith(".ogg"):
+            cmd += ["-codec:a", "libvorbis", "-qscale:a", str(quality)]
+        elif dst.endswith(".mp3"):
+            cmd += ["-codec:a", "libmp3lame", "-qscale:a", str(quality)]
+        elif dst.endswith(".wav"):
+            cmd += ["-ar", str(sample_rate)]
+        elif dst.endswith(".flac"):
+            cmd += ["-codec:a", "flac"]
+        cmd.append(dst)
+        result = subprocess.run(cmd, capture_output=True, timeout=300)
+        if result.returncode == 0:
+            return dst
+        logger.error(f"ffmpeg error: {result.stderr.decode()[:200]}")
+        return None
+    except FileNotFoundError:
+        logger.error("ffmpeg not installed")
+        return None
+
+
+def convert_video(src: str, dst: str, codec: str = "h264", **kw) -> Optional[str]:
+    """Convert video using ffmpeg."""
+    try:
+        cmd = ["ffmpeg", "-y", "-i", src]
+        if codec == "h264":
+            cmd += ["-c:v", "libx264", "-preset", "medium", "-crf", "23"]
+        elif codec == "vp9":
+            cmd += ["-c:v", "libvpx-v9", "-crf", "30", "-b:v", "0"]
+        cmd.append(dst)
+        result = subprocess.run(cmd, capture_output=True, timeout=600)
+        if result.returncode == 0:
+            return dst
+        return None
+    except FileNotFoundError:
+        logger.error("ffmpeg not installed")
+        return None
+
+
+def convert_3d(src: str, dst: str, scale: float = 1.0, **kw) -> Optional[str]:
+    """Convert 3D models using trimesh."""
+    try:
+        import trimesh
+        mesh = trimesh.load(src)
+        if scale != 1.0 and hasattr(mesh, 'vertices'):
+            mesh.vertices *= scale
+        mesh.export(dst)
+        return dst
+    except ImportError:
+        logger.error("trimesh not installed. pip install trimesh")
+        return None
+    except Exception as e:
+        logger.error(f"3D conversion failed: {e}")
+        return None
+
+
+# === Helpers ===
+
+
+def _infer_converter(src_ext: str, tgt_ext: str) -> Optional[str]:
+    """Infer converter from extension families."""
+    image_exts = {".png", ".jpg", ".jpeg", ".webp", ".tga", ".bmp", ".gif"}
+    audio_exts = {".wav", ".mp3", ".ogg", ".flac", ".aac", ".m4a"}
+    video_exts = {".mp4", ".webm", ".avi", ".mov", ".mkv"}
+    threed_exts = {".glb", ".gltf", ".obj", ".fbx", ".stl", ".ply"}
+
+    if src_ext in image_exts and tgt_ext in image_exts:
+        return "convert_image"
+    if src_ext in audio_exts and tgt_ext in audio_exts:
+        return "convert_audio"
+    if src_ext in video_exts and tgt_ext in video_exts:
+        return "convert_video"
+    if src_ext in threed_exts and tgt_ext in threed_exts:
+        return "convert_3d"
+    return None
+
+
+def _guess_asset_type(ext: str) -> str:
+    """Guess asset type from extension."""
+    image_exts = {".png", ".jpg", ".jpeg", ".webp", ".tga", ".bmp"}
+    audio_exts = {".wav", ".mp3", ".ogg", ".flac"}
+    video_exts = {".mp4", ".webm", ".avi", ".mov"}
+    threed_exts = {".glb", ".gltf", ".obj", ".fbx", ".stl"}
+
+    ext = ext.lower()
+    if ext in image_exts:
+        return "image"
+    if ext in audio_exts:
+        return "audio"
+    if ext in video_exts:
+        return "video"
+    if ext in threed_exts:
+        return "3d"
+    return "unknown"
+
+
+CONVERTERS = {
+    "convert_image": convert_image,
+    "convert_audio": convert_audio,
+    "convert_video": convert_video,
+    "convert_3d": convert_3d,
+}

gameforge/engine/orchestrator.py

@@ -0,0 +1,584 @@
+"""
+Orchestrator - Runs pipeline YAML definitions through the HF Harness.
+Handles DAG execution, retries, and state management.
+"""
+
+from __future__ import annotations
+import yaml
+import json
+import time
+import os
+import logging
+from pathlib import Path
+from typing import Optional, Dict, Any, List, Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from gameforge.config.registry_loader import get_registry, ModelEntry
+from gameforge.engine.router import Router, RouteDecision, ExecutionTarget
+
+logger = logging.getLogger(__name__)
+
+PIPELINES_DIR = Path(__file__).parent.parent / "pipelines"
+OUTPUT_DIR = Path(__file__).parent.parent / "storage" / "local"
+
+
+@dataclass
+class StepResult:
+    """Result of a single pipeline step."""
+    step_name: str
+    success: bool
+    output: Any = None
+    error: Optional[str] = None
+    duration_sec: float = 0.0
+    model_used: str = ""
+    execution_target: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "step": self.step_name,
+            "success": self.success,
+            "output": str(self.output)[:200] if self.output else None,
+            "error": self.error,
+            "duration": self.duration_sec,
+            "model": self.model_used,
+            "target": self.execution_target,
+        }
+
+
+@dataclass
+class PipelineRun:
+    """A single execution of a pipeline."""
+    pipeline_name: str
+    started_at: str = ""
+    completed_at: str = ""
+    steps: List[StepResult] = field(default_factory=list)
+    inputs: Dict[str, Any] = field(default_factory=dict)
+    outputs: Dict[str, Any] = field(default_factory=dict)
+    status: str = "pending"  # pending, running, completed, failed
+
+    @property
+    def success(self) -> bool:
+        return self.status == "completed" and all(s.success for s in self.steps)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "pipeline": self.pipeline_name,
+            "status": self.status,
+            "started": self.started_at,
+            "completed": self.completed_at,
+            "steps": [s.to_dict() for s in self.steps],
+            "outputs": {k: str(v)[:200] for k, v in self.outputs.items()},
+        }
+
+
+class Orchestrator:
+    """
+    Executes pipeline definitions by routing each step through HF Harness.
+    """
+
+    def __init__(self, output_dir: Optional[str] = None):
+        self.registry = get_registry()
+        self.router = Router()
+        self.output_dir = Path(output_dir) if output_dir else OUTPUT_DIR
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self._history: List[PipelineRun] = []
+
+    def load_pipeline(self, name: str) -> Dict[str, Any]:
+        """Load a pipeline YAML definition."""
+        # Try exact name first, then with .yaml extension
+        candidates = [
+            PIPELINES_DIR / f"{name}.yaml",
+            PIPELINES_DIR / name,
+            PIPELINES_DIR / f"{name}.yml",
+        ]
+        for path in candidates:
+            if path.exists():
+                with open(path) as f:
+                    data = yaml.safe_load(f)
+                data["_path"] = str(path)
+                return data
+        raise FileNotFoundError(f"Pipeline not found: {name} (searched {PIPELINES_DIR})")
+
+    def list_pipelines(self) -> List[Dict[str, str]]:
+        """List available pipeline definitions."""
+        result = []
+        for path in PIPELINES_DIR.glob("*.yaml"):
+            try:
+                with open(path) as f:
+                    data = yaml.safe_load(f)
+                result.append({
+                    "name": path.stem,
+                    "description": data.get("description", ""),
+                    "version": data.get("version", ""),
+                    "steps": len(data.get("steps", [])),
+                })
+            except Exception:
+                pass
+        return result
+
+    def run(
+        self,
+        pipeline_name: str,
+        inputs: Optional[Dict[str, Any]] = None,
+        dry_run: bool = False,
+    ) -> PipelineRun:
+        """
+        Execute a pipeline end-to-end.
+
+        Args:
+            pipeline_name: Name of the pipeline YAML (without extension)
+            inputs: Override default inputs
+            dry_run: If True, show what would happen without executing
+        """
+        pipeline = self.load_pipeline(pipeline_name)
+        run = PipelineRun(
+            pipeline_name=pipeline_name,
+            started_at=datetime.now().isoformat(),
+            inputs=inputs or {},
+        )
+
+        # Merge defaults with provided inputs
+        defaults = pipeline.get("defaults", {})
+        run.inputs = {**defaults, **(inputs or {})}
+
+        logger.info(f"Starting pipeline: {pipeline_name}")
+        run.status = "running"
+
+        if dry_run:
+            run = self._dry_run(pipeline, run)
+            run.status = "completed"
+            return run
+
+        try:
+            context = dict(pipeline.get("defaults", {}))
+            context.update(run.inputs)  # Step outputs accumulate here
+
+            for step_def in pipeline.get("steps", []):
+                step_result = self._execute_step(step_def, context)
+                run.steps.append(step_result)
+
+                if step_result.success and step_result.output is not None:
+                    context[step_def["name"]] = step_result.output
+                    # Also store by output_key if specified
+                    out_key = step_def.get("output_key")
+                    if out_key:
+                        context[out_key] = step_result.output
+                elif not step_result.success:
+                    # Check if step is optional
+                    if step_def.get("optional", False):
+                        logger.warning(f"Optional step {step_def['name']} failed, continuing")
+                    else:
+                        run.status = "failed"
+                        break
+
+            if run.status != "failed":
+                run.status = "completed"
+
+            # Collect outputs
+            output_keys = pipeline.get("outputs", [])
+            for key in output_keys:
+                if key in context:
+                    run.outputs[key] = context[key]
+
+        except Exception as e:
+            logger.error(f"Pipeline failed: {e}")
+            run.status = "failed"
+            run.steps.append(StepResult(
+                step_name="pipeline_error",
+                success=False,
+                error=str(e),
+            ))
+
+        run.completed_at = datetime.now().isoformat()
+        self._history.append(run)
+        return run
+
+    def _dry_run(self, pipeline: Dict[str, Any], run: PipelineRun) -> PipelineRun:
+        """Show what would be executed without running."""
+        for step_def in pipeline.get("steps", []):
+            step_type = step_def.get("type", "unknown")
+            asset_type = step_def.get("asset_type", "")
+            variant = step_def.get("variant", "primary")
+
+            route = self.router.route(asset_type, variant) if asset_type else None
+            run.steps.append(StepResult(
+                step_name=step_def["name"],
+                success=True,
+                output=f"[DRY RUN] Would execute {step_type} via {route.target.value if route else 'unknown'}",
+                model_used=route.model_entry.model if route else "unknown",
+                execution_target=route.target.value if route else "unknown",
+            ))
+        return run
+
+    def _execute_step(self, step_def: Dict[str, Any], context: Dict[str, Any]) -> StepResult:
+        """Execute a single pipeline step."""
+        step_name = step_def["name"]
+        step_type = step_def.get("type", "unknown")
+        start_time = time.time()
+
+        logger.info(f"  Executing step: {step_name} (type={step_type})")
+
+        try:
+            if step_type == "generate":
+                return self._step_generate(step_def, context, start_time)
+            elif step_type == "transform":
+                return self._step_transform(step_def, context, start_time)
+            elif step_type == "enhance_prompt":
+                return self._step_enhance_prompt(step_def, context, start_time)
+            elif step_type == "save":
+                return self._step_save(step_def, context, start_time)
+            elif step_type == "validate":
+                return self._step_validate(step_def, context, start_time)
+            elif step_type == "convert":
+                return self._step_convert(step_def, context, start_time)
+            elif step_type == "call_space":
+                return self._step_call_space(step_def, context, start_time)
+            else:
+                return StepResult(
+                    step_name=step_name,
+                    success=False,
+                    error=f"Unknown step type: {step_type}",
+                    duration_sec=time.time() - start_time,
+                )
+        except Exception as e:
+            return StepResult(
+                step_name=step_name,
+                success=False,
+                error=str(e),
+                duration_sec=time.time() - start_time,
+            )
+
+    def _resolve_input(self, input_spec: Any, context: Dict[str, Any]) -> Any:
+        """Resolve a step input -- can be literal value or context reference."""
+        if isinstance(input_spec, str) and input_spec.startswith("$"):
+            key = input_spec[1:]
+            return context.get(key, input_spec)
+        return input_spec
+
+    def _step_generate(self, step: Dict, context: Dict, start: float) -> StepResult:
+        """Generate asset using a model."""
+        asset_type = step["asset_type"]
+        variant_raw = step.get("variant", "primary")
+        variant = self._resolve_input(variant_raw, context)
+        # Ensure variant is a string (not a resolved dict/object)
+        if not isinstance(variant, str):
+            variant = "primary"
+        prompt = self._resolve_input(step.get("prompt", ""), context)
+
+        route = self.router.route(asset_type, variant)
+
+        if route.target == ExecutionTarget.UNSUPPORTED:
+            return StepResult(
+                step_name=step["name"],
+                success=False,
+                error=route.reason,
+                duration_sec=time.time() - start,
+            )
+
+        # Build params from registry + step overrides
+        params = dict(route.model_entry.params)
+        params.update(step.get("params", {}))
+        params["prompt"] = prompt
+
+        # Route to appropriate executor
+        if route.target == ExecutionTarget.HF_INFERENCE:
+            output = self._exec_inference(route.model_entry, params)
+        elif route.target == ExecutionTarget.HF_SPACE:
+            output = self._exec_space(route.model_entry, params)
+        elif route.target == ExecutionTarget.LOCAL_PIPELINE:
+            output = self._exec_local_pipeline(route.model_entry, params)
+        else:
+            output = f"[{route.target.value}] Execution delegated"
+
+        return StepResult(
+            step_name=step["name"],
+            success=True,
+            output=output,
+            duration_sec=time.time() - start,
+            model_used=route.model_entry.model,
+            execution_target=route.target.value,
+        )
+
+    def _step_enhance_prompt(self, step: Dict, context: Dict, start: float) -> StepResult:
+        """Enhance a prompt using an LLM."""
+        prompt = self._resolve_input(step.get("prompt", ""), context)
+        template = step.get("template", "Enhance this game asset description for AI generation: {prompt}")
+
+        enhanced_prompt = template.format(prompt=prompt)
+
+        # Try the utility prompt enhancer model, but fall back gracefully
+        enhancer = self.registry.get_utility("prompt_enhancer")
+        if enhancer:
+            try:
+                from huggingface_hub import InferenceClient
+                import os
+                token = os.environ.get("HF_TOKEN", "")
+                client = InferenceClient(token=token)
+                messages = [{"role": "user", "content": enhanced_prompt}]
+                response = client.chat.completions.create(
+                    model=enhancer.model,
+                    messages=messages,
+                    max_tokens=enhancer.params.get("max_tokens", 512),
+                    temperature=enhancer.params.get("temperature", 0.8),
+                )
+                result = response.choices[0].message.content
+                return StepResult(
+                    step_name=step["name"],
+                    success=True,
+                    output=result,
+                    duration_sec=time.time() - start,
+                    model_used=enhancer.model,
+                    execution_target="hf_inference",
+                )
+            except Exception as e:
+                logger.warning(f"Prompt enhancer failed ({e}), using template result")
+
+        # Fallback: just return the template result
+        return StepResult(
+            step_name=step["name"],
+            success=True,
+            output=enhanced_prompt,
+            duration_sec=time.time() - start,
+        )
+
+    def _step_transform(self, step: Dict, context: Dict, start: float) -> StepResult:
+        """Transform data using a function."""
+        fn_name = step.get("function", "")
+        input_val = self._resolve_input(step.get("input", ""), context)
+
+        # Built-in transform functions
+        transforms = {
+            "prefix": lambda x, p=step.get("prefix", ""): f"{p}{x}",
+            "suffix": lambda x, s=step.get("suffix", ""): f"{x}{s}",
+            "wrap_prompt": lambda x: f"{step.get('prefix', '')}{x}{step.get('suffix', '')}",
+            "upper": lambda x: str(x).upper(),
+            "lower": lambda x: str(x).lower(),
+        }
+
+        fn = transforms.get(fn_name)
+        if fn:
+            output = fn(input_val)
+        else:
+            output = input_val
+
+        return StepResult(
+            step_name=step["name"],
+            success=True,
+            output=output,
+            duration_sec=time.time() - start,
+        )
+
+    def _step_save(self, step: Dict, context: Dict, start: float) -> StepResult:
+        """Save an asset to disk."""
+        content = self._resolve_input(step.get("content", ""), context)
+        filename = step.get("filename", "output.txt")
+        subfolder = step.get("subfolder", "")
+
+        save_dir = self.output_dir / subfolder if subfolder else self.output_dir
+        save_dir.mkdir(parents=True, exist_ok=True)
+        save_path = save_dir / filename
+
+        if isinstance(content, str) and content.startswith("http"):
+            # Download URL
+            import urllib.request
+            urllib.request.urlretrieve(content, str(save_path))
+        elif isinstance(content, str) and os.path.isfile(content):
+            # Gradio returns local temp file paths - copy them
+            import shutil
+            shutil.copy2(content, str(save_path))
+        elif isinstance(content, (bytes, bytearray)):
+            save_path.write_bytes(content)
+        elif hasattr(content, "save"):
+            # PIL Image object
+            content.save(str(save_path))
+        else:
+            save_path.write_text(str(content))
+
+        return StepResult(
+            step_name=step["name"],
+            success=True,
+            output=str(save_path),
+            duration_sec=time.time() - start,
+        )
+
+    def _step_validate(self, step: Dict, context: Dict, start: float) -> StepResult:
+        """Validate an asset meets requirements."""
+        content = self._resolve_input(step.get("input", ""), context)
+        checks = step.get("checks", [])
+
+        from gameforge.engine.validator import validate_asset
+        result = validate_asset(content, checks)
+
+        return StepResult(
+            step_name=step["name"],
+            success=result["valid"],
+            output=result,
+            error=None if result["valid"] else result.get("errors", []),
+            duration_sec=time.time() - start,
+        )
+
+    def _step_convert(self, step: Dict, context: Dict, start: float) -> StepResult:
+        """Convert asset format."""
+        input_path = self._resolve_input(step.get("input", ""), context)
+        target_format = step.get("target_format", "")
+
+        from gameforge.engine.converter import convert_asset
+        output_path = convert_asset(str(input_path), target_format)
+
+        return StepResult(
+            step_name=step["name"],
+            success=output_path is not None,
+            output=output_path,
+            error=None if output_path else "Conversion failed",
+            duration_sec=time.time() - start,
+        )
+
+    def _step_call_space(self, step: Dict, context: Dict, start: float) -> StepResult:
+        """Call a HF Space directly."""
+        space_id = step.get("space_id", "")
+        api_name = step.get("api_name", "/predict")
+        args = []
+        for inp in step.get("inputs", []):
+            args.append(self._resolve_input(inp, context))
+
+        try:
+            from gradio_client import Client
+            client = Client(space_id)
+            result = client.predict(*args, api_name=api_name)
+            return StepResult(
+                step_name=step["name"],
+                success=True,
+                output=result,
+                duration_sec=time.time() - start,
+                model_used=space_id,
+                execution_target="hf_space",
+            )
+        except Exception as e:
+            return StepResult(
+                step_name=step["name"],
+                success=False,
+                error=str(e),
+                duration_sec=time.time() - start,
+                model_used=space_id,
+                execution_target="hf_space",
+            )
+
+    # --- Execution Backends ---
+
+    def _exec_inference(self, model_entry: ModelEntry, params: Dict[str, Any]) -> Any:
+        """Execute via HF Inference API."""
+        try:
+            from huggingface_hub import InferenceClient, hf_hub_download
+            import os
+            # Get token from env or cached file
+            token = os.environ.get("HF_TOKEN", "") or os.environ.get("HUGGING_FACE_HUB_TOKEN", "")
+            if not token:
+                # Try cached token
+                for token_path in [
+                    os.path.expanduser("~/.cache/huggingface/token"),
+                    os.path.expanduser("~/.huggingface/token"),
+                ]:
+                    if os.path.isfile(token_path):
+                        token = open(token_path).read().strip()
+                        break
+
+            # Use hf-inference provider for free tier
+            client = InferenceClient(token=token, provider="hf-inference")
+            prompt = params.get("prompt", "")
+
+            # Determine task type from model
+            model = model_entry.model
+            if "text-to-image" in model_entry.type or "flux" in model.lower() or "stable-diffusion" in model.lower():
+                return client.text_to_image(
+                    prompt,
+                    model=model,
+                    negative_prompt=params.get("negative_prompt"),
+                    num_inference_steps=params.get("num_inference_steps", 20),
+                    guidance_scale=params.get("guidance_scale", 7.5),
+                )
+            elif "whisper" in model.lower() or "asr" in str(params):
+                with open(params.get("audio_path", ""), "rb") as f:
+                    return client.automatic_speech_recognition(f.read(), model=model)
+            else:
+                # For chat/instruct models, use chat completion
+                if any(tag in model.lower() for tag in ["instruct", "chat", "qwen", "llama", "mistral"]):
+                    messages = [{"role": "user", "content": prompt}]
+                    response = client.chat.completions.create(
+                        model=model,
+                        messages=messages,
+                        max_tokens=params.get("max_tokens", 512),
+                        temperature=params.get("temperature", 0.7),
+                    )
+                    return response.choices[0].message.content
+                else:
+                    # Default to text generation
+                    response = client.text_generation(
+                        prompt,
+                        model=model,
+                        max_new_tokens=params.get("max_tokens", 512),
+                        temperature=params.get("temperature", 0.7),
+                    )
+                    return response
+        except Exception as e:
+            logger.error(f"Inference failed: {e}")
+            raise
+
+    def _exec_space(self, model_entry: ModelEntry, params: Dict[str, Any]) -> Any:
+        """Execute via HF Space gradio_client."""
+        space_id = model_entry.space_id or model_entry.model
+        api_name = params.get("api_name", "/predict")
+        try:
+            from gradio_client import Client
+            client = Client(space_id)
+            prompt = params.get("prompt", "")
+
+            # Try the specified API name first, then common alternatives
+            api_names_to_try = [api_name]
+            if api_name != "/predict":
+                api_names_to_try.append("/predict")
+            api_names_to_try.extend(["/generate", "/run", "/infer", "/synthesize"])
+
+            last_error = None
+            for api in api_names_to_try:
+                try:
+                    result = client.predict(prompt, api_name=api)
+                    return result
+                except Exception as e:
+                    last_error = e
+                    # If it's an argument error, try without args
+                    if "required argument" in str(e):
+                        try:
+                            result = client.predict(api_name=api)
+                            return result
+                        except Exception:
+                            pass
+                    continue
+
+            raise last_error or Exception(f"No working API found for {space_id}")
+        except Exception as e:
+            logger.error(f"Space call failed for {space_id}: {e}")
+            raise
+
+    def _exec_local_pipeline(self, model_entry: ModelEntry, params: Dict[str, Any]) -> Any:
+        """Execute locally via transformers pipeline."""
+        try:
+            from transformers import pipeline as hf_pipeline
+            prompt = params.get("prompt", "")
+            pipe = hf_pipeline("text-generation", model=model_entry.model)
+            return pipe(prompt, max_new_tokens=params.get("max_tokens", 128))
+        except Exception as e:
+            logger.error(f"Local pipeline failed: {e}")
+            raise
+
+    @property
+    def history(self) -> List[PipelineRun]:
+        return self._history
+
+    def get_last_run(self) -> Optional[PipelineRun]:
+        return self._history[-1] if self._history else None
+
+
+def get_orchestrator(output_dir: Optional[str] = None) -> Orchestrator:
+    """Get an Orchestrator instance."""
+    return Orchestrator(output_dir)

gameforge/engine/router.py

@@ -0,0 +1,213 @@
+"""
+Router - Decides whether to run inference locally, via HF Spaces, or via free API.
+Handles fallback logic and rate limiting awareness.
+"""
+
+from __future__ import annotations
+from typing import Optional, Dict, Any, Tuple
+from dataclasses import dataclass
+from enum import Enum
+import logging
+
+from gameforge.config.registry_loader import ModelEntry, get_registry
+
+logger = logging.getLogger(__name__)
+
+
+class ExecutionTarget(Enum):
+    """Where to run a model."""
+    LOCAL_PIPELINE = "local_pipeline"    # transformers pipeline on local machine
+    HF_INFERENCE = "hf_inference"        # Free HF Inference API
+    HF_SPACE = "hf_space"                # Call a HF Space via gradio_client
+    EXTERNAL = "external"                # External API (Mixamo, etc.)
+    UNSUPPORTED = "unsupported"          # No way to run this
+
+
+@dataclass
+class RouteDecision:
+    """Result of routing a model to an execution target."""
+    target: ExecutionTarget
+    model_entry: ModelEntry
+    reason: str
+    requires_gpu: bool = False
+    estimated_cost: str = "free"
+    fallback_target: Optional[ExecutionTarget] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "target": self.target.value,
+            "model": self.model_entry.model,
+            "reason": self.reason,
+            "requires_gpu": self.requires_gpu,
+            "estimated_cost": self.estimated_cost,
+            "fallback": self.fallback_target.value if self.fallback_target else None,
+        }
+
+
+class Router:
+    """
+    Routes model requests to the best execution target.
+
+    Decision hierarchy:
+    1. If model type is "pipeline" and model is small enough -> local
+    2. If model type is "inference" -> HF free inference API
+    3. If model type is "space" -> HF Space via gradio_client
+    4. If model type is "external" -> External API call
+    5. Fallback: try inference first, then space
+    """
+
+    # Known small models that can run locally on CPU
+    LOCAL_FRIENDLY = {
+        "distilbert", "distilgpt2", "distilroberta", "distilbart",
+        "blip", "whisper-small", "whisper-base", "vit-base",
+        "bge-small", "all-minilm", "musicgen-small",
+    }
+
+    def __init__(self):
+        self.registry = get_registry()
+        self._rate_limit_hits = 0
+
+    def route(
+        self,
+        asset_type: str,
+        variant: str = "primary",
+        force_target: Optional[str] = None,
+        prefer_free: bool = True,
+    ) -> RouteDecision:
+        """
+        Route a generation request to the best execution target.
+
+        Args:
+            asset_type: e.g. "images", "video", "threed", "voice", "music"
+            variant: e.g. "primary", "fast", "cinematic"
+            force_target: Override routing ("local", "inference", "space", "external")
+            prefer_free: Prefer free tier when possible
+        """
+        model_entry = self.registry.get_model(asset_type, variant)
+        if not model_entry:
+            return RouteDecision(
+                target=ExecutionTarget.UNSUPPORTED,
+                model_entry=ModelEntry(model="unknown", type="unknown", license="unknown",
+                                       status="unknown", hardware="unknown"),
+                reason=f"No model registered for {asset_type}/{variant}",
+            )
+
+        # Forced override
+        if force_target:
+            return self._force_route(model_entry, force_target)
+
+        # Default routing based on model type
+        return self._auto_route(model_entry, prefer_free)
+
+    def _auto_route(self, entry: ModelEntry, prefer_free: bool) -> RouteDecision:
+        """Auto-route based on model entry type and hardware requirements."""
+        model_lower = entry.model.lower()
+
+        # Local pipeline models
+        if entry.type == "pipeline":
+            can_run_local = any(friendly in model_lower for friendly in self.LOCAL_FRIENDLY)
+            if can_run_local or entry.hardware == "local":
+                return RouteDecision(
+                    target=ExecutionTarget.LOCAL_PIPELINE,
+                    model_entry=entry,
+                    reason=f"Local pipeline: {entry.model} is small enough for CPU",
+                )
+            # Too big for local, try inference instead
+            return RouteDecision(
+                target=ExecutionTarget.HF_INFERENCE,
+                model_entry=entry,
+                reason=f"Model too large for local, using HF Inference API",
+                fallback_target=ExecutionTarget.HF_SPACE,
+            )
+
+        # Inference API models
+        if entry.type == "inference":
+            if entry.hardware == "free" or prefer_free:
+                return RouteDecision(
+                    target=ExecutionTarget.HF_INFERENCE,
+                    model_entry=entry,
+                    reason=f"Free HF Inference API: {entry.model}",
+                )
+            return RouteDecision(
+                target=ExecutionTarget.HF_INFERENCE,
+                model_entry=entry,
+                reason=f"HF Inference API: {entry.model}",
+            )
+
+        # HF Space models
+        if entry.type == "space":
+            gpu_required = entry.hardware not in ("cpu-basic", "free")
+            cost = self._estimate_space_cost(entry.hardware)
+            return RouteDecision(
+                target=ExecutionTarget.HF_SPACE,
+                model_entry=entry,
+                reason=f"HF Space: {entry.space_id or entry.model}",
+                requires_gpu=gpu_required,
+                estimated_cost=cost,
+                fallback_target=ExecutionTarget.HF_INFERENCE if not gpu_required else None,
+            )
+
+        # External APIs
+        if entry.type == "external":
+            return RouteDecision(
+                target=ExecutionTarget.EXTERNAL,
+                model_entry=entry,
+                reason=f"External API: {entry.model}",
+                estimated_cost="free" if entry.hardware == "cloud" else "unknown",
+            )
+
+        # Unknown type
+        return RouteDecision(
+            target=ExecutionTarget.UNSUPPORTED,
+            model_entry=entry,
+            reason=f"Unknown model type: {entry.type}",
+        )
+
+    def _force_route(self, entry: ModelEntry, target: str) -> RouteDecision:
+        """Handle forced routing."""
+        target_map = {
+            "local": ExecutionTarget.LOCAL_PIPELINE,
+            "inference": ExecutionTarget.HF_INFERENCE,
+            "space": ExecutionTarget.HF_SPACE,
+            "external": ExecutionTarget.EXTERNAL,
+        }
+        exec_target = target_map.get(target, ExecutionTarget.UNSUPPORTED)
+        return RouteDecision(
+            target=exec_target,
+            model_entry=entry,
+            reason=f"Forced to {target}",
+        )
+
+    def _estimate_space_cost(self, hardware: str) -> str:
+        """Estimate cost for HF Space hardware tier."""
+        costs = {
+            "cpu-basic": "free",
+            "cpu-upgrade": "$0.03/hr",
+            "t4-small": "$0.40/hr",
+            "t4-medium": "$0.60/hr",
+            "l4x1": "$0.80/hr",
+            "a10g-small": "$1.00/hr",
+            "a10g-large": "$1.50/hr",
+            "a100-large": "$2.50/hr",
+            "zerogpu": "free (quota)",
+        }
+        return costs.get(hardware, "unknown")
+
+    def get_all_routes(
+        self,
+        asset_type: str,
+        prefer_free: bool = True,
+    ) -> Dict[str, RouteDecision]:
+        """Get routing for all variants of an asset type."""
+        asset = self.registry.get_asset(asset_type)
+        if not asset:
+            return {}
+        return {
+            variant: self.route(asset_type, variant, prefer_free=prefer_free)
+            for variant in asset.list_variants()
+        }
+
+
+def get_router() -> Router:
+    """Get a Router instance."""
+    return Router()

gameforge/engine/validator.py

@@ -0,0 +1,198 @@
+"""
+Validator - Validates generated assets meet quality requirements.
+Checks images, 3D meshes, audio files, etc.
+"""
+
+from __future__ import annotations
+import os
+from pathlib import Path
+from typing import Optional, Dict, Any, List
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def validate_asset(
+    asset_path: Any,
+    checks: List[str],
+    **kwargs,
+) -> Dict[str, Any]:
+    """
+    Run validation checks on an asset.
+
+    Args:
+        asset_path: Path to the asset file, URL, or PIL Image
+        checks: List of check names to run
+    Returns:
+        {"valid": bool, "checks": {...}, "errors": [...]}
+    """
+    results = {}
+    errors = []
+
+    for check_name in checks:
+        check_fn = CHECKS.get(check_name)
+        if check_fn:
+            try:
+                passed, detail = check_fn(asset_path, **kwargs)
+                results[check_name] = {"passed": passed, "detail": detail}
+                if not passed:
+                    errors.append(f"{check_name}: {detail}")
+            except Exception as e:
+                results[check_name] = {"passed": False, "detail": str(e)}
+                errors.append(f"{check_name}: {e}")
+        else:
+            results[check_name] = {"passed": False, "detail": f"Unknown check: {check_name}"}
+
+    return {
+        "valid": len(errors) == 0,
+        "checks": results,
+        "errors": errors,
+    }
+
+
+# === Individual Check Functions ===
+
+
+def check_file_exists(path: Any, **kw) -> tuple:
+    """Check that the file exists."""
+    if isinstance(path, (str, Path)):
+        p = Path(path)
+        if p.exists():
+            return True, f"File exists ({p.stat().st_size} bytes)"
+        return False, f"File not found: {path}"
+    return True, "Not a file path (e.g., PIL Image or URL)"
+
+
+def check_image_resolution(path: Any, min_width: int = 64, min_height: int = 64, **kw) -> tuple:
+    """Check image meets minimum resolution."""
+    try:
+        from PIL import Image
+        if isinstance(path, str) and path.startswith("http"):
+            import urllib.request, io
+            data = urllib.request.urlopen(path).read()
+            img = Image.open(io.BytesIO(data))
+        elif isinstance(path, (str, Path)):
+            img = Image.open(path)
+        else:
+            img = path  # Assume PIL Image
+
+        w, h = img.size
+        if w >= min_width and h >= min_height:
+            return True, f"Resolution {w}x{h} meets minimum {min_width}x{min_height}"
+        return False, f"Resolution {w}x{h} below minimum {min_width}x{min_height}"
+    except Exception as e:
+        return False, f"Could not check resolution: {e}"
+
+
+def check_image_not_blank(path: Any, **kw) -> tuple:
+    """Check image is not a solid color / blank."""
+    try:
+        from PIL import Image
+        import numpy as np
+
+        if isinstance(path, (str, Path)):
+            img = Image.open(path).convert("RGB")
+        else:
+            img = path.convert("RGB") if hasattr(path, "convert") else path
+
+        arr = np.array(img)
+        std = arr.std()
+        if std > 5:  # Some variance exists
+            return True, f"Image has content (pixel std={std:.1f})"
+        return False, f"Image appears blank/near-uniform (pixel std={std:.1f})"
+    except ImportError:
+        return True, "numpy not available, skipping blank check"
+    except Exception as e:
+        return False, f"Could not check: {e}"
+
+
+def check_file_size(path: Any, min_bytes: int = 100, max_bytes: int = 50_000_000, **kw) -> tuple:
+    """Check file size is within bounds."""
+    if not isinstance(path, (str, Path)):
+        return True, "Not a file path"
+    p = Path(path)
+    if not p.exists():
+        return False, "File not found"
+    size = p.stat().st_size
+    if size < min_bytes:
+        return False, f"File too small ({size} bytes < {min_bytes})"
+    if size > max_bytes:
+        return False, f"File too large ({size} bytes > {max_bytes})"
+    return True, f"File size OK ({size} bytes)"
+
+
+def check_format(path: Any, expected_formats: list = None, **kw) -> tuple:
+    """Check file has expected format/extension."""
+    if not isinstance(path, (str, Path)):
+        return True, "Not a file path"
+    ext = Path(path).suffix.lower()
+    if expected_formats:
+        if ext in expected_formats:
+            return True, f"Format {ext} is expected"
+        return False, f"Format {ext} not in expected: {expected_formats}"
+    return True, f"Format: {ext}"
+
+
+def check_3d_mesh(path: Any, **kw) -> tuple:
+    """Check 3D mesh is valid (watertight, has UVs)."""
+    try:
+        import trimesh
+        mesh = trimesh.load(str(path))
+        info = {
+            "vertices": len(mesh.vertices) if hasattr(mesh, 'vertices') else 0,
+            "faces": len(mesh.faces) if hasattr(mesh, 'faces') else 0,
+            "watertight": mesh.is_watertight if hasattr(mesh, 'is_watertight') else None,
+        }
+        if info["vertices"] > 0:
+            return True, f"Mesh valid: {info['vertices']} verts, {info['faces']} faces"
+        return False, "Empty mesh"
+    except ImportError:
+        return True, "trimesh not installed, skipping mesh validation"
+    except Exception as e:
+        return False, f"Mesh validation failed: {e}"
+
+
+def check_audio_format(path: Any, min_duration: float = 0.5, **kw) -> tuple:
+    """Check audio file is valid and meets duration requirement."""
+    if not isinstance(path, (str, Path)):
+        return True, "Not a file path"
+    try:
+        import subprocess
+        result = subprocess.run(
+            ["ffprobe", "-v", "quiet", "-show_entries", "format=duration",
+             "-of", "default=noprint_wrappers=1:nokey=1", str(path)],
+            capture_output=True, text=True, timeout=10,
+        )
+        if result.returncode == 0:
+            duration = float(result.stdout.strip())
+            if duration >= min_duration:
+                return True, f"Audio duration: {duration:.1f}s"
+            return False, f"Audio too short: {duration:.1f}s < {min_duration}s"
+        return False, f"ffprobe failed: {result.stderr}"
+    except FileNotFoundError:
+        return True, "ffprobe not installed, skipping audio check"
+    except Exception as e:
+        return False, f"Audio check failed: {e}"
+
+
+def check_non_empty_output(path: Any, **kw) -> tuple:
+    """Check output is not None/empty."""
+    if path is None:
+        return False, "Output is None"
+    if isinstance(path, str) and path.strip() == "":
+        return False, "Output is empty string"
+    return True, "Output is non-empty"
+
+
+# === Registry of Checks ===
+
+CHECKS = {
+    "file_exists": check_file_exists,
+    "image_resolution": check_image_resolution,
+    "image_not_blank": check_image_not_blank,
+    "file_size": check_file_size,
+    "format": check_format,
+    "3d_mesh": check_3d_mesh,
+    "audio_format": check_audio_format,
+    "non_empty": check_non_empty_output,
+}

pipelines/asset_pack.yaml

@@ -0,0 +1,110 @@
+# Asset Pack Pipeline
+# ========================
+# Generates a complete asset pack for a game scene/theme.
+
+name: asset_pack
+version: "1.1.0"
+description: "Generate a complete game asset pack for a theme (all free/ZeroGPU)"
+
+defaults:
+  theme: "fantasy forest"
+  engine: "godot"
+
+inputs:
+  theme:
+    type: string
+    description: "Overall theme for the asset pack"
+    required: true
+
+steps:
+  # Step 1: Generate character concept
+  - name: character_concept
+    type: generate
+    asset_type: images
+    variant: primary
+    prompt: "$theme hero character, game asset, detailed, full body"
+    params:
+      negative_prompt: "blurry, low quality"
+      num_inference_steps: 4
+    output_key: character_image
+
+  - name: save_character
+    type: save
+    content: "$character_image"
+    filename: "character.png"
+    subfolder: "asset_pack"
+
+  # Step 2: Generate environment skybox
+  - name: environment_skybox
+    type: generate
+    asset_type: images
+    variant: primary
+    prompt: "$theme environment, game skybox, 360 panorama, atmospheric"
+    params:
+      negative_prompt: "text, watermark"
+      num_inference_steps: 28
+    output_key: skybox_image
+
+  - name: save_skybox
+    type: save
+    content: "$skybox_image"
+    filename: "skybox.png"
+    subfolder: "asset_pack"
+
+  # Step 3: Generate prop
+  - name: prop_concept
+    type: generate
+    asset_type: images
+    variant: primary
+    prompt: "$theme prop, game item, detailed, clean background"
+    params:
+      negative_prompt: "blurry"
+      num_inference_steps: 4
+    output_key: prop_image
+
+  - name: save_prop
+    type: save
+    content: "$prop_image"
+    filename: "prop.png"
+    subfolder: "asset_pack"
+
+  # Step 4: Generate sound effect via TangoFlux (ZeroGPU)
+  - name: ambient_sfx
+    type: call_space
+    space_id: "declare-lab/TangoFlux"
+    api_name: "/predict"
+    inputs:
+      - "$theme ambient sound effect"
+    output_key: sfx_audio
+    optional: true
+
+  - name: save_sfx
+    type: save
+    content: "$sfx_audio"
+    filename: "ambient.wav"
+    subfolder: "asset_pack"
+    optional: true
+
+  # Step 5: Generate music via ACE-Step (ZeroGPU)
+  - name: bgm
+    type: call_space
+    space_id: "victor/ace-step-jam"
+    api_name: "/predict"
+    inputs:
+      - "$theme background music, game soundtrack"
+    output_key: music_audio
+    optional: true
+
+  - name: save_music
+    type: save
+    content: "$music_audio"
+    filename: "bgm.wav"
+    subfolder: "asset_pack"
+    optional: true
+
+outputs:
+  - character_image
+  - skybox_image
+  - prop_image
+  - sfx_audio
+  - music_audio

pipelines/audio.yaml

@@ -0,0 +1,106 @@
+# Audio Cue Pipeline
+# ==================
+# Generates sound effects and background music via ZeroGPU Spaces.
+#
+# Usage:
+#   orchestrator.run("audio", inputs={"prompt": "epic orchestral battle theme", "audio_type": "music"})
+#   orchestrator.run("audio", inputs={"prompt": "sword slash whoosh", "audio_type": "sfx"})
+
+name: audio
+version: "1.1.0"
+description: "Generate sound effects or background music (ACE-Step / TangoFlux, ZeroGPU)"
+
+defaults:
+  audio_type: "sfx"
+  duration: 10
+
+inputs:
+  prompt:
+    type: string
+    description: "Sound description"
+    required: true
+  audio_type:
+    type: string
+    description: "sfx or music"
+    default: "sfx"
+  duration:
+    type: number
+    description: "Duration in seconds"
+    default: 10
+
+steps:
+  # Step 1: Enhance prompt for audio generation
+  - name: enhance_prompt
+    type: enhance_prompt
+    prompt: "$prompt"
+    template: >
+      Create a detailed audio generation prompt for a game {audio_type}:
+      {prompt}
+      Specify instruments, tempo, mood, reverb, and production quality.
+      Format as a concise audio generation prompt.
+    output_key: enhanced_prompt
+
+  # Step 2: Generate SFX via TangoFlux (ZeroGPU)
+  - name: generate_sfx
+    type: call_space
+    space_id: "declare-lab/TangoFlux"
+    api_name: "/predict"
+    inputs:
+      - "$enhanced_prompt"
+    output_key: audio_sfx
+    optional: true
+
+  # Step 3: Generate music via ACE-Step (ZeroGPU)
+  - name: generate_music
+    type: call_space
+    space_id: "victor/ace-step-jam"
+    api_name: "/predict"
+    inputs:
+      - "$enhanced_prompt"
+    output_key: audio_music
+    optional: true
+
+  # Step 4: Select the right output based on audio_type
+  - name: select_output
+    type: transform
+    function: prefix
+    input: "$audio_sfx"
+    prefix: ""
+    output_key: audio_file
+    optional: true
+
+  # Step 5: Save audio
+  - name: save_audio
+    type: save
+    content: "$audio_sfx"
+    filename: "audio_output.wav"
+    subfolder: "audio"
+
+  # Step 6: Validate audio
+  - name: validate_audio
+    type: validate
+    input: "$audio_sfx"
+    checks:
+      - non_empty
+      - file_exists
+      - audio_format
+    optional: true
+
+  # Step 7: Convert to OGG for game engines
+  - name: convert_ogg
+    type: convert
+    input: "$audio_sfx"
+    target_format: ".ogg"
+    optional: true
+
+  - name: save_ogg
+    type: save
+    content: "$convert_ogg"
+    filename: "audio_output.ogg"
+    subfolder: "audio"
+    optional: true
+
+outputs:
+  - enhanced_prompt
+  - audio_sfx
+  - audio_music

pipelines/character.yaml

@@ -0,0 +1,109 @@
+# Character Pipeline
+# ==================
+# Generates a game character from concept art to rigged 3D model.
+#
+# Flow: Text prompt -> Enhanced prompt -> Concept image -> 3D mesh -> Save
+#
+# Usage:
+#   orchestrator.run("character", inputs={"prompt": "fantasy knight in silver armor"})
+
+name: character
+version: "1.1.0"
+description: "Generate a game character: concept art -> 3D mesh"
+
+defaults:
+  style: "game asset, detailed, professional"
+  engine: "godot"
+  image_variant: "primary"
+  threed_variant: "primary"
+
+inputs:
+  prompt:
+    type: string
+    description: "Character description"
+    required: true
+  style:
+    type: string
+    description: "Art style modifier"
+    default: "game asset, detailed, professional"
+  engine:
+    type: string
+    description: "Target game engine"
+    default: "godot"
+
+steps:
+  # Step 1: Enhance the prompt for better image generation
+  - name: enhance_prompt
+    type: enhance_prompt
+    prompt: "$prompt"
+    template: >
+      Create a detailed image generation prompt for a game character:
+      {prompt}
+      Style: highly detailed 3D game character, clean background,
+      T-pose or A-pose, full body view, studio lighting,
+      suitable for 3D modeling reference.
+    output_key: enhanced_prompt
+
+  # Step 2: Generate concept art using FLUX
+  - name: concept_art
+    type: generate
+    asset_type: images
+    variant: "$image_variant"
+    prompt: "$enhanced_prompt"
+    params:
+      negative_prompt: "blurry, low quality, watermark, text, signature"
+      num_inference_steps: 4
+    output_key: concept_image
+
+  # Step 3: Save concept art
+  - name: save_concept
+    type: save
+    content: "$concept_image"
+    filename: "concept_art.png"
+    subfolder: "characters"
+
+  # Step 4: Validate concept art
+  - name: validate_concept
+    type: validate
+    input: "$concept_image"
+    checks:
+      - non_empty
+      - image_not_blank
+    optional: true
+
+  # Step 5: Generate 3D mesh via TRELLIS.2 (ZeroGPU)
+  - name: generate_3d
+    type: call_space
+    space_id: "microsoft/TRELLIS.2"
+    api_name: "/generate"
+    inputs:
+      - "$concept_image"
+    output_key: mesh_3d
+    optional: true
+
+  # Step 6: Save 3D mesh
+  - name: save_mesh
+    type: save
+    content: "$mesh_3d"
+    filename: "character.glb"
+    subfolder: "characters"
+    optional: true
+
+  # Step 7: Convert for target engine
+  - name: convert_for_engine
+    type: convert
+    input: "$mesh_3d"
+    target_format: ".fbx"
+    optional: true
+
+  - name: save_engine_export
+    type: save
+    content: "$convert_for_engine"
+    filename: "character.fbx"
+    subfolder: "characters"
+    optional: true
+
+outputs:
+  - enhanced_prompt
+  - concept_image
+  - mesh_3d

pipelines/cutscene.yaml

@@ -0,0 +1,91 @@
+# Cutscene Pipeline
+# =================
+# Generates short video cutscenes for games via LTX 2.3 or Wan 2.2 (ZeroGPU).
+#
+# Usage:
+#   orchestrator.run("cutscene", inputs={"prompt": "A dragon lands on a castle tower at sunset"})
+
+name: cutscene
+version: "1.1.0"
+description: "Generate game cutscene videos (LTX 2.3 / Wan 2.2, ZeroGPU)"
+
+defaults:
+  video_variant: "fast"
+  duration_sec: 4
+
+inputs:
+  prompt:
+    type: string
+    description: "Scene description / storyboard"
+    required: true
+  video_variant:
+    type: string
+    description: "fast (LTX Turbo), primary (LTX 2.3), cinematic (Wan 2.2)"
+    default: "fast"
+  duration_sec:
+    type: number
+    description: "Video duration in seconds"
+    default: 4
+  ref_image:
+    type: string
+    description: "Reference image for image-to-video (optional)"
+    default: ""
+
+steps:
+  # Step 1: Enhance the storyboard into a video prompt
+  - name: enhance_prompt
+    type: enhance_prompt
+    prompt: "$prompt"
+    template: >
+      Create a cinematic video generation prompt for a game cutscene:
+      {prompt}
+      Include camera movement (pan, zoom, tracking shot),
+      lighting description, motion details, and atmosphere.
+      Keep it under 200 words for the video model.
+    output_key: enhanced_prompt
+
+  # Step 2: Generate video via LTX-2 Turbo (ZeroGPU)
+  - name: generate_video
+    type: call_space
+    space_id: "alexnasa/ltx-2-TURBO"
+    api_name: "/generate"
+    inputs:
+      - "$enhanced_prompt"
+    output_key: video_file
+    optional: true
+
+  # Step 3: Save video
+  - name: save_video
+    type: save
+    content: "$video_file"
+    filename: "cutscene.mp4"
+    subfolder: "cutscenes"
+    optional: true
+
+  # Step 4: Validate
+  - name: validate_video
+    type: validate
+    input: "$video_file"
+    checks:
+      - non_empty
+      - file_exists
+      - file_size
+    optional: true
+
+  # Step 5: Convert to WebM for Godot
+  - name: convert_webm
+    type: convert
+    input: "$video_file"
+    target_format: ".webm"
+    optional: true
+
+  - name: save_webm
+    type: save
+    content: "$convert_webm"
+    filename: "cutscene.webm"
+    subfolder: "cutscenes"
+    optional: true
+
+outputs:
+  - enhanced_prompt
+  - video_file

pipelines/environment.yaml

@@ -0,0 +1,104 @@
+# Environment Pipeline
+# ====================
+# Generates game environments: skyboxes, 3D worlds (all free/ZeroGPU).
+
+name: environment
+version: "1.1.0"
+description: "Generate game environment: skybox or 3D world"
+
+defaults:
+  env_type: "skybox"
+  style: "game environment, detailed, professional"
+  image_variant: "primary"
+
+inputs:
+  prompt:
+    type: string
+    description: "Environment description"
+    required: true
+  env_type:
+    type: string
+    description: "skybox, terrain, or world"
+    default: "skybox"
+
+steps:
+  - name: enhance_prompt
+    type: enhance_prompt
+    prompt: "$prompt"
+    template: >
+      Create a detailed prompt for a game {env_type}:
+      {prompt}
+      Include lighting, atmosphere, color palette, mood.
+    output_key: enhanced_prompt
+
+  # Skybox generation (free Inference API)
+  - name: generate_skybox
+    type: generate
+    asset_type: images
+    variant: "$image_variant"
+    prompt: "$enhanced_prompt"
+    params:
+      prompt_suffix: ", 360 degree equirectangular panorama, seamless, game skybox"
+      negative_prompt: "text, watermark, border, frame, seams"
+      num_inference_steps: 28
+      width: 2048
+      height: 1024
+    output_key: skybox_image
+
+  - name: save_skybox
+    type: save
+    content: "$skybox_image"
+    filename: "skybox.png"
+    subfolder: "environments"
+
+  - name: validate_skybox
+    type: validate
+    input: "$skybox_image"
+    checks:
+      - non_empty
+      - image_not_blank
+      - image_resolution
+    optional: true
+
+  # Detail texture (free Inference API)
+  - name: generate_detail
+    type: generate
+    asset_type: images
+    variant: "texture"
+    prompt: "$prompt"
+    params:
+      prompt_prefix: "seamless tileable texture, top-down view, "
+      negative_prompt: "seams, borders, edges, frame, text"
+      num_inference_steps: 28
+    output_key: detail_texture
+    optional: true
+
+  - name: save_detail
+    type: save
+    content: "$detail_texture"
+    filename: "detail_texture.png"
+    subfolder: "environments"
+    optional: true
+
+  # 3D world via HY-World 2.0 (ZeroGPU)
+  - name: generate_world
+    type: call_space
+    space_id: "prithivMLmods/HY-World-2.0-Demo"
+    api_name: "/predict"
+    inputs:
+      - "$enhanced_prompt"
+    output_key: world_3d
+    optional: true
+
+  - name: save_world
+    type: save
+    content: "$world_3d"
+    filename: "world.glb"
+    subfolder: "environments"
+    optional: true
+
+outputs:
+  - enhanced_prompt
+  - skybox_image
+  - detail_texture
+  - world_3d

pipelines/npc_voice.yaml

@@ -0,0 +1,102 @@
+# NPC Voice Pipeline
+# ==================
+# Generates NPC dialogue voices using TTS with optional voice cloning.
+#
+# Flow: Script text -> Enhanced prompt -> TTS generation -> Convert -> Save
+#
+# Usage:
+#   orchestrator.run("npc_voice", inputs={"prompt": "Welcome traveler, what brings you to our village?"})
+#   With voice cloning:
+#   orchestrator.run("npc_voice", inputs={"prompt": "...", "ref_audio": "/path/to/reference.wav"})
+
+name: npc_voice
+version: "1.0.0"
+description: "Generate NPC dialogue voices for games"
+
+defaults:
+  voice_variant: "primary"
+  speed: 1.0
+  language: "EN"
+
+inputs:
+  prompt:
+    type: string
+    description: "NPC dialogue text"
+    required: true
+  ref_audio:
+    type: string
+    description: "Reference audio for voice cloning (optional)"
+    default: ""
+  speed:
+    type: number
+    description: "Speech speed multiplier"
+    default: 1.0
+  language:
+    type: string
+    description: "Language code"
+    default: "EN"
+
+steps:
+  # Step 1: Format the dialogue with emotion/direction
+  - name: format_dialogue
+    type: enhance_prompt
+    prompt: "$prompt"
+    template: >
+      Format this NPC dialogue for text-to-speech. Keep it natural and clear.
+      Add no markup, just clean text:
+      {prompt}
+    output_key: formatted_text
+
+  # Step 2: Generate voice using F5-TTS
+  - name: generate_voice
+    type: generate
+    asset_type: voice
+    variant: "$voice_variant"
+    prompt: "$formatted_text"
+    params:
+      speed: "$speed"
+      cross_fade_duration: 0.15
+      nfe_step: 32
+    output_key: voice_audio
+
+  # Step 3: Save voice
+  - name: save_voice
+    type: save
+    content: "$voice_audio"
+    filename: "npc_voice.wav"
+    subfolder: "voices"
+
+  # Step 4: Validate
+  - name: validate_voice
+    type: validate
+    input: "$voice_audio"
+    checks:
+      - non_empty
+      - file_exists
+      - audio_format
+    optional: true
+
+  # Step 5: Convert to OGG for game engines
+  - name: convert_ogg
+    type: convert
+    input: "$voice_audio"
+    target_format: ".ogg"
+    optional: true
+
+  - name: save_ogg
+    type: save
+    content: "$convert_ogg"
+    filename: "npc_voice.ogg"
+    subfolder: "voices"
+    optional: true
+
+  # Step 6: Also convert to WAV at 22050Hz for lightweight games
+  - name: convert_lightweight
+    type: convert
+    input: "$voice_audio"
+    target_format: ".wav"
+    optional: true
+
+outputs:
+  - formatted_text
+  - voice_audio

pipelines/prop.yaml

@@ -0,0 +1,92 @@
+# Prop Pipeline
+# =============
+# Generates individual game props: weapons, furniture, items, vehicles.
+# Uses FLUX for concept + TRELLIS.2 for 3D mesh (both free/ZeroGPU).
+
+name: prop
+version: "1.1.0"
+description: "Generate game props (weapons, items, furniture) -> concept + 3D"
+
+defaults:
+  style: "game asset, detailed, PBR, clean background"
+  image_variant: "primary"
+  threed_variant: "primary"
+
+inputs:
+  prompt:
+    type: string
+    description: "Prop description"
+    required: true
+  style:
+    type: string
+    description: "Art style"
+    default: "game asset, detailed, PBR, clean background"
+
+steps:
+  - name: enhance_prompt
+    type: enhance_prompt
+    prompt: "$prompt"
+    template: >
+      Create a detailed image generation prompt for a game prop:
+      {prompt}
+      Style: game-ready 3D prop, single object, clean white/gray background,
+      studio lighting, multiple angle hint, high detail, PBR-ready.
+    output_key: enhanced_prompt
+
+  - name: concept_art
+    type: generate
+    asset_type: images
+    variant: "$image_variant"
+    prompt: "$enhanced_prompt"
+    params:
+      negative_prompt: "blurry, low quality, watermark, text, multiple objects"
+      num_inference_steps: 4
+    output_key: concept_image
+
+  - name: save_concept
+    type: save
+    content: "$concept_image"
+    filename: "prop_concept.png"
+    subfolder: "props"
+
+  - name: generate_texture
+    type: generate
+    asset_type: images
+    variant: "texture"
+    prompt: "$prompt"
+    params:
+      prompt_prefix: "PBR texture, diffuse map, seamless, "
+      negative_prompt: "3d, perspective, object, background"
+      num_inference_steps: 28
+    output_key: texture_diffuse
+    optional: true
+
+  - name: save_texture
+    type: save
+    content: "$texture_diffuse"
+    filename: "prop_texture.png"
+    subfolder: "props"
+    optional: true
+
+  # 3D mesh via TRELLIS.2 (ZeroGPU)
+  - name: generate_3d
+    type: call_space
+    space_id: "microsoft/TRELLIS.2"
+    api_name: "/generate"
+    inputs:
+      - "$concept_image"
+    output_key: mesh_3d
+    optional: true
+
+  - name: save_mesh
+    type: save
+    content: "$mesh_3d"
+    filename: "prop.glb"
+    subfolder: "props"
+    optional: true
+
+outputs:
+  - enhanced_prompt
+  - concept_image
+  - texture_diffuse
+  - mesh_3d

pipelines/ui_element.yaml

@@ -0,0 +1,93 @@
+# UI Elements Pipeline
+# =====================
+# Generates game UI elements: icons, buttons, HUD elements, menus.
+#
+# Flow: Text -> Enhanced prompt -> Icon/UI image -> Convert -> Save
+#
+# Usage:
+#   orchestrator.run("ui_element", inputs={"prompt": "health potion icon, red flask"})
+
+name: ui_element
+version: "1.0.0"
+description: "Generate game UI elements (icons, buttons, HUD)"
+
+defaults:
+  style: "game UI, pixel art OR flat design"
+  image_variant: "primary"
+
+inputs:
+  prompt:
+    type: string
+    description: "UI element description"
+    required: true
+  style:
+    type: string
+    description: "UI style"
+    default: "game UI, flat design, clean, icon"
+  size:
+    type: string
+    description: "Output size (e.g., 64x64, 128x128, 256x256)"
+    default: "128x128"
+
+steps:
+  # Step 1: Enhance prompt for UI generation
+  - name: enhance_prompt
+    type: enhance_prompt
+    prompt: "$prompt"
+    template: >
+      Create a prompt for a game UI element:
+      {prompt}
+      Style: clean icon, transparent background, flat design,
+      game UI element, sharp edges, readable at small sizes.
+    output_key: enhanced_prompt
+
+  # Step 2: Generate UI element
+  - name: generate_ui
+    type: generate
+    asset_type: images
+    variant: "$image_variant"
+    prompt: "$enhanced_prompt"
+    params:
+      negative_prompt: "photo, realistic, 3d render, text, watermark, blurry"
+      num_inference_steps: 4
+    output_key: ui_image
+
+  # Step 3: Save
+  - name: save_ui
+    type: save
+    content: "$ui_image"
+    filename: "ui_element.png"
+    subfolder: "ui"
+
+  # Step 4: Validate
+  - name: validate_ui
+    type: validate
+    input: "$ui_image"
+    checks:
+      - non_empty
+      - image_not_blank
+    optional: true
+
+  # Step 5: Generate additional variants (hover, pressed, disabled)
+  - name: generate_hover
+    type: generate
+    asset_type: images
+    variant: "$image_variant"
+    prompt: "$enhanced_prompt"
+    params:
+      prompt_suffix: ", bright glow, hover state, highlighted"
+      num_inference_steps: 4
+    output_key: hover_image
+    optional: true
+
+  - name: save_hover
+    type: save
+    content: "$hover_image"
+    filename: "ui_element_hover.png"
+    subfolder: "ui"
+    optional: true
+
+outputs:
+  - enhanced_prompt
+  - ui_image
+  - hover_image

requirements.txt

@@ -0,0 +1,8 @@
+gradio>=5.25.0
+huggingface_hub>=0.28.0
+gradio_client>=1.0.0
+pyyaml>=6.0
+Pillow>=10.0.0
+numpy>=1.24.0
+spaces>=0.30.0
+torch>=2.0.0

static/css/app.css

@@ -0,0 +1,391 @@
+/* GameForge - Custom Frontend Styles */
+
+:root {
+    --bg-primary: #0f1117;
+    --bg-secondary: #1a1d27;
+    --bg-tertiary: #242836;
+    --bg-hover: #2d3245;
+    --text-primary: #e4e7f1;
+    --text-secondary: #9ca3bf;
+    --text-muted: #6b7394;
+    --accent: #6c5ce7;
+    --accent-hover: #7d6ff0;
+    --success: #00d68f;
+    --warning: #ffaa00;
+    --danger: #ff6b6b;
+    --border: #2d3245;
+    --radius: 8px;
+    --radius-lg: 12px;
+    --shadow: 0 4px 24px rgba(0,0,0,0.3);
+}
+
+* { margin: 0; padding: 0; box-sizing: border-box; }
+
+body {
+    font-family: 'Inter', -apple-system, sans-serif;
+    background: var(--bg-primary);
+    color: var(--text-primary);
+    line-height: 1.6;
+}
+
+#app {
+    display: flex;
+    min-height: 100vh;
+}
+
+/* Sidebar */
+.sidebar {
+    width: 220px;
+    background: var(--bg-secondary);
+    border-right: 1px solid var(--border);
+    display: flex;
+    flex-direction: column;
+    padding: 16px 0;
+    position: fixed;
+    top: 0;
+    left: 0;
+    bottom: 0;
+    z-index: 100;
+}
+
+.logo {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    padding: 0 20px 20px;
+    border-bottom: 1px solid var(--border);
+    margin-bottom: 16px;
+}
+
+.logo-icon { font-size: 24px; }
+.logo-text { font-size: 18px; font-weight: 700; color: var(--accent); }
+
+.nav { list-style: none; flex: 1; }
+
+.nav-item {
+    padding: 10px 20px;
+    cursor: pointer;
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    color: var(--text-secondary);
+    transition: all 0.15s;
+    font-size: 14px;
+}
+
+.nav-item:hover { background: var(--bg-hover); color: var(--text-primary); }
+.nav-item.active { background: var(--bg-tertiary); color: var(--accent); border-left: 3px solid var(--accent); }
+
+.nav-icon { font-size: 16px; width: 20px; text-align: center; }
+
+.sidebar-footer {
+    padding: 16px 20px;
+    border-top: 1px solid var(--border);
+}
+
+.gpu-status {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+    font-size: 12px;
+    color: var(--text-muted);
+}
+
+.status-dot {
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    background: var(--success);
+    animation: pulse 2s infinite;
+}
+
+@keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.5; }
+}
+
+/* Main content */
+.main {
+    flex: 1;
+    margin-left: 220px;
+    padding: 24px 32px;
+    max-width: 1200px;
+}
+
+.tab-content { display: none; }
+.tab-content.active { display: block; }
+
+h1 { font-size: 24px; font-weight: 700; margin-bottom: 24px; }
+h2 { font-size: 18px; font-weight: 600; margin: 24px 0 16px; color: var(--text-secondary); }
+
+/* Stats grid */
+.stats-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+    gap: 16px;
+    margin-bottom: 32px;
+}
+
+.stat-card {
+    background: var(--bg-secondary);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    padding: 20px;
+    text-align: center;
+}
+
+.stat-value {
+    font-size: 32px;
+    font-weight: 700;
+    color: var(--accent);
+    font-family: 'JetBrains Mono', monospace;
+}
+
+.stat-label {
+    font-size: 13px;
+    color: var(--text-muted);
+    margin-top: 4px;
+}
+
+/* Quick generate */
+.quick-gen-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+    gap: 12px;
+}
+
+.quick-gen-card {
+    background: var(--bg-secondary);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    padding: 24px 16px;
+    text-align: center;
+    cursor: pointer;
+    transition: all 0.15s;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 8px;
+}
+
+.quick-gen-card:hover {
+    border-color: var(--accent);
+    background: var(--bg-tertiary);
+    transform: translateY(-2px);
+}
+
+.qg-icon { font-size: 32px; }
+.qg-label { font-size: 14px; font-weight: 500; }
+
+/* Generate panel */
+.generate-panel {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 24px;
+}
+
+.gen-form { display: flex; flex-direction: column; gap: 16px; }
+
+.form-group { display: flex; flex-direction: column; gap: 6px; }
+.form-group label { font-size: 13px; font-weight: 500; color: var(--text-secondary); }
+
+input[type="text"], textarea, select {
+    background: var(--bg-tertiary);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 10px 14px;
+    color: var(--text-primary);
+    font-family: inherit;
+    font-size: 14px;
+    outline: none;
+    transition: border-color 0.15s;
+}
+
+input:focus, textarea:focus, select:focus { border-color: var(--accent); }
+
+.btn {
+    border: none;
+    border-radius: var(--radius);
+    padding: 10px 20px;
+    font-family: inherit;
+    font-size: 14px;
+    font-weight: 500;
+    cursor: pointer;
+    transition: all 0.15s;
+}
+
+.btn-primary { background: var(--accent); color: white; }
+.btn-primary:hover { background: var(--accent-hover); }
+.btn-primary:disabled { opacity: 0.5; cursor: not-allowed; }
+.btn-secondary { background: var(--bg-tertiary); color: var(--text-primary); border: 1px solid var(--border); }
+.btn-secondary:hover { background: var(--bg-hover); }
+.btn-lg { padding: 14px 28px; font-size: 16px; }
+
+/* Preview box */
+.preview-box {
+    background: var(--bg-secondary);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    min-height: 400px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    overflow: hidden;
+}
+
+.preview-placeholder {
+    text-align: center;
+    color: var(--text-muted);
+}
+
+.preview-placeholder span { font-size: 48px; display: block; margin-bottom: 12px; }
+
+.preview-box img, .preview-box video, .preview-box audio {
+    max-width: 100%;
+    max-height: 100%;
+    border-radius: var(--radius);
+}
+
+/* Pipeline grid */
+.pipeline-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+    gap: 16px;
+}
+
+.pipeline-card {
+    background: var(--bg-secondary);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    padding: 20px;
+}
+
+.pipeline-card h3 { font-size: 16px; margin-bottom: 8px; }
+.pipeline-card p { font-size: 13px; color: var(--text-muted); margin-bottom: 12px; }
+
+.pipeline-meta {
+    display: flex;
+    gap: 12px;
+    font-size: 12px;
+    color: var(--text-secondary);
+}
+
+/* Assets grid */
+.assets-toolbar {
+    display: flex;
+    gap: 12px;
+    margin-bottom: 20px;
+}
+
+.assets-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+    gap: 12px;
+}
+
+.asset-card {
+    background: var(--bg-secondary);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 12px;
+    font-size: 13px;
+}
+
+.asset-card .name { font-weight: 500; word-break: break-all; }
+.asset-card .meta { color: var(--text-muted); font-size: 12px; margin-top: 4px; }
+
+/* Models table */
+.models-filters {
+    display: flex;
+    gap: 16px;
+    margin-bottom: 16px;
+    align-items: center;
+}
+
+.models-table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 13px;
+}
+
+.models-table th {
+    text-align: left;
+    padding: 10px 12px;
+    background: var(--bg-secondary);
+    color: var(--text-secondary);
+    font-weight: 500;
+    border-bottom: 1px solid var(--border);
+}
+
+.models-table td {
+    padding: 8px 12px;
+    border-bottom: 1px solid var(--border);
+}
+
+.models-table tr:hover { background: var(--bg-hover); }
+
+.badge {
+    display: inline-block;
+    padding: 2px 8px;
+    border-radius: 4px;
+    font-size: 11px;
+    font-weight: 500;
+}
+
+.badge-free { background: rgba(0,214,143,0.15); color: var(--success); }
+.badge-paid { background: rgba(255,170,0,0.15); color: var(--warning); }
+.badge-safe { background: rgba(108,92,231,0.15); color: var(--accent); }
+.badge-check { background: rgba(255,107,107,0.15); color: var(--danger); }
+
+/* Batch */
+.batch-form {
+    background: var(--bg-secondary);
+    border: 1px solid var(--border);
+    border-radius: var(--radius-lg);
+    padding: 24px;
+    margin-bottom: 24px;
+}
+
+.batch-results {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+    gap: 12px;
+}
+
+/* Toast */
+#toast-container {
+    position: fixed;
+    bottom: 24px;
+    right: 24px;
+    z-index: 1000;
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+}
+
+.toast {
+    background: var(--bg-tertiary);
+    border: 1px solid var(--border);
+    border-radius: var(--radius);
+    padding: 12px 20px;
+    font-size: 14px;
+    animation: slideIn 0.2s ease-out;
+    max-width: 400px;
+}
+
+.toast-success { border-left: 3px solid var(--success); }
+.toast-error { border-left: 3px solid var(--danger); }
+.toast-info { border-left: 3px solid var(--accent); }
+
+@keyframes slideIn {
+    from { transform: translateX(100%); opacity: 0; }
+    to { transform: translateX(0); opacity: 1; }
+}
+
+/* Responsive */
+@media (max-width: 768px) {
+    .sidebar { width: 60px; }
+    .logo-text, .nav-item span:not(.nav-icon) { display: none; }
+    .main { margin-left: 60px; padding: 16px; }
+    .generate-panel { grid-template-columns: 1fr; }
+}

static/index.html

@@ -0,0 +1,224 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>GameForge - AI Game Asset Pipeline</title>
+    <link rel="stylesheet" href="/static/css/app.css">
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
+</head>
+<body>
+    <div id="app">
+        <!-- Sidebar -->
+        <nav class="sidebar">
+            <div class="logo">
+                <span class="logo-icon">⚔️</span>
+                <span class="logo-text">GameForge</span>
+            </div>
+            <ul class="nav">
+                <li class="nav-item active" data-tab="dashboard">
+                    <span class="nav-icon">📊</span> Dashboard
+                </li>
+                <li class="nav-item" data-tab="generate">
+                    <span class="nav-icon">✨</span> Generate
+                </li>
+                <li class="nav-item" data-tab="pipelines">
+                    <span class="nav-icon">🔗</span> Pipelines
+                </li>
+                <li class="nav-item" data-tab="assets">
+                    <span class="nav-icon">📁</span> Assets
+                </li>
+                <li class="nav-item" data-tab="models">
+                    <span class="nav-icon">🧠</span> Models
+                </li>
+                <li class="nav-item" data-tab="batch">
+                    <span class="nav-icon">📦</span> Batch
+                </li>
+            </ul>
+            <div class="sidebar-footer">
+                <div class="gpu-status">
+                    <span class="status-dot"></span>
+                    <span>ZeroGPU Ready</span>
+                </div>
+            </div>
+        </nav>
+
+        <!-- Main Content -->
+        <main class="main">
+            <!-- Dashboard -->
+            <section class="tab-content active" id="tab-dashboard">
+                <h1>Dashboard</h1>
+                <div class="stats-grid">
+                    <div class="stat-card">
+                        <div class="stat-value" id="stat-models">--</div>
+                        <div class="stat-label">Models Available</div>
+                    </div>
+                    <div class="stat-card">
+                        <div class="stat-value" id="stat-free">--</div>
+                        <div class="stat-label">Free (ZeroGPU)</div>
+                    </div>
+                    <div class="stat-card">
+                        <div class="stat-value" id="stat-pipelines">--</div>
+                        <div class="stat-label">Pipelines</div>
+                    </div>
+                    <div class="stat-card">
+                        <div class="stat-value" id="stat-assets">--</div>
+                        <div class="stat-label">Generated Assets</div>
+                    </div>
+                </div>
+                <h2>Quick Generate</h2>
+                <div class="quick-gen-grid">
+                    <button class="quick-gen-card" data-pipeline="character" data-prompt="fantasy knight in silver armor">
+                        <span class="qg-icon">⚔️</span>
+                        <span class="qg-label">Character</span>
+                    </button>
+                    <button class="quick-gen-card" data-pipeline="prop" data-prompt="enchanted magic sword with glowing runes">
+                        <span class="qg-icon">🗡️</span>
+                        <span class="qg-label">Prop</span>
+                    </button>
+                    <button class="quick-gen-card" data-pipeline="environment" data-prompt="dark fantasy forest clearing at twilight">
+                        <span class="qg-icon">🌲</span>
+                        <span class="qg-label">Environment</span>
+                    </button>
+                    <button class="quick-gen-card" data-pipeline="npc_voice" data-prompt="Welcome, traveler. What brings you to our village?">
+                        <span class="qg-icon">🗣️</span>
+                        <span class="qg-label">NPC Voice</span>
+                    </button>
+                    <button class="quick-gen-card" data-pipeline="audio" data-prompt="epic orchestral battle theme">
+                        <span class="qg-icon">🎵</span>
+                        <span class="qg-label">Music</span>
+                    </button>
+                    <button class="quick-gen-card" data-pipeline="audio" data-prompt="sword slash whoosh with metallic ring">
+                        <span class="qg-icon">💥</span>
+                        <span class="qg-label">SFX</span>
+                    </button>
+                </div>
+            </section>
+
+            <!-- Generate -->
+            <section class="tab-content" id="tab-generate">
+                <h1>Generate Asset</h1>
+                <div class="generate-panel">
+                    <div class="gen-form">
+                        <div class="form-group">
+                            <label>Asset Type</label>
+                            <select id="gen-type">
+                                <option value="image">Image (FLUX)</option>
+                                <option value="3d">3D Model (TRELLIS.2)</option>
+                                <option value="voice">NPC Voice (MeloTTS)</option>
+                                <option value="music">Music (ACE-Step)</option>
+                                <option value="video">Video (LTX 2.3)</option>
+                                <option value="sfx">Sound Effect (TangoFlux)</option>
+                            </select>
+                        </div>
+                        <div class="form-group">
+                            <label>Prompt</label>
+                            <textarea id="gen-prompt" placeholder="Describe your asset..." rows="4"></textarea>
+                        </div>
+                        <div class="form-group" id="neg-prompt-group">
+                            <label>Negative Prompt (optional)</label>
+                            <input type="text" id="gen-negative" placeholder="blurry, low quality, watermark">
+                        </div>
+                        <div class="form-group" id="ref-image-group" style="display:none">
+                            <label>Reference Image (for 3D)</label>
+                            <input type="file" id="gen-ref-image" accept="image/*">
+                        </div>
+                        <button class="btn btn-primary btn-lg" id="gen-btn">
+                            <span class="btn-text">Generate</span>
+                            <span class="btn-loading" style="display:none">Generating...</span>
+                        </button>
+                    </div>
+                    <div class="gen-preview">
+                        <div class="preview-box" id="gen-preview-box">
+                            <div class="preview-placeholder">
+                                <span>✨</span>
+                                <p>Your generated asset will appear here</p>
+                            </div>
+                        </div>
+                        <div class="gen-result-info" id="gen-result-info" style="display:none">
+                            <div id="gen-result-meta"></div>
+                            <button class="btn btn-secondary" id="gen-download">Download</button>
+                        </div>
+                    </div>
+                </div>
+            </section>
+
+            <!-- Pipelines -->
+            <section class="tab-content" id="tab-pipelines">
+                <h1>Pipelines</h1>
+                <div class="pipeline-grid" id="pipeline-grid">
+                    <!-- Loaded dynamically -->
+                </div>
+            </section>
+
+            <!-- Assets -->
+            <section class="tab-content" id="tab-assets">
+                <h1>Generated Assets</h1>
+                <div class="assets-toolbar">
+                    <select id="asset-filter">
+                        <option value="">All Types</option>
+                    </select>
+                    <button class="btn btn-secondary" id="asset-refresh">Refresh</button>
+                </div>
+                <div class="assets-grid" id="assets-grid">
+                    <!-- Loaded dynamically -->
+                </div>
+            </section>
+
+            <!-- Models -->
+            <section class="tab-content" id="tab-models">
+                <h1>Model Registry</h1>
+                <div class="models-filters">
+                    <select id="model-filter-type">
+                        <option value="">All Asset Types</option>
+                    </select>
+                    <label><input type="checkbox" id="model-filter-free"> Free Only</label>
+                    <label><input type="checkbox" id="model-filter-safe"> Commercial Safe</label>
+                </div>
+                <table class="models-table" id="models-table">
+                    <thead>
+                        <tr>
+                            <th>Asset Type</th>
+                            <th>Variant</th>
+                            <th>Model</th>
+                            <th>Type</th>
+                            <th>License</th>
+                            <th>Hardware</th>
+                            <th>Free</th>
+                            <th>Safe</th>
+                        </tr>
+                    </thead>
+                    <tbody id="models-tbody"></tbody>
+                </table>
+            </section>
+
+            <!-- Batch -->
+            <section class="tab-content" id="tab-batch">
+                <h1>Batch Generator</h1>
+                <div class="batch-form">
+                    <div class="form-group">
+                        <label>Pipeline</label>
+                        <select id="batch-pipeline"></select>
+                    </div>
+                    <div class="form-group">
+                        <label>Base Prompt</label>
+                        <textarea id="batch-prompt" placeholder="enchanted sword with glowing runes" rows="2"></textarea>
+                    </div>
+                    <div class="form-group">
+                        <label>Variants: <span id="batch-count-val">3</span></label>
+                        <input type="range" id="batch-count" min="1" max="10" value="3">
+                    </div>
+                    <button class="btn btn-primary" id="batch-btn">Generate Variants</button>
+                </div>
+                <div class="batch-results" id="batch-results"></div>
+            </section>
+        </main>
+
+        <!-- Toast notifications -->
+        <div id="toast-container"></div>
+    </div>
+
+    <script type="module" src="/static/js/app.js"></script>
+</body>
+</html>

static/js/app.js

@@ -0,0 +1,360 @@
+/**
+ * GameForge Frontend
+ * Custom HTML/CSS/JS app powered by gradio.Server + ZeroGPU.
+ */
+
+import { Client } from "https://cdn.jsdelivr.net/npm/@gradio/client/dist/index.min.js";
+
+// ============================================================================
+// State
+// ============================================================================
+
+let client = null;
+let registryData = [];
+let pipelines = [];
+
+// ============================================================================
+// Gradio Client Connection
+// ============================================================================
+
+async function connect() {
+    try {
+        client = await Client.connect(window.location.origin);
+        toast("Connected to GameForge", "success");
+        await loadDashboard();
+    } catch (e) {
+        toast("Failed to connect: " + e.message, "error");
+    }
+}
+
+// ============================================================================
+// API Helpers
+// ============================================================================
+
+async function api(endpoint, params = {}) {
+    if (!client) await connect();
+    try {
+        const result = await client.predict(endpoint, params);
+        return result.data;
+    } catch (e) {
+        toast(`API error (${endpoint}): ${e.message}`, "error");
+        throw e;
+    }
+}
+
+// ============================================================================
+// Navigation
+// ============================================================================
+
+document.querySelectorAll(".nav-item").forEach(item => {
+    item.addEventListener("click", () => {
+        document.querySelectorAll(".nav-item").forEach(i => i.classList.remove("active"));
+        document.querySelectorAll(".tab-content").forEach(t => t.classList.remove("active"));
+        item.classList.add("active");
+        const tab = document.getElementById("tab-" + item.dataset.tab);
+        if (tab) tab.classList.add("active");
+
+        // Load data for tab
+        if (item.dataset.tab === "models") loadModels();
+        if (item.dataset.tab === "pipelines") loadPipelines();
+        if (item.dataset.tab === "assets") loadAssets();
+        if (item.dataset.tab === "batch") loadBatchPipelines();
+    });
+});
+
+// ============================================================================
+// Dashboard
+// ============================================================================
+
+async function loadDashboard() {
+    try {
+        const [reg, pipes, assets] = await Promise.all([
+            api("/registry_info"),
+            api("/list_pipelines"),
+            api("/list_assets"),
+        ]);
+
+        registryData = reg.models || [];
+        pipelines = pipes || [];
+
+        document.getElementById("stat-models").textContent = registryData.length;
+        document.getElementById("stat-free").textContent = registryData.filter(m => m.free).length;
+        document.getElementById("stat-pipelines").textContent = pipelines.length;
+        document.getElementById("stat-assets").textContent = assets.length;
+
+        // Quick generate buttons
+        document.querySelectorAll(".quick-gen-card").forEach(card => {
+            card.addEventListener("click", () => {
+                const typeMap = {
+                    character: "image", prop: "image", environment: "image",
+                    npc_voice: "voice", audio: "music",
+                };
+                const type = typeMap[card.dataset.pipeline] || "image";
+                document.getElementById("gen-type").value = type;
+                document.getElementById("gen-prompt").value = card.dataset.prompt;
+                switchTab("generate");
+                document.getElementById("gen-btn").click();
+            });
+        });
+    } catch (e) {
+        console.error("Dashboard load failed:", e);
+    }
+}
+
+function switchTab(name) {
+    document.querySelector(`.nav-item[data-tab="${name}"]`)?.click();
+}
+
+// ============================================================================
+// Generate
+// ============================================================================
+
+const genType = document.getElementById("gen-type");
+const genBtn = document.getElementById("gen-btn");
+const genPrompt = document.getElementById("gen-prompt");
+const genPreview = document.getElementById("gen-preview-box");
+const genInfo = document.getElementById("gen-result-info");
+
+genType.addEventListener("change", () => {
+    const is3d = genType.value === "3d";
+    document.getElementById("ref-image-group").style.display = is3d ? "block" : "none";
+    document.getElementById("neg-prompt-group").style.display = (genType.value === "image") ? "block" : "none";
+});
+
+genBtn.addEventListener("click", async () => {
+    const prompt = genPrompt.value.trim();
+    if (!prompt) { toast("Enter a prompt", "error"); return; }
+
+    const type = genType.value;
+    const btnText = genBtn.querySelector(".btn-text");
+    const btnLoad = genBtn.querySelector(".btn-loading");
+
+    btnText.style.display = "none";
+    btnLoad.style.display = "inline";
+    genBtn.disabled = true;
+
+    genPreview.innerHTML = '<div class="preview-placeholder"><span>⏳</span><p>Generating...</p></div>';
+
+    try {
+        const endpointMap = {
+            image: "/generate_image",
+            voice: "/generate_voice",
+            music: "/generate_music",
+            video: "/generate_video",
+            sfx: "/generate_sfx",
+            "3d": "/generate_3d",
+        };
+
+        const endpoint = endpointMap[type];
+        let result;
+
+        if (type === "image") {
+            const neg = document.getElementById("gen-negative").value;
+            result = await client.predict(endpoint, { prompt, negative_prompt: neg, steps: 4 });
+        } else {
+            result = await client.predict(endpoint, { prompt, text: prompt });
+        }
+
+        const fileData = result.data[0];
+        if (fileData && fileData.url) {
+            showResult(fileData, type);
+            toast("Generated!", "success");
+        } else {
+            genPreview.innerHTML = '<div class="preview-placeholder"><span>❌</span><p>Generation failed</p></div>';
+        }
+    } catch (e) {
+        genPreview.innerHTML = `<div class="preview-placeholder"><span>❌</span><p>${e.message}</p></div>`;
+    } finally {
+        btnText.style.display = "inline";
+        btnLoad.style.display = "none";
+        genBtn.disabled = false;
+    }
+});
+
+function showResult(fileData, type) {
+    const url = fileData.url;
+    let html = "";
+
+    if (type === "image") {
+        html = `<img src="${url}" alt="Generated">`;
+    } else if (type === "video") {
+        html = `<video controls autoplay><source src="${url}" type="video/mp4"></video>`;
+    } else if (["voice", "music", "sfx"].includes(type)) {
+        html = `<audio controls autoplay><source src="${url}"></audio>`;
+    } else {
+        html = `<div class="preview-placeholder"><span>📦</span><p>3D Model Generated</p></div>`;
+    }
+
+    genPreview.innerHTML = html;
+    genInfo.style.display = "flex";
+
+    document.getElementById("gen-download").onclick = () => {
+        const a = document.createElement("a");
+        a.href = url;
+        a.download = `gameforge_${type}_${Date.now()}`;
+        a.click();
+    };
+}
+
+// ============================================================================
+// Models
+// ============================================================================
+
+async function loadModels() {
+    if (!registryData.length) {
+        const reg = await api("/registry_info");
+        registryData = reg.models || [];
+    }
+
+    const typeFilter = document.getElementById("model-filter-type");
+    const freeOnly = document.getElementById("model-filter-free");
+    const safeOnly = document.getElementById("model-filter-safe");
+
+    // Populate type filter
+    const types = [...new Set(registryData.map(m => m.asset_type))];
+    if (typeFilter.options.length <= 1) {
+        types.forEach(t => {
+            const opt = document.createElement("option");
+            opt.value = t;
+            opt.textContent = t;
+            typeFilter.appendChild(opt);
+        });
+    }
+
+    function render() {
+        let models = registryData;
+        if (typeFilter.value) models = models.filter(m => m.asset_type === typeFilter.value);
+        if (freeOnly.checked) models = models.filter(m => m.free);
+        if (safeOnly.checked) models = models.filter(m => m.commercial_safe);
+
+        const tbody = document.getElementById("models-tbody");
+        tbody.innerHTML = models.map(m => `
+            <tr>
+                <td>${m.asset_type}</td>
+                <td>${m.variant}</td>
+                <td style="font-family:monospace;font-size:12px">${m.model}</td>
+                <td>${m.type}</td>
+                <td>${m.license}</td>
+                <td>${m.hardware}</td>
+                <td><span class="badge ${m.free ? 'badge-free' : 'badge-paid'}">${m.free ? 'FREE' : 'PAID'}</span></td>
+                <td><span class="badge ${m.commercial_safe ? 'badge-safe' : 'badge-check'}">${m.commercial_safe ? 'SAFE' : 'CHECK'}</span></td>
+            </tr>
+        `).join("");
+    }
+
+    typeFilter.onchange = freeOnly.onchange = safeOnly.onchange = render;
+    render();
+}
+
+// ============================================================================
+// Pipelines
+// ============================================================================
+
+async function loadPipelines() {
+    if (!pipelines.length) {
+        pipelines = await api("/list_pipelines");
+    }
+
+    const grid = document.getElementById("pipeline-grid");
+    grid.innerHTML = pipelines.map(p => `
+        <div class="pipeline-card">
+            <h3>${p.name}</h3>
+            <p>${p.description}</p>
+            <div class="pipeline-meta">
+                <span>📋 ${p.steps} steps</span>
+                <span>v${p.version}</span>
+            </div>
+        </div>
+    `).join("");
+}
+
+// ============================================================================
+// Assets
+// ============================================================================
+
+async function loadAssets() {
+    const assets = await api("/list_assets");
+    const grid = document.getElementById("assets-grid");
+
+    if (!assets.length) {
+        grid.innerHTML = '<p style="color:var(--text-muted);grid-column:1/-1">No assets generated yet. Go to Generate to create some!</p>';
+        return;
+    }
+
+    grid.innerHTML = assets.map(a => `
+        <div class="asset-card">
+            <div class="name">${a.name}</div>
+            <div class="meta">${a.format} &middot; ${(a.size / 1024).toFixed(1)} KB</div>
+        </div>
+    `).join("");
+}
+
+document.getElementById("asset-refresh")?.addEventListener("click", loadAssets);
+
+// ============================================================================
+// Batch
+// ============================================================================
+
+async function loadBatchPipelines() {
+    if (!pipelines.length) {
+        pipelines = await api("/list_pipelines");
+    }
+
+    const select = document.getElementById("batch-pipeline");
+    select.innerHTML = pipelines.map(p =>
+        `<option value="${p.name}">${p.name} (${p.steps} steps)</option>`
+    ).join("");
+}
+
+document.getElementById("batch-count")?.addEventListener("input", (e) => {
+    document.getElementById("batch-count-val").textContent = e.target.value;
+});
+
+document.getElementById("batch-btn")?.addEventListener("click", async () => {
+    const pipeline = document.getElementById("batch-pipeline").value;
+    const prompt = document.getElementById("batch-prompt").value;
+    const count = parseInt(document.getElementById("batch-count").value);
+
+    if (!prompt) { toast("Enter a prompt", "error"); return; }
+
+    toast(`Generating ${count} variants...`, "info");
+
+    // Run variants sequentially
+    const results = document.getElementById("batch-results");
+    results.innerHTML = "";
+
+    for (let i = 0; i < count; i++) {
+        const card = document.createElement("div");
+        card.className = "asset-card";
+        card.innerHTML = `<div class="name">Variant ${i + 1}</div><div class="meta">Generating...</div>`;
+        results.appendChild(card);
+
+        try {
+            // Each variant gets a slightly different prompt
+            const variantPrompt = `${prompt}, style variation ${i + 1}`;
+            // This would call the pipeline endpoint
+            card.querySelector(".meta").textContent = "Queued";
+        } catch (e) {
+            card.querySelector(".meta").textContent = "Failed: " + e.message;
+        }
+    }
+});
+
+// ============================================================================
+// Toast Notifications
+// ============================================================================
+
+function toast(message, type = "info") {
+    const container = document.getElementById("toast-container");
+    const el = document.createElement("div");
+    el.className = `toast toast-${type}`;
+    el.textContent = message;
+    container.appendChild(el);
+    setTimeout(() => el.remove(), 4000);
+}
+
+// ============================================================================
+// Init
+// ============================================================================
+
+connect();