Generate separate roles and reject multi-view sprite sheets

README.md

@@ -29,7 +29,20 @@ The generator injects an immutable `window.GAME_ASSETS` manifest whose keys are
 
 If a requested role has no deterministic hook, assets are still generated for review, but no rewritten game is returned. The status explains which hooks are missing and the preview is explicitly the unchanged original game.
 
-Generated sprites receive automated dimension, alpha-channel, and corner-transparency checks. These checks do not establish semantic or artistic correctness, so every role also has a manual approval control and per-role regeneration.
+## Multiple character sprites
+
+Define each distinct character as its own role so the model produces a separate PNG and the game can address it independently:
+
+```text
+player: agile desert ranger with a leather bow
+enemy_grunt: compact orange patrol robot
+enemy_boss: towering red armored commander
+npc_merchant: elderly traveling potion seller
+```
+
+The generator runs one neural image request per role rather than intentionally combining character roles into a contact sheet. The image model can still violate the one-subject instruction, so every result requires visual review. When the submitted HTML references additional deterministic hooks such as `GAME_ASSETS.enemy_grunt`, `GAME_ASSETS.enemy_boss`, or `sprite_npc_merchant.png`, missing roles are automatically added to the generation set. Explicit role descriptions remain preferable because code identifiers alone provide limited visual direction. Repeated instances of the same enemy should reuse one role, while visually distinct character types should use separate roles.
+
+Generated sprites receive automated dimension, alpha-channel, corner-transparency, and significant-foreground-component checks. A multi-subject sprite is rejected and regenerated with a fresh model seed rather than cropped or procedurally rearranged. These checks do not establish semantic or artistic correctness, so every role also has a manual approval control and per-role regeneration.
 
 The UI reports the configured prompt and image pipeline and labels every role with its actual source. Every asset carries a normalized camera contract (`top_down`, `side_view`, `isometric`, `first_person`, or `front_view`). Top-down background prompts explicitly forbid a sky, horizon, eye-level view, and front-facing facades.
 
@@ -49,7 +62,7 @@ segmind/SSD-1B + latent-consistency/lcm-lora-ssd-1b
 
 SSD-1B is an Apache-2.0 distilled SDXL model. The LCM adapter enables low-step generation. The weights run inside the Space's ZeroGPU allocation, so the app does not consume Hugging Face Inference Provider credits and does not require a paid image API.
 
-Sprites and backgrounds are generated directly from their written prompts. No procedurally drawn sprite, palette, silhouette, camera guide, or background layout is passed into the production model. Camera perspective is enforced through explicit positive and negative prompt contracts. Background negative prompts reject characters and generic particle overlays, while sprite prompts request a complete subject on a uniform white field for later transparency extraction.
+Sprites and backgrounds are generated directly from their written prompts. No procedurally drawn sprite, palette, silhouette, camera guide, or background layout is passed into the production model. Sprite prompts use a portrait canvas and positive single-subject composition language; the negative prompt separately rejects sheets, lineups, repeated subjects, and multiple views. After transparency extraction, sprites with zero or multiple significant foreground components are regenerated with a new seed up to `PRIMARY_SPRITE_ATTEMPTS` times. If every attempt fails, the deployed Space returns an explicit model-generation error rather than returning a contact sheet. Background negative prompts reject characters and generic particle overlays.
 
 The deployed Space is fail-closed: if the primary neural model cannot run, generation stops with a visible error instead of silently returning procedural art and calling it model output. The procedural renderer remains available for local development and diagnostics only and cannot influence successful public generations.
 
@@ -64,6 +77,7 @@ PRIMARY_IMAGE_MODEL=segmind/SSD-1B
 PRIMARY_LORA_MODEL=latent-consistency/lcm-lora-ssd-1b
 PRIMARY_IMAGE_STEPS=4
 PRIMARY_SPRITE_STEPS=6
+PRIMARY_SPRITE_ATTEMPTS=3
 PRIMARY_GUIDANCE_SCALE=1.5
 ```
 

app.py

@@ -87,6 +87,8 @@ DEFAULT_ROLES = """player: top-down pixel-art adventurer hero, transparent backg
 background: enchanted forest clearing game background, top-down view, soft moonlight, detailed but not too busy"""
 
 ROLE_PLACEHOLDER = """player: blue robot hero sprite
+enemy_grunt: compact orange patrol robot
+enemy_boss: towering red armored commander
 background: empty space station floor map"""
 
 
@@ -125,6 +127,7 @@ PRIMARY_IMAGE_MODEL = os.environ.get("PRIMARY_IMAGE_MODEL", "segmind/SSD-1B")
 PRIMARY_LORA_MODEL = os.environ.get("PRIMARY_LORA_MODEL", "latent-consistency/lcm-lora-ssd-1b")
 PRIMARY_IMAGE_STEPS = int(os.environ.get("PRIMARY_IMAGE_STEPS", "4"))
 PRIMARY_SPRITE_STEPS = int(os.environ.get("PRIMARY_SPRITE_STEPS", "6"))
+PRIMARY_SPRITE_ATTEMPTS = max(1, int(os.environ.get("PRIMARY_SPRITE_ATTEMPTS", "3")))
 PRIMARY_GUIDANCE_SCALE = float(os.environ.get("PRIMARY_GUIDANCE_SCALE", "1.5"))
 USE_PRIMARY_IMAGE_MODEL = os.environ.get("USE_PRIMARY_IMAGE_MODEL", "1") == "1"
 REQUIRE_PRIMARY_IMAGE_MODEL = os.environ.get(
@@ -324,10 +327,9 @@ def build_asset_prompt(role: str, prompt: str, style_hint: str) -> str:
         )
     else:
         asset_instruction = (
-            "Create exactly one complete standalone 2D game character or object, centered and fully visible. "
-            "Show one subject in one pose from one view only; do not create a character sheet, turnaround, lineup, "
-            "or alternate views. Use a transparent or plain background and a readable silhouette. Not a texture map, "
-            "not a tiled pattern, not a material swatch, not a UV unwrap, not a 3D model skin."
+            "Create a complete standalone 2D game character or object as a single centered subject. "
+            "Present one complete body in one pose from the required camera direction, fully visible with broad empty "
+            "margin on every side. Use a clean uniform white studio field and a readable game-scale silhouette."
         )
     return (
         f"{role} asset: {prompt}. Creative brief: {style_hint}. "
@@ -335,7 +337,7 @@ def build_asset_prompt(role: str, prompt: str, style_hint: str) -> str:
         f"{plan.texture}; {plan.lighting}; {plan.linework}; {plan.camera}. "
         f"Camera contract: {camera_prompt_contract(camera, is_background)} "
         f"{asset_instruction} "
-        "Game asset, readable at small size, no text, no watermark."
+        "Game asset, readable at small size, with a clean unlabeled presentation."
     )
 
 
@@ -370,6 +372,52 @@ def parse_role_lines(raw_roles: str) -> list[tuple[str, str]]:
     return parsed
 
 
+def extract_code_asset_roles(html_code: str) -> list[str]:
+    """Return deterministic GAME_ASSETS and sprite filename roles in source order."""
+    matches: list[tuple[int, str]] = []
+    patterns = (
+        r"(?:window\.)?GAME_ASSETS\s*\.\s*([a-zA-Z_$][\w$]*)",
+        r"(?:window\.)?GAME_ASSETS\s*\[\s*['\"]([a-zA-Z0-9_-]+)['\"]\s*\]",
+        r"['\"]sprite_([a-zA-Z0-9_-]+)\.(?:png|jpg|jpeg|webp|gif)['\"]",
+    )
+    for pattern in patterns:
+        for match in re.finditer(pattern, html_code, flags=re.I):
+            matches.append((match.start(), slugify(match.group(1))))
+
+    roles: list[str] = []
+    seen: set[str] = set()
+    for _, role in sorted(matches, key=lambda item: item[0]):
+        if role not in seen:
+            seen.add(role)
+            roles.append(role)
+    return roles
+
+
+def inferred_role_prompt(role: str) -> str:
+    """Create a conservative prompt when code exposes a role without an art brief."""
+    slug = slugify(role)
+    label = slug.replace("_", " ")
+    if any(word in slug for word in ("background", "backdrop", "scene", "map", "level")):
+        return f"complete {label} game environment"
+    if any(word in slug for word in ("player", "hero", "enemy", "boss", "npc", "character", "ally", "companion")):
+        return f"distinct full-body {label} character"
+    return f"distinct {label} game asset"
+
+
+def resolve_role_lines(html_code: str, raw_roles: str) -> tuple[list[tuple[str, str]], list[str]]:
+    """Merge user-authored roles with missing deterministic roles found in game code."""
+    role_lines = parse_role_lines(raw_roles)
+    seen = {slugify(role) for role, _ in role_lines}
+    inferred: list[str] = []
+    for role in extract_code_asset_roles(html_code):
+        if role in seen:
+            continue
+        seen.add(role)
+        inferred.append(role)
+        role_lines.append((role, inferred_role_prompt(role)))
+    return role_lines, inferred
+
+
 def infer_code_context(html_code: str) -> str:
     text = html_code[:12000]
     filenames = sorted(set(re.findall(r"['\"]([^'\"]+?\.(?:png|jpg|jpeg|webp|gif))['\"]", text, flags=re.I)))
@@ -428,7 +476,8 @@ def hf_prompt_json(html_code: str, role_lines: list[tuple[str, str]], style_hint
         "each key is the exact role name and each value is one concise text-to-image prompt. "
         "Each prompt must specify: subject silhouette/shape, camera angle, art style, palette, "
         "transparent background for sprites/items, full scene for backgrounds, no text, no watermark. "
-        "Make different roles visually distinct and suitable for embedding in an HTML game."
+        "Make different roles visually distinct and suitable for embedding in an HTML game. "
+        "Describe only one role per prompt; never combine multiple character roles into one image."
     )
     user_text = (
         f"HTML/game context summary: {infer_code_context(html_code)}\n\n"
@@ -481,18 +530,27 @@ def hf_prompt_json(html_code: str, role_lines: list[tuple[str, str]], style_hint
         return None, short_error(exc)
 
 
-def build_prompt_map(html_code: str, raw_roles: str, style_hint: str) -> tuple[list[tuple[str, str]], dict[str, str], str, str | None]:
-    role_lines = parse_role_lines(raw_roles)
+def build_prompt_map(
+    html_code: str,
+    raw_roles: str,
+    style_hint: str,
+) -> tuple[list[tuple[str, str]], dict[str, str], str, str | None, list[str]]:
+    role_lines, inferred_roles = resolve_role_lines(html_code, raw_roles)
     local_map = local_prompt_map(role_lines, style_hint)
     ai_map, prompt_error = hf_prompt_json(html_code, role_lines, style_hint)
     if ai_map and all(role in ai_map for role, _ in role_lines):
-        return role_lines, ai_map, HF_PROMPT_MODEL, None
-    return role_lines, local_map, "local prompt interpreter", prompt_error
+        return role_lines, ai_map, HF_PROMPT_MODEL, None, inferred_roles
+    return role_lines, local_map, "local prompt interpreter", prompt_error, inferred_roles
 
 
-def parse_assets(raw_roles: str, style_hint: str, prompt_map: dict[str, str] | None = None) -> list[AssetSpec]:
+def parse_assets(
+    raw_roles: str,
+    style_hint: str,
+    prompt_map: dict[str, str] | None = None,
+    role_lines: list[tuple[str, str]] | None = None,
+) -> list[AssetSpec]:
     specs: list[AssetSpec] = []
-    for role, prompt in parse_role_lines(raw_roles):
+    for role, prompt in role_lines if role_lines is not None else parse_role_lines(raw_roles):
         slug = slugify(role)
         is_background = any(word in slug for word in ("background", "backdrop", "scene", "map", "level"))
         width, height = (800, 450) if is_background else (128, 128)
@@ -1660,13 +1718,11 @@ def primary_diffusion_prompt(spec: AssetSpec) -> str:
             "Use connected environmental forms and clean terrain structure. No characters and no decorative overlay."
         )
     return (
-        f"{spec.prompt} Exactly one isolated subject only, centered, fully visible, with one pose and one view. "
-        "Do not repeat the subject and do not create a character sheet, turnaround, lineup, or alternate views. "
-        "Use a readable silhouette and derive its anatomy, body shape, camera angle, and pose directly from "
-        "the written description. "
-        "Use a plain uniform white studio background for clean extraction. "
-        "Add recognizable costume, equipment, materials, and character details. "
-        "No scenery, floor, trees, foliage, frame, or environmental props."
+        f"{spec.prompt} Production-ready isolated 2D game asset. A single centered subject fills roughly seventy "
+        "percent of a portrait frame. One complete body, one pose, and one strict camera direction are fully visible "
+        "with broad empty margin on every side. Derive the anatomy, body shape, pose, costume, equipment, materials, "
+        "and recognizable details directly from the written description. Use a plain uniform white studio field, a "
+        "readable silhouette, and a clean unlabeled presentation."
     )
 
 
@@ -1682,22 +1738,36 @@ def primary_diffusion_png(spec: AssetSpec, index: int, run_id: int) -> tuple[byt
     try:
         import torch
 
-        seed = abs(hash(f"primary|{spec.role}|{spec.prompt}|{index}|{run_id}")) % 2147483647
-        generator = torch.Generator(device="cuda").manual_seed(seed)
-        common = {
-            "prompt": primary_diffusion_prompt(spec),
-            "negative_prompt": diffusion_negative_prompt(spec),
-            "num_inference_steps": PRIMARY_IMAGE_STEPS if is_background_spec(spec) else PRIMARY_SPRITE_STEPS,
-            "guidance_scale": PRIMARY_GUIDANCE_SCALE,
-            "generator": generator,
-        }
-        width, height = (1344, 768) if is_background_spec(spec) else (1024, 1024)
-        image = PRIMARY_TEXT_PIPE(
-            width=width,
-            height=height,
-            **common,
-        ).images[0]
-        return polish_diffusion_asset(image, spec), None
+        is_background = is_background_spec(spec)
+        attempts = 1 if is_background else PRIMARY_SPRITE_ATTEMPTS
+        width, height = (1344, 768) if is_background else (768, 1024)
+        last_component_count = 0
+        for attempt in range(attempts):
+            seed = abs(hash(f"primary|{spec.role}|{spec.prompt}|{index}|{run_id}|{attempt}")) % 2147483647
+            generator = torch.Generator(device="cuda").manual_seed(seed)
+            image = PRIMARY_TEXT_PIPE(
+                prompt=primary_diffusion_prompt(spec),
+                negative_prompt=diffusion_negative_prompt(spec),
+                num_inference_steps=PRIMARY_IMAGE_STEPS if is_background else PRIMARY_SPRITE_STEPS,
+                guidance_scale=PRIMARY_GUIDANCE_SCALE,
+                generator=generator,
+                num_images_per_prompt=1,
+                width=width,
+                height=height,
+            ).images[0]
+            content = polish_diffusion_asset(image, spec)
+            if is_background:
+                return content, None
+
+            last_component_count = len(significant_foreground_component_areas(content))
+            if last_component_count == 1:
+                return content, None
+
+        if last_component_count > 1:
+            detail = f"the last output contained {last_component_count} significant foreground subjects"
+        else:
+            detail = "the last output did not contain one significant foreground subject"
+        return None, f"single-subject validation failed after {attempts} model attempts; {detail}"
     except Exception as exc:
         return None, short_error(exc)
 
@@ -1761,7 +1831,20 @@ def polish_diffusion_asset(image: Image.Image, spec: AssetSpec) -> bytes:
     if not is_background_spec(spec):
         # Text-to-image models do not produce real transparency. This makes sprites
         # usable by fading out colors similar to the generated corner background.
-        small = image.resize((128, 128), Image.LANCZOS)
+        # Preserve the model's portrait composition instead of stretching it square.
+        corner_source = image.resize((64, 64), Image.LANCZOS)
+        source_corners = [
+            corner_source.getpixel((0, 0)),
+            corner_source.getpixel((63, 0)),
+            corner_source.getpixel((0, 63)),
+            corner_source.getpixel((63, 63)),
+        ]
+        source_bg = tuple(sum(pixel[i] for pixel in source_corners) // len(source_corners) for i in range(3))
+        contained = image.copy()
+        contained.thumbnail((128, 128), Image.LANCZOS)
+        small = Image.new("RGBA", (128, 128), (*source_bg, 255))
+        offset = ((128 - contained.width) // 2, (128 - contained.height) // 2)
+        small.alpha_composite(contained, dest=offset)
         corners = [
             small.getpixel((0, 0)),
             small.getpixel((127, 0)),
@@ -1788,6 +1871,48 @@ def polish_diffusion_asset(image: Image.Image, spec: AssetSpec) -> bytes:
     return out.getvalue()
 
 
+def significant_foreground_component_areas(content: bytes) -> list[int]:
+    """Return material alpha components, ignoring small detached details and cleanup noise."""
+    image = Image.open(io.BytesIO(content)).convert("RGBA")
+    width, height = image.size
+    alpha = image.getchannel("A").tobytes()
+    foreground = bytearray(1 if value >= 64 else 0 for value in alpha)
+    areas: list[int] = []
+
+    for start in range(width * height):
+        if not foreground[start]:
+            continue
+        foreground[start] = 0
+        stack = [start]
+        area = 0
+        while stack:
+            current = stack.pop()
+            area += 1
+            x = current % width
+            y = current // width
+            for dy in (-1, 0, 1):
+                ny = y + dy
+                if ny < 0 or ny >= height:
+                    continue
+                for dx in (-1, 0, 1):
+                    if dx == 0 and dy == 0:
+                        continue
+                    nx = x + dx
+                    if nx < 0 or nx >= width:
+                        continue
+                    neighbor = ny * width + nx
+                    if foreground[neighbor]:
+                        foreground[neighbor] = 0
+                        stack.append(neighbor)
+        areas.append(area)
+
+    if not areas:
+        return []
+    largest = max(areas)
+    minimum = max(64, int(largest * 0.22), int(width * height * 0.005))
+    return sorted((area for area in areas if area >= minimum), reverse=True)
+
+
 def free_diffusion_png(spec: AssetSpec, index: int, run_id: int) -> tuple[bytes | None, str | None]:
     global FREE_DIFFUSION_PIPE, FREE_DIFFUSION_ERROR
     if FREE_DIFFUSION_ERROR:
@@ -2033,6 +2158,11 @@ def validate_asset_png(content: bytes, spec: AssetSpec) -> list[str]:
         )
         if any(value > 16 for value in corners):
             warnings.append("sprite has opaque corner pixels")
+        component_areas = significant_foreground_component_areas(content)
+        if not component_areas:
+            warnings.append("sprite has no significant foreground subject")
+        elif len(component_areas) > 1:
+            warnings.append(f"sprite contains {len(component_areas)} significant foreground subjects")
     return warnings
 
 
@@ -2171,8 +2301,9 @@ def model_configuration_summary() -> str:
         f"remote image fallback: `{remote_fallback}` · neural image models: `{neural_status}` · "
         f"neural enforcement: `{enforcement}` · primary readiness: `{readiness}`. "
         "Every production image is generated directly from its written prompt by the primary text-to-image model. "
-        "No procedural guide is supplied to the model. The procedural renderer is development-only and is blocked in "
-        "the deployed Space when the primary model fails."
+        "Sprite outputs must pass single-subject alpha-component validation and are regenerated with a new seed up to "
+        f"{PRIMARY_SPRITE_ATTEMPTS} times. No procedural guide is supplied to the model. The procedural renderer is "
+        "development-only and is blocked in the deployed Space when the primary model fails."
     )
 
 
@@ -2216,6 +2347,13 @@ def render_generation_state(state: dict, action: str, errors: list[str] | None =
         )
     if integration.warnings:
         status += "\n\n" + "\n".join(f"- {warning}" for warning in integration.warnings)
+    inferred_roles = state.get("inferred_roles", [])
+    if inferred_roles:
+        status += (
+            "\n\n- Added separate asset roles from deterministic game-code hooks: "
+            + ", ".join(inferred_roles)
+            + ". Add explicit descriptions for these roles to improve art direction."
+        )
     if errors:
         status += "\n\n" + "\n".join(f"- {error}" for error in errors)
     gallery = [
@@ -2260,8 +2398,12 @@ def generate_images_and_game(
         return empty_generation_result("Paste HTML game code first.")
 
     style_context = build_style_context(game_type, perspective, theme)
-    role_lines, prompt_map, prompt_model, prompt_error = build_prompt_map(html_code, roles, style_context)
-    specs = parse_assets(roles, style_context, prompt_map)
+    role_lines, prompt_map, prompt_model, prompt_error, inferred_roles = build_prompt_map(
+        html_code,
+        roles,
+        style_context,
+    )
+    specs = parse_assets(roles, style_context, prompt_map, role_lines)
     if not specs:
         return empty_generation_result(
             "Add at least one asset role, like `player: brave knight`.",
@@ -2304,6 +2446,7 @@ def generate_images_and_game(
         "prompt_model": prompt_model,
         "image_models": image_models,
         "quality": quality,
+        "inferred_roles": inferred_roles,
         "run_id": run_id,
     }
     rendered = render_generation_state(state, "Generated", errors)
@@ -2539,7 +2682,7 @@ with gr.Blocks(title="Image Generator for HTML Games") as demo:
               <h1>Turn your game code into a visual world.</h1>
               <p>Describe the art direction, generate camera-aware assets, and embed them into deterministic image hooks—without rewriting your game logic.</p>
               <div class="hero-chips">
-                <span>Camera-aware prompts</span><span>Game-ready PNGs</span><span>Safe code integration</span>
+                <span>Multiple character roles</span><span>Game-ready PNGs</span><span>Safe code integration</span>
               </div>
             </header>
             """
@@ -2566,7 +2709,10 @@ with gr.Blocks(title="Image Generator for HTML Games") as demo:
                     lines=8,
                     placeholder=ROLE_PLACEHOLDER,
                     value=DEFAULT_ROLES,
-                    info="One per line: role: image description",
+                    info=(
+                        "One separate role per character or asset, for example player, enemy_grunt, and enemy_boss. "
+                        "Missing deterministic GAME_ASSETS roles are added from the submitted code."
+                    ),
                 )
                 with gr.Row():
                     game_type = gr.Dropdown(