Enforce camera perspective in background generation

README.md

@@ -31,10 +31,48 @@ If a requested role has no deterministic hook, assets are still generated for re
 
 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.
 
-The UI reports the configured prompt and image pipeline and labels every role with its actual source. Procedural generators provide predictable structure and real transparency but have limited open-ended semantic fidelity. Diffusion models provide more visual variety but are more likely to miss perspective, subject, background, or edge constraints; sprite outputs therefore receive alpha post-processing and still require visual approval. Background and sprite diffusion runs use different negative prompts so valid characters and vehicles are not accidentally excluded from sprite generation.
+The UI reports the configured prompt and image pipeline and labels every role with its actual source. Every asset now 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. The free procedural renderer also routes top-down and isometric backgrounds through dedicated geometry, so camera compliance does not depend only on prompt wording.
+
+Procedural generators provide predictable structure and real transparency but have limited open-ended semantic fidelity. Diffusion models provide more visual variety but are more likely to miss perspective, subject, background, or edge constraints; sprite outputs therefore receive alpha post-processing and still require visual approval. Background and sprite diffusion runs use different negative prompts so valid characters and vehicles are not accidentally excluded from sprite generation.
 
 The app combines the game type, perspective, theme, and pasted code into explicit per-role image prompts, then generates PNG assets and embeds contract-compatible assets as base64 data URIs.
 
-If the Space has an `HF_TOKEN` secret, it first uses the text model in `HF_PROMPT_MODEL` to interpret the code, roles, and theme into image prompts. The default prompt model is `Qwen/Qwen2.5-Coder-7B-Instruct`.
+If the Space has an `HF_TOKEN` secret and `USE_HF_PROMPT_PROVIDER=1`, it first uses the text model in `HF_PROMPT_MODEL` to interpret the code, roles, and theme into image prompts. The default prompt model is `Qwen/Qwen2.5-Coder-7B-Instruct`. The camera contract is appended after model interpretation, so the model cannot silently remove it.
+
+## Background generation tiers
+
+The default tier is deliberately free and deterministic:
+
+```text
+camera-aware procedural background
+```
+
+It runs on CPU Basic and is the active production-safe fallback. It fixes camera geometry, but it cannot match the semantic richness of a large image model.
+
+For a GPU Space, enable the production depth-control path:
+
+```text
+USE_CONTROLNET_FOR_BACKGROUNDS=1
+CONTROLNET_BASE_MODEL=stabilityai/stable-diffusion-xl-base-1.0
+CONTROLNET_MODEL=diffusers/controlnet-depth-sdxl-1.0-small
+CONTROLNET_STEPS=24
+```
+
+This constructs a camera-specific depth-like control image and runs SDXL with Depth ControlNet before falling back. It intentionally refuses to run on CPU-only hardware: loading SDXL on CPU Basic is not a credible interactive production configuration. The small ControlNet adapter is experimental, so perspective still needs human review.
+
+For an API-backed refinement that works from a CPU Space, enable:
+
+```text
+USE_HF_STRUCTURE_PROVIDER=1
+HF_STRUCTURE_MODEL=black-forest-labs/FLUX.2-klein-4B
+HF_STRUCTURE_PROVIDER=fal-ai
+HF_TOKEN=<Space secret with Inference Providers permission>
+```
+
+This sends the deterministic background as an image-to-image layout reference, asks the model to preserve its projection and walkable geometry, and falls back safely if the request fails. `FLUX.2-klein-4B` is Apache-2.0 licensed and available through a Hugging Face Inference Provider. It is not unlimited-free infrastructure: a free Hugging Face user currently receives only a small monthly inference credit, after which purchased credits are required. Keep the flag disabled unless paid API usage and token handling are acceptable.
+
+The older text-to-image fallback remains opt-in through `USE_HF_IMAGE_PROVIDER=1` and `HF_IMAGE_MODEL` (default `black-forest-labs/FLUX.1-schnell`). Unlike the structure-refinement tier, text-to-image receives no layout image and is therefore the weakest model option for strict camera compliance.
+
+If every enabled model path fails, the app uses the local style-aware Pillow fallback, which varies watercolor, vector/neon, claymation, oil-painting, anime, pixel-art looks, and common game sprite silhouettes.
 
-It then tries the image model in `HF_IMAGE_MODEL` for each role. The default image model is `black-forest-labs/FLUX.1-schnell`. Without `HF_TOKEN`, or if an API call fails, the app uses a local style-aware Pillow fallback that varies watercolor, vector/neon, claymation, oil-painting, anime, pixel-art looks, and common game sprite silhouettes.
+`black-forest-labs/FLUX.1-Depth-dev` is not configured here. Its gated 12B weights, non-commercial development license, and lack of a Hugging Face Inference Provider make it a poor fit for this Space and impossible to run credibly on CPU Basic. Black Forest Labs offers Depth Pro through its own API, which requires a separate provider account and billing rather than only the current free Hugging Face account.

app.py

@@ -92,6 +92,7 @@ class AssetSpec:
     filename: str
     width: int
     height: int
+    camera: str = "auto"
 
 
 @dataclass
@@ -121,11 +122,20 @@ USE_HF_PROMPT_PROVIDER = os.environ.get("USE_HF_PROMPT_PROVIDER", "0") == "1"
 USE_HF_IMAGE_PROVIDER = os.environ.get("USE_HF_IMAGE_PROVIDER", "0") == "1"
 USE_DIFFUSION_FOR_SPRITES = os.environ.get("USE_DIFFUSION_FOR_SPRITES", "0") == "1"
 USE_DIFFUSION_FOR_BACKGROUNDS = os.environ.get("USE_DIFFUSION_FOR_BACKGROUNDS", "0") == "1"
+USE_CONTROLNET_FOR_BACKGROUNDS = os.environ.get("USE_CONTROLNET_FOR_BACKGROUNDS", "0") == "1"
+CONTROLNET_BASE_MODEL = os.environ.get("CONTROLNET_BASE_MODEL", "stabilityai/stable-diffusion-xl-base-1.0")
+CONTROLNET_MODEL = os.environ.get("CONTROLNET_MODEL", "diffusers/controlnet-depth-sdxl-1.0-small")
+CONTROLNET_STEPS = int(os.environ.get("CONTROLNET_STEPS", "24"))
+USE_HF_STRUCTURE_PROVIDER = os.environ.get("USE_HF_STRUCTURE_PROVIDER", "0") == "1"
+HF_STRUCTURE_MODEL = os.environ.get("HF_STRUCTURE_MODEL", "black-forest-labs/FLUX.2-klein-4B")
+HF_STRUCTURE_PROVIDER = os.environ.get("HF_STRUCTURE_PROVIDER", "fal-ai")
 HF_IMAGE_MODEL = os.environ.get("HF_IMAGE_MODEL", "black-forest-labs/FLUX.1-schnell")
 HF_PROMPT_MODEL = os.environ.get("HF_PROMPT_MODEL", "Qwen/Qwen2.5-Coder-7B-Instruct:fastest")
 HF_PROMPT_ENDPOINT = os.environ.get("HF_PROMPT_ENDPOINT", "https://router.huggingface.co/v1/chat/completions")
 FREE_DIFFUSION_PIPE = None
 FREE_DIFFUSION_ERROR = None
+CONTROLNET_PIPE = None
+CONTROLNET_ERROR = None
 
 
 def slugify(value: str) -> str:
@@ -133,6 +143,44 @@ def slugify(value: str) -> str:
     return value or "asset"
 
 
+def normalize_camera(text: str) -> str:
+    """Convert UI and prompt camera wording into a stable generation contract."""
+    lowered = (text or "").lower()
+    explicit = re.search(r"required camera perspective:\s*([^.]*)", lowered)
+    camera_text = explicit.group(1) if explicit else lowered
+    if any(word in camera_text for word in ("top-down", "top down", "overhead", "bird's-eye", "birds-eye")):
+        return "top_down"
+    if any(word in camera_text for word in ("isometric", "3/4 view", "three-quarter")):
+        return "isometric"
+    if any(word in camera_text for word in ("side view", "side-view", "side-scroller", "side scroller", "platformer")):
+        return "side_view"
+    if any(word in camera_text for word in ("first-person", "first person")):
+        return "first_person"
+    if any(word in camera_text for word in ("front-facing", "front facing", "front view")):
+        return "front_view"
+    return "auto"
+
+
+def camera_prompt_contract(camera: str, is_background: bool) -> str:
+    if camera == "top_down":
+        if is_background:
+            return (
+                "Strict orthographic overhead composition viewed straight down. Show roofs, ground, paths, and "
+                "objects from above. No visible sky, no horizon line, no eye-level view, no front-facing facade, "
+                "and no vanishing-point perspective. Keep traversal space readable across the whole frame."
+            )
+        return "Strict overhead view of the subject from directly above; not front-facing and not side-view."
+    if camera == "isometric":
+        return "Consistent isometric three-quarter projection with parallel axes and no eye-level horizon."
+    if camera == "side_view":
+        return "Strict side-view profile composition suitable for a 2D platformer."
+    if camera == "first_person":
+        return "First-person viewpoint with environment geometry aligned to the player's eye line."
+    if camera == "front_view":
+        return "Front-facing composition with the subject or environment oriented toward the camera."
+    return "Use one internally consistent game camera angle appropriate to the role."
+
+
 def interpret_style_hint(style_hint: str) -> StylePlan:
     text = (style_hint or "").lower()
     tags: list[str] = []
@@ -198,24 +246,20 @@ def interpret_style_hint(style_hint: str) -> StylePlan:
         lighting = "balanced game lighting"
         linework = "clear readable silhouette and controlled edges"
 
-    if has("top-down", "top down", "overhead"):
-        camera = "top-down readable game camera"
-    elif has("platformer", "side-scroller", "side scroller"):
-        camera = "side-view platformer camera"
-    elif has("isometric", "3/4 view", "three-quarter"):
-        camera = "consistent isometric three-quarter game camera"
-    elif has("first-person", "first person"):
-        camera = "first-person game camera"
-    elif has("front-facing", "front facing"):
-        camera = "front-facing game camera"
-    else:
-        camera = "game-ready camera angle matching the role"
+    camera = {
+        "top_down": "top-down readable game camera",
+        "side_view": "side-view platformer camera",
+        "isometric": "consistent isometric three-quarter game camera",
+        "first_person": "first-person game camera",
+        "front_view": "front-facing game camera",
+    }.get(normalize_camera(style_hint), "game-ready camera angle matching the role")
 
     return StylePlan(medium, palette, texture, lighting, linework, camera, tuple(tags))
 
 
 def build_asset_prompt(role: str, prompt: str, style_hint: str) -> str:
     plan = interpret_style_hint(style_hint)
+    camera = normalize_camera(f"{style_hint} {prompt}")
     slug = slugify(role)
     is_background = any(word in slug for word in ("background", "backdrop", "scene", "map", "level"))
     if is_background:
@@ -234,6 +278,7 @@ def build_asset_prompt(role: str, prompt: str, style_hint: str) -> str:
         f"{role} asset: {prompt}. Creative brief: {style_hint}. "
         f"Style interpretation: {plan.medium}; {plan.palette}; "
         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."
     )
@@ -397,8 +442,25 @@ def parse_assets(raw_roles: str, style_hint: str, prompt_map: dict[str, str] | N
         is_background = any(word in slug for word in ("background", "backdrop", "scene", "map", "level"))
         width, height = (800, 450) if is_background else (128, 128)
         filename = f"sprite_{slug}.png"
-        full_prompt = (prompt_map or {}).get(role) or build_asset_prompt(role, prompt, style_hint)
-        specs.append(AssetSpec(role=role, prompt=full_prompt, filename=filename, width=width, height=height))
+        camera = normalize_camera(f"{style_hint} {prompt}")
+        interpreted_prompt = (prompt_map or {}).get(role)
+        if interpreted_prompt:
+            full_prompt = (
+                f"{interpreted_prompt}. Camera contract: {camera_prompt_contract(camera, is_background)} "
+                "Game asset, no text, no watermark."
+            )
+        else:
+            full_prompt = build_asset_prompt(role, prompt, style_hint)
+        specs.append(
+            AssetSpec(
+                role=role,
+                prompt=full_prompt,
+                filename=filename,
+                width=width,
+                height=height,
+                camera=camera,
+            )
+        )
     return specs
 
 
@@ -577,15 +639,170 @@ def apply_style_finish(content: bytes, spec: AssetSpec, rng: random.Random) -> b
     return out.getvalue()
 
 
+def finish_png(image: Image.Image) -> bytes:
+    out = io.BytesIO()
+    image.save(out, format="PNG")
+    return out.getvalue()
+
+
+def is_space_background_prompt(prompt: str) -> bool:
+    lowered = prompt.lower()
+    return any(
+        phrase in lowered
+        for phrase in ("outer space", "deep space", "starfield", "star field", "nebula", "galaxy", "cosmic")
+    )
+
+
+def draw_top_down_background(spec: AssetSpec, rng: random.Random) -> bytes:
+    """Draw an explicitly horizon-free overhead map for the free default path."""
+    prompt = spec.prompt.lower()
+    colors = palette_for(spec.prompt)
+    width, height = spec.width, spec.height
+
+    if any(word in prompt for word in ("sci-fi", "scifi", "arena", "metal", "space station", "shooter")):
+        image = Image.new("RGBA", (width, height), (18, 22, 31, 255))
+        draw = ImageDraw.Draw(image, "RGBA")
+        panel = 64
+        for y in range(0, height, panel):
+            for x in range(0, width, panel):
+                shade = 24 + ((x // panel + y // panel) % 2) * 12
+                draw.rectangle(
+                    (x, y, x + panel - 2, y + panel - 2),
+                    fill=(shade, shade + 4, shade + 14, 255),
+                    outline=(58, 74, 92, 170),
+                )
+        for x in range(0, width, 96):
+            draw.line((x, 0, x, height), fill=(34, 215, 236, 95), width=2)
+        for y in range(0, height, 96):
+            draw.line((0, y, width, y), fill=(34, 215, 236, 95), width=2)
+        return finish_png(image)
+
+    if any(word in prompt for word in ("garden", "flower", "grass", "meadow", "forest", "jungle", "path")):
+        image = Image.new("RGBA", (width, height), (64, 132, 70, 255))
+        draw = ImageDraw.Draw(image, "RGBA")
+        for _ in range(85):
+            x, y = rng.randint(0, width), rng.randint(0, height)
+            rx, ry = rng.randint(18, 70), rng.randint(12, 48)
+            draw.ellipse((x - rx, y - ry, x + rx, y + ry), fill=(78, rng.randint(135, 169), 76, 75))
+
+        path_points = [
+            (-40, int(height * 0.76)),
+            (int(width * 0.20), int(height * 0.66)),
+            (int(width * 0.43), int(height * 0.52)),
+            (int(width * 0.63), int(height * 0.37)),
+            (int(width * 0.83), int(height * 0.22)),
+            (width + 40, int(height * 0.13)),
+        ]
+        draw.line(path_points, fill=(112, 91, 59, 155), width=126, joint="curve")
+        draw.line(path_points, fill=(198, 169, 112, 255), width=108, joint="curve")
+        for _ in range(31):
+            edge = rng.choice(("top", "bottom", "left", "right"))
+            if edge in ("top", "bottom"):
+                x = rng.randint(-24, width + 24)
+                y = rng.randint(-28, 94) if edge == "top" else rng.randint(height - 94, height + 28)
+            else:
+                x = rng.randint(-28, 86) if edge == "left" else rng.randint(width - 86, width + 28)
+                y = rng.randint(-24, height + 24)
+            radius = rng.randint(24, 53)
+            draw.ellipse(
+                (x - radius, y - radius, x + radius, y + radius),
+                fill=(28, rng.randint(82, 116), 48, 255),
+                outline=(18, 70, 37, 210),
+                width=3,
+            )
+            inner = int(radius * 0.66)
+            draw.ellipse((x - inner, y - inner, x + inner, y + inner), fill=(58, rng.randint(126, 166), 69, 245))
+        for _ in range(42):
+            x, y = rng.randint(0, width), rng.randint(0, height)
+            radius = rng.randint(2, 5)
+            draw.ellipse((x - radius, y - radius, x + radius, y + radius), fill=rng.choice(colors) + (220,))
+        return finish_png(image)
+
+    if any(word in prompt for word in ("dungeon", "castle", "stone", "crypt")):
+        image = Image.new("RGBA", (width, height), (48, 50, 62, 255))
+        draw = ImageDraw.Draw(image, "RGBA")
+        tile = 54
+        for y in range(0, height, tile):
+            for x in range(0, width, tile):
+                shade = rng.randint(48, 78)
+                draw.rectangle(
+                    (x, y, x + tile - 2, y + tile - 2),
+                    fill=(shade, shade + 2, shade + 8, 255),
+                    outline=(27, 29, 38, 190),
+                )
+        return finish_png(image)
+
+    if any(word in prompt for word in ("lava", "fire", "volcano")):
+        image = Image.new("RGBA", (width, height), (52, 23, 18, 255))
+        draw = ImageDraw.Draw(image, "RGBA")
+        for _ in range(24):
+            x, y = rng.randint(-80, width), rng.randint(0, height)
+            points = [(x, y)]
+            for _ in range(rng.randint(2, 5)):
+                x += rng.randint(45, 125)
+                y += rng.randint(-45, 45)
+                points.append((x, y))
+            draw.line(points, fill=(255, 103, 35, 235), width=rng.randint(7, 15), joint="curve")
+            draw.line(points, fill=(255, 202, 64, 210), width=rng.randint(2, 5), joint="curve")
+        return finish_png(image)
+
+    if any(word in prompt for word in ("ocean", "sea", "water", "underwater")):
+        image = Image.new("RGBA", (width, height), (18, 114, 158, 255))
+        draw = ImageDraw.Draw(image, "RGBA")
+        for _ in range(42):
+            x, y = rng.randint(0, width), rng.randint(0, height)
+            rx, ry = rng.randint(18, 75), rng.randint(7, 25)
+            draw.ellipse((x - rx, y - ry, x + rx, y + ry), outline=(176, 236, 230, 95), width=3)
+        return finish_png(image)
+
+    image = Image.new("RGBA", (width, height), colors[2] + (255,))
+    draw = ImageDraw.Draw(image, "RGBA")
+    for _ in range(75):
+        x, y = rng.randint(0, width), rng.randint(0, height)
+        radius = rng.randint(8, 52)
+        draw.ellipse((x - radius, y - radius, x + radius, y + radius), fill=rng.choice(colors) + (rng.randint(45, 105),))
+    return finish_png(image)
+
+
+def draw_isometric_background(spec: AssetSpec, rng: random.Random) -> bytes:
+    """Draw a stable diamond-grid projection instead of an accidental horizon view."""
+    colors = palette_for(spec.prompt)
+    image = Image.new("RGBA", (spec.width, spec.height), colors[2] + (255,))
+    draw = ImageDraw.Draw(image, "RGBA")
+    tile_w, tile_h = 96, 48
+    for row in range(-2, spec.height // tile_h + 4):
+        for col in range(-2, spec.width // tile_w + 4):
+            cx = col * tile_w + (row % 2) * (tile_w // 2)
+            cy = row * (tile_h // 2)
+            diamond = [(cx, cy), (cx + tile_w // 2, cy + tile_h // 2), (cx, cy + tile_h), (cx - tile_w // 2, cy + tile_h // 2)]
+            shade = colors[(row + col) % len(colors)] + (115,)
+            draw.polygon(diamond, fill=shade, outline=colors[3] + (150,))
+    for _ in range(14):
+        cx, cy = rng.randint(40, spec.width - 40), rng.randint(45, spec.height - 55)
+        size = rng.randint(16, 35)
+        top = [(cx, cy - size), (cx + size, cy - size // 2), (cx, cy), (cx - size, cy - size // 2)]
+        left = [(cx - size, cy - size // 2), (cx, cy), (cx, cy + size), (cx - size, cy + size // 2)]
+        right = [(cx + size, cy - size // 2), (cx, cy), (cx, cy + size), (cx + size, cy + size // 2)]
+        draw.polygon(left, fill=colors[2] + (235,))
+        draw.polygon(right, fill=colors[0] + (235,))
+        draw.polygon(top, fill=colors[1] + (245,))
+    return finish_png(image)
+
+
 def draw_background(spec: AssetSpec, rng: random.Random) -> bytes:
     colors = palette_for(spec.prompt)
     image = Image.new("RGBA", (spec.width, spec.height), colors[2] + (255,))
     draw = ImageDraw.Draw(image, "RGBA")
     prompt = spec.prompt.lower()
 
+    if spec.camera == "top_down" and not is_space_background_prompt(prompt):
+        return draw_top_down_background(spec, rng)
+    if spec.camera == "isometric":
+        return draw_isometric_background(spec, rng)
+
     if (
         any(word in prompt for word in ("sci-fi", "scifi", "arena", "metal", "hazard", "grid", "shooter"))
-        and not any(word in prompt for word in ("space", "starfield", "nebula", "galaxy", "cosmic"))
+        and not is_space_background_prompt(prompt)
     ):
         image = Image.new("RGBA", (spec.width, spec.height), (18, 22, 31, 255))
         draw = ImageDraw.Draw(image, "RGBA")
@@ -620,7 +837,7 @@ def draw_background(spec: AssetSpec, rng: random.Random) -> bytes:
         image.save(out, format="PNG")
         return out.getvalue()
 
-    if any(word in prompt for word in ("space", "star", "nebula", "galaxy", "cosmic")):
+    if is_space_background_prompt(prompt):
         image = Image.new("RGBA", (spec.width, spec.height), (3, 4, 18, 255))
         draw = ImageDraw.Draw(image, "RGBA")
         for y in range(spec.height):
@@ -1085,10 +1302,119 @@ def diffusion_negative_prompt(spec: AssetSpec) -> str:
         "multiple objects, cropped subject, close-up surface, fabric swatch, text, watermark"
     )
     if is_background_spec(spec):
-        return common + ", person, character, player, hero, creature, monster, vehicle, mascot, foreground subject"
+        camera_negative = {
+            "top_down": ", sky, horizon, eye-level view, front view, front-facing facade, vanishing point",
+            "isometric": ", eye-level view, front view, inconsistent perspective, horizon",
+            "side_view": ", overhead view, top-down view, isometric view",
+        }.get(spec.camera, "")
+        return (
+            common
+            + ", person, character, player, hero, creature, monster, vehicle, mascot, foreground subject"
+            + camera_negative
+        )
     return common + ", landscape, environment scene, room, horizon, opaque background, drop shadow"
 
 
+def build_camera_control_image(spec: AssetSpec, width: int = 1024, height: int = 576) -> Image.Image:
+    """Create a deterministic depth-like layout that encodes the requested camera."""
+    image = Image.new("L", (width, height), 172)
+    draw = ImageDraw.Draw(image)
+    camera = spec.camera
+
+    if camera == "top_down":
+        # Overhead maps use local depth islands and a constant-width traversal path.
+        # There is deliberately no full-width horizontal boundary that could become a horizon.
+        path = [
+            (-60, int(height * 0.78)),
+            (int(width * 0.18), int(height * 0.66)),
+            (int(width * 0.43), int(height * 0.54)),
+            (int(width * 0.68), int(height * 0.34)),
+            (width + 60, int(height * 0.18)),
+        ]
+        draw.line(path, fill=205, width=150, joint="curve")
+        seed = random.Random(f"control|{spec.role}|{spec.prompt}")
+        for _ in range(24):
+            x, y = seed.randint(0, width), seed.randint(0, height)
+            radius = seed.randint(22, 62)
+            draw.ellipse((x - radius, y - radius, x + radius, y + radius), fill=seed.randint(55, 125))
+    elif camera == "isometric":
+        tile_w, tile_h = 128, 64
+        for row in range(-2, height // (tile_h // 2) + 3):
+            for col in range(-2, width // tile_w + 3):
+                cx = col * tile_w + (row % 2) * (tile_w // 2)
+                cy = row * (tile_h // 2)
+                value = 125 + ((row + col) % 3) * 30
+                diamond = [(cx, cy), (cx + tile_w // 2, cy + tile_h // 2), (cx, cy + tile_h), (cx - tile_w // 2, cy + tile_h // 2)]
+                draw.polygon(diamond, fill=value, outline=95)
+    elif camera == "side_view":
+        horizon = int(height * 0.55)
+        for y in range(height):
+            value = int(230 - 125 * (y / max(1, height - 1)))
+            draw.line((0, y, width, y), fill=value)
+        draw.rectangle((0, horizon, width, min(height, horizon + 18)), fill=70)
+        for x in range(0, width, 160):
+            draw.rectangle((x, horizon - 90, x + 75, horizon), fill=115)
+    else:
+        # Front/first-person guide: converging floor rays and a real horizon are intentional.
+        horizon = int(height * 0.48)
+        for y in range(height):
+            value = 225 if y < horizon else int(180 - 95 * ((y - horizon) / max(1, height - horizon)))
+            draw.line((0, y, width, y), fill=value)
+        vanishing = (width // 2, horizon)
+        for x in range(-width, width * 2, width // 6):
+            draw.line((x, height, *vanishing), fill=70, width=5)
+
+    return image.convert("RGB")
+
+
+def controlnet_background_png(spec: AssetSpec, index: int, run_id: int) -> tuple[bytes | None, str | None]:
+    """Run SDXL Depth ControlNet when a CUDA Space explicitly enables it."""
+    global CONTROLNET_PIPE, CONTROLNET_ERROR
+    if CONTROLNET_ERROR:
+        return None, CONTROLNET_ERROR
+    try:
+        import torch
+        from diffusers import ControlNetModel, StableDiffusionXLControlNetPipeline
+
+        if not torch.cuda.is_available():
+            return None, "SDXL ControlNet requires CUDA; CPU Basic is not a production-viable runtime"
+
+        if CONTROLNET_PIPE is None:
+            controlnet = ControlNetModel.from_pretrained(
+                CONTROLNET_MODEL,
+                variant="fp16",
+                use_safetensors=True,
+                torch_dtype=torch.float16,
+            )
+            CONTROLNET_PIPE = StableDiffusionXLControlNetPipeline.from_pretrained(
+                CONTROLNET_BASE_MODEL,
+                controlnet=controlnet,
+                variant="fp16",
+                use_safetensors=True,
+                torch_dtype=torch.float16,
+            )
+            CONTROLNET_PIPE.enable_model_cpu_offload()
+
+        width, height = 1024, 576
+        seed = abs(hash(f"controlnet|{spec.role}|{spec.prompt}|{index}|{run_id}")) % 2147483647
+        generator = torch.Generator(device="cuda").manual_seed(seed)
+        image = CONTROLNET_PIPE(
+            prompt=spec.prompt,
+            negative_prompt=diffusion_negative_prompt(spec),
+            image=build_camera_control_image(spec, width, height),
+            width=width,
+            height=height,
+            num_inference_steps=CONTROLNET_STEPS,
+            guidance_scale=6.5,
+            controlnet_conditioning_scale=0.65,
+            generator=generator,
+        ).images[0]
+        return polish_diffusion_asset(image, spec), None
+    except Exception as exc:
+        CONTROLNET_ERROR = short_error(exc)
+        return None, CONTROLNET_ERROR
+
+
 def polish_diffusion_asset(image: Image.Image, spec: AssetSpec) -> bytes:
     image = image.convert("RGBA")
     if not is_background_spec(spec):
@@ -1181,8 +1507,37 @@ def hf_image_png(spec: AssetSpec, index: int, run_id: int) -> tuple[bytes | None
         return None, short_error(exc)
 
 
+def hf_structure_background_png(spec: AssetSpec, index: int, run_id: int) -> tuple[bytes | None, str | None]:
+    """Refine the deterministic layout through a routed image-to-image provider."""
+    if not USE_HF_STRUCTURE_PROVIDER:
+        return None, None
+    if not HF_TOKEN:
+        return None, "HF_TOKEN is required for the routed structure-aware image API"
+    if InferenceClient is None:
+        return None, "huggingface_hub is not installed in this Space"
+
+    try:
+        source_png = local_asset_png(spec, index, run_id)
+        camera_instruction = camera_prompt_contract(spec.camera, True)
+        edit_prompt = (
+            "Polish this supplied game-background layout into production-quality 2D game art. "
+            "Preserve its camera projection, walkable-space geometry, and obstacle placement. "
+            f"{camera_instruction} Match this creative brief: {spec.prompt}"
+        )
+        client = InferenceClient(provider=HF_STRUCTURE_PROVIDER, api_key=HF_TOKEN)
+        image = client.image_to_image(
+            source_png,
+            prompt=edit_prompt,
+            model=HF_STRUCTURE_MODEL,
+        )
+        return polish_diffusion_asset(image, spec), None
+    except Exception as exc:
+        return None, short_error(exc)
+
+
 def generate_asset(spec: AssetSpec, index: int, run_id: int) -> tuple[str, str, str | None, str]:
-    if not is_background_spec(spec) and not USE_DIFFUSION_FOR_SPRITES:
+    is_background = is_background_spec(spec)
+    if not is_background and not USE_DIFFUSION_FOR_SPRITES and not USE_HF_IMAGE_PROVIDER:
         png_content = local_asset_png(spec, index, run_id)
         return (
             png_bytes_to_data_uri(png_content),
@@ -1190,7 +1545,15 @@ def generate_asset(spec: AssetSpec, index: int, run_id: int) -> tuple[str, str,
             None,
             "shape-aware 2D sprite generator",
         )
-    if is_background_spec(spec) and not USE_DIFFUSION_FOR_BACKGROUNDS:
+    background_models_enabled = any(
+        (
+            USE_CONTROLNET_FOR_BACKGROUNDS,
+            USE_HF_STRUCTURE_PROVIDER,
+            USE_DIFFUSION_FOR_BACKGROUNDS,
+            USE_HF_IMAGE_PROVIDER,
+        )
+    )
+    if is_background and not background_models_enabled:
         png_content = local_asset_png(spec, index, run_id)
         return (
             png_bytes_to_data_uri(png_content),
@@ -1199,20 +1562,42 @@ def generate_asset(spec: AssetSpec, index: int, run_id: int) -> tuple[str, str,
             "scene-safe 2D background generator",
         )
 
-    png_content, free_error = free_diffusion_png(spec, index, run_id)
-    source = FREE_IMAGE_MODEL
-    error = free_error
-    if png_content is None:
-        png_content, hf_error = hf_image_png(spec, index, run_id)
+    png_content = None
+    source = ""
+    errors: list[str] = []
+
+    if is_background and USE_CONTROLNET_FOR_BACKGROUNDS:
+        png_content, error = controlnet_background_png(spec, index, run_id)
+        source = f"{CONTROLNET_BASE_MODEL} + {CONTROLNET_MODEL}"
+        if error:
+            errors.append(f"ControlNet: {error}")
+
+    if png_content is None and is_background and USE_HF_STRUCTURE_PROVIDER:
+        png_content, error = hf_structure_background_png(spec, index, run_id)
+        source = f"{HF_STRUCTURE_MODEL} via {HF_STRUCTURE_PROVIDER}"
+        if error:
+            errors.append(f"structure API: {error}")
+
+    use_free_diffusion = USE_DIFFUSION_FOR_BACKGROUNDS if is_background else USE_DIFFUSION_FOR_SPRITES
+    if png_content is None and use_free_diffusion:
+        png_content, error = free_diffusion_png(spec, index, run_id)
+        source = FREE_IMAGE_MODEL
+        if error:
+            errors.append(f"local diffusion: {error}")
+
+    if png_content is None and USE_HF_IMAGE_PROVIDER:
+        png_content, error = hf_image_png(spec, index, run_id)
         source = HF_IMAGE_MODEL
-        error = hf_error or free_error
+        if error:
+            errors.append(f"text-to-image API: {error}")
+
     if png_content is None:
         png_content = local_asset_png(spec, index, run_id)
         source = "local procedural fallback"
     return (
         png_bytes_to_data_uri(png_content),
         write_gallery_image(png_content, spec.role),
-        error if source == "local procedural fallback" else None,
+        "; ".join(errors) if source == "local procedural fallback" and errors else None,
         source,
     )
 
@@ -1369,20 +1754,45 @@ def model_source_note(image_model: str) -> str:
     lowered = image_model.lower()
     if "shape-aware" in lowered or "scene-safe" in lowered or "procedural" in lowered:
         return "procedural/heuristic output—predictable structure, limited open-ended semantic fidelity"
+    if "controlnet" in lowered:
+        return "depth-controlled diffusion—stronger camera structure; still requires visual perspective review"
+    if "via fal-ai" in lowered or "via replicate" in lowered:
+        return "routed image-to-image refinement—preserves a layout guide but consumes account inference credit"
     return "diffusion output—higher visual variety; verify subject, perspective, alpha edges, and prompt compliance"
 
 
 def model_configuration_summary() -> str:
     prompt_source = HF_PROMPT_MODEL if USE_HF_PROMPT_PROVIDER else "local prompt interpreter"
-    sprite_source = FREE_IMAGE_MODEL if USE_DIFFUSION_FOR_SPRITES else "shape-aware procedural generator"
-    background_source = FREE_IMAGE_MODEL if USE_DIFFUSION_FOR_BACKGROUNDS else "scene-safe procedural generator"
-    remote_fallback = HF_IMAGE_MODEL if USE_HF_IMAGE_PROVIDER else "disabled"
+    sprite_chain = []
+    if USE_DIFFUSION_FOR_SPRITES:
+        sprite_chain.append(FREE_IMAGE_MODEL)
+    if USE_HF_IMAGE_PROVIDER:
+        sprite_chain.append(HF_IMAGE_MODEL)
+    sprite_chain.append("shape-aware procedural fallback")
+    sprite_source = " → ".join(sprite_chain)
+    background_chain = []
+    if USE_CONTROLNET_FOR_BACKGROUNDS:
+        background_chain.append(f"{CONTROLNET_BASE_MODEL} + {CONTROLNET_MODEL}")
+    if USE_HF_STRUCTURE_PROVIDER:
+        background_chain.append(f"{HF_STRUCTURE_MODEL} via {HF_STRUCTURE_PROVIDER}")
+    if USE_DIFFUSION_FOR_BACKGROUNDS:
+        background_chain.append(FREE_IMAGE_MODEL)
+    if USE_HF_IMAGE_PROVIDER:
+        background_chain.append(HF_IMAGE_MODEL)
+    background_chain.append("camera-safe procedural fallback")
+    background_source = " → ".join(background_chain)
+    remote_sources = []
+    if USE_HF_STRUCTURE_PROVIDER:
+        remote_sources.append(f"{HF_STRUCTURE_MODEL} via {HF_STRUCTURE_PROVIDER}")
+    if USE_HF_IMAGE_PROVIDER:
+        remote_sources.append(HF_IMAGE_MODEL)
+    remote_fallback = " → ".join(remote_sources) if remote_sources else "disabled"
     return (
         "**Configured model pipeline:** "
         f"prompts: `{prompt_source}` · sprites: `{sprite_source}` · backgrounds: `{background_source}` · "
         f"remote image fallback: `{remote_fallback}`. "
-        "Procedural output is structurally predictable but semantically limited; diffusion output is more varied "
-        "and therefore requires stricter visual review."
+        "Every background carries an explicit camera contract. The free procedural path enforces that contract "
+        "deterministically; model-based refinements are more varied and still require visual perspective review."
     )