Platformer scenes

The original forge.generate_platformer_level tool builds a tilemap-based level: tile grid, painted cells, schematic. It’s right for top-down levels (forest, dungeon, cave) and for users who want a paintable cell grid in the editor afterward. It’s wrong for platformer-perspective art with painted parallax — the solid tile blocks read as schematic, the parallax reads as art, and the two sit at different stylistic registers.

forge.generate_platformer_scene is the side-scrolling alternative. Painted ground silhouette + entity spawn points + parallax. No tile grid. The output sits naturally over painted parallax because the ground itself is painted at the same register.

When to reach for which

generate_platformer_level — top-down levels (forest / dungeon / cave), or platformer prototypes where you want to keep painting individual tiles in the tilemap editor afterward. The classic Tiled workflow.
generate_platformer_scene — side-scrolling platformer art. Painted ground silhouette, entity spawn points placed along the ground curve, parallax in the back. No paintable tile grid; you tweak by re-running with a different seed or by handing the agent a custom ground PNG.

The agent’s forge-self skill steers platformer asks toward the scene tool now. You don’t need to specify which one — saying “build me a forest platformer with parallax” picks the scene tool automatically.

The chain

1. (4× image-generation calls — sky, far hills, mid hills, foreground)
   forge.generate_parallax_layers(layers=[sky, hills, mid, fg])
   → savedPath C (parallax descriptor + thumbnail)
   → forge-link card #1: "Forest parallax · 4 layers"

2. (8× image-generation calls — hero idle/run frames)
   forge.generate_spritesheet(frames=[idle1, ..., run4])
   → savedPath D (packed sheet)
   → forge-link card #2: "Hero sheet · 8 frames"

3. forge.generate_platformer_scene(
     theme="forest",
     width=2400, height=360,
     parallax_path=C,
     character_sheet_path=D,
   )
   → savedPath F (scene descriptor + ground PNG + thumbnail)
   → forge-link card #3: "Forest scene · 12 entities · parallax · character"

Three cards in chat. Click card #3 → the platformer scene preview tab opens with parallax in the back, painted ground curving across the viewport, coins floating ~40 px above the ground line, two floating platforms placed mid-jump-height, an exit at the far right. Drag to pan; the parallax layers crawl at their own scroll multipliers, the ground pans 1:1, the character sticks at its spawn point.

Themes

The theme argument picks the palette tint for the procedural ground and the fallback sky gradient (when no parallax is supplied):

forest — deep blue → light blue sky, green grass top → dark green fill, brown rock dots. The default.
desert — purple → orange sky, golden grass top → sandstone fill.
canyon — dusk red → sunset orange sky, rust ground → red rock fill.
factory (alias scifi) — near-black sky → slate, gray ground → graphite fill.
cave-side (alias cave) — near-black sky → purple, dark slate ground → dark fill.
snow (alias tundra) — slate-blue sky → near-white sky, pure white top → light grey fill.

The parallax style (sunset / dusk / etc.) lives in the parallax descriptor — pick a parallax look that complements the ground theme, or generate it after the scene to match.

Two ways to source the ground

Procedural (default, fast)

Omit ground_path. Forge generates a multi-octave-noise terrain curve and paints it with the theme palette:

forge.generate_platformer_scene(theme="forest", width=2400, height=360)

The terrain curve is reproducible — pass seed=12345 to get the same shape every time, or omit seed for a fresh layout each call.

Custom painted ground (more control)

For art-directed scenes, generate the ground PNG separately via Codex’s image tool first, then pass the saved path as ground_path:

1. Codex's built-in image-gen → "Side-on platformer ground silhouette,
   forest theme, transparent sky on top half, opaque painted ground
   filling bottom half with natural undulations, broken stone outcrops,
   no characters or props, no parallax background"
   → ~/.forge/generated/<timestamp>.png

2. forge.generate_platformer_scene(
     theme="forest",  // still controls the sky/sky-fallback gradient
     ground_path="<that path>",
     parallax_path=C,
     character_sheet_path=D,
   )

When ground_path is supplied:

Forge skips the procedural generator and uses the painted PNG as the canonical ground.
The painted image’s natural dimensions become the scene size — the width and height args are ignored.
Entity placement reads the alpha channel column-by-column to find the actual painted edge, so coins/platforms/spikes/the exit still rest on the visible ground line. Spawn points feel “tied to the painting” rather than landing in arbitrary spots.

A typical custom-ground PNG is 2400×360 or wider, with the ground filling the bottom 30–60% of the image and transparent above. The agent’s skill copy includes a prompt template you can copy verbatim.

Entities

Each scene descriptor includes an entities array of typed spawn points. The renderer draws them inline (coins are gold dots, platforms are pale blue rectangles, spikes are red triangles, the exit is a turquoise door):

{ "type": "coin", "x": 320, "y": 200 }
{ "type": "platform", "x": 480, "y": 180, "w": 96, "h": 14 }
{ "type": "spike", "x": 800, "y": 240 }
{ "type": "exit", "x": 2200, "y": 220 }

Entity counts scale with scene width: roughly one coin per 240 px, one platform per 480 px, one spike per 800 px, plus exactly one exit at the far right. Pass seed to keep entity placement reproducible alongside the terrain.

The descriptor is plain JSON, so you can hand-edit entities after the fact if you want a specific layout — or pipe it into your engine’s level loader.

Re-opening + iterating

Click any open scene’s “Reveal descriptor” button to find the JSON on disk. Edit it manually, save, then re-click the forge-link in chat to re-load. The preview tab consumes the descriptor on every open, so in-place edits show up without re-generating.

For a different ground curve: re-run the tool with a new seed. For a different parallax style: regenerate parallax separately, then re-run the scene with the new parallax_path. The descriptor refs are absolute paths, so swapping is straightforward.