ASCII Maps

RPU currently supports embedded ASCII maps directly inside scene files.

This is intentionally basic and is meant as a foundation for later terrain experiments.

Syntax

1map Terrain {2    origin = (80, 176)3    cell = (48, 48)4    render = basic5​6    legend {7        x = marker8        # = #c58c359        g = "tile-grass-top.png"10        - = #4dc7ff11        / = #7b8cff12        \ = #5970d813    }14​15    ascii {16        x17        ###/18          /----19             \##20    }21}

Current behavior

Current map support includes:

• origin
• cell
• render
• legend
• ascii
• color-mapped cells rendered as rects
• texture-mapped cells rendered as sprites
• marker cells used for sprite placement
• typed spawn markers used for entity placement
• solid collision rect generation for platformer physics
• terrain legend entries with topology + material parsing
• derived terrain shape classification for debug rendering

Shape Maps

shape_map is the first vector-map path for games such as pinball. It still uses an ASCII grid, but the cells define named control points instead of tile collision.

1shape_map Table {2    origin = (40, 40)3    cell = (8, 8)4    debug_labels = true5​6    legend {7        a = point("left_top")8        b = point("left_mid")9        c = point("left_bottom")10        l = point("lane_top", 0, -8)11        k = point("lane_bottom")12        r = point("lane_exit_edge")13        q = point("lane_exit_guide")14        x = point("bumper_left")15    }16​17    ascii {18        a......q.19        ........lr20        ....x...21        b.......22        c........k23    }24​25    wall LeftRail {26        points = [left_top, left_mid, left_bottom]27        corner = round28        radius = 1229        segments = 830        thickness = 531        color = #9ad8ff32        bounce = 0.933    }34​35    polyline PlayfieldBoundary {36        points = [left_bottom, left_mid, left_top, lane_exit_guide, lane_top]37        closed = false38        radius = 339        smooth = 840        corner = round41        corner_radius = 1642        segments = 1043        color = #9ad8ff44        bounce = 0.945    }46​47    pipe ShooterLane {48        points = [lane_top, lane_bottom]49        width = 2050        thickness = 451        color = #ffe08a52        bounce = 0.653    }54​55    sdf_wall ShooterExitGuide {56        points = [lane_exit_edge, lane_exit_guide, left_top]57        radius = 458        smooth = 859        corner = round60        corner_radius = 1261        segments = 862        color = #ffe08a63        bounce = 0.964    }65​66    bumper LeftBumper {67        point = bumper_left68        radius = 1369        color = #ff4f9a70        bounce = 1.771    }72​73    flipper LeftFlipper {74        pivot = left_bottom75        length = 3476        thickness = 577        rest_angle = 0.2878        active_angle = -0.5579        up_speed = 2480        down_speed = 1281        impulse = 1.2582        input = left83        color = #fff39a84        bounce = 1.4585    }86}

Current shape-map behavior:

• origin and cell define the control-point grid.
• cell can be non-square, for example (8, 36), to stretch a compact ASCII sketch over a taller playfield.
• debug_labels = true draws each authored point symbol at its resolved world position.
• legend maps ASCII symbols to named points with point("name").
• point("name", dx, dy) applies an optional world-space offset to a control point, useful when the ASCII grid is too coarse for final pinball tuning.
• wall connects named points into prototype polyline geometry.
• corner = round rounds interior wall corners; omit it or use corner = sharp for raw line segments.
• radius controls how far the rounded corner cuts back along each adjacent segment.
• segments controls how many short debug/render segments approximate each rounded corner.
• pipe creates two parallel wall rails from a named centerline. It is useful for launcher lanes, tubes, and other constrained ball paths.
• pipe.width is the rail-to-rail center distance; pipe.thickness, color, and bounce use the same meaning as walls.
• sdf_wall creates a smooth signed-distance wall from named points. Collision samples the SDF and uses the field gradient as the response normal.
• sdf_wall.radius is the wall radius, and smooth blends neighboring segments so bends are less brittle than raw polylines.
• sdf_wall also supports corner = round, corner_radius, and segments to round the authored polyline before SDF collision sampling.
• polyline is the same rounded SDF collision/render path as sdf_wall, but intended for larger authored boundaries. Use closed = true to connect the last point back to the first.
• bumper places prototype circular bumper geometry at a named point.
• flipper creates an input-driven pinball segment around a named pivot.
• rest_angle and active_angle are radians in world coordinates, where 0 points right and positive angles rotate downward.
• up_speed and down_speed control flipper angular motion in radians per second.
• impulse scales the extra velocity transferred from moving flippers into the ball.
• input can be left, right, up, down, action, or a concrete key name.
• bounce controls the restitution used by physics = pinball balls.

Pinball balls are regular sprites:

1sprite Ball {2    pos = (154, 72)3    size = (12, 12)4    collider_size = (12, 12)5    texture = "generated://circle/ball"6    physics = pinball7    gravity = 1808    max_speed = 4209}

physics = pinball treats the sprite collider as a circle and collides it against all shape-map walls and bumpers in the scene. generated://circle/... creates an internal circular alpha texture, so prototypes do not need a separate ball image asset.

Markers

Sprites can resolve their position from a symbol:

1sprite Player {2    symbol = x3    size = (144, 144)4    color = #ffd4475    script = "main.rpu"6}

Typed spawn markers bind a map cell to an entity name:

1map Terrain {2    legend {3        p = spawn(Player)4    }5​6    ascii {7        p8        ####9    }10}11​12sprite Player {13    physics = platformer14    texture = "foxy_idle1.png"15}

spawn(Player) places the scene sprite named Player at that map cell. This is often more readable than assigning a separate pos to the sprite.

Repeated spawn cells can instantiate hidden sprite definitions:

1legend {2    c = spawn(Coin)3    o = spawn(Opossum)4}5​6ascii {7    c   o   c8}9​10sprite Coin {11    visible = false12    group = "pickup"13    texture = ["gem-1.png", "gem-2.png"]14}

The runtime creates visible instances named from the template, such as Coin_1, Coin_2, and Opossum_1. This keeps collectible, enemy, and prop placement in the map instead of scattering positions through sprite definitions.

Direct Tiles

For tile-based games that do not want terrain synthesis, legend entries can map symbols directly to texture filenames and collision policies:

1map Terrain {2    origin = (0, 84)3    cell = (24, 24)4​5    legend {6        # = tile("tile-grass-top.png", solid)7        d = tile("tile-dirt.png", solid)8        - = tile("platform.png", one_way)9        b = tile("bush.png", none)10    }11​12    ascii {13         ----14    ############15    dddddddddddd16    b          b17    }18}

tile("name.png", policy) draws one sprite per map cell using the map cell size. This path is deterministic and does not use terrain classification, material stacks, WFC, or synthesized caps.

Collision policies:

• solid generates full AABB collision.
• one_way only collides when a platformer body lands from above.
• none draws the tile without collision.

Quoted texture entries such as # = "tile-grass-top.png" still work as a compatibility shorthand for a solid tile. Spawn and marker cells do not collide.

Current limits

The map system does not yet provide:

• tile rules
• procedural terrain generation
• slope semantics beyond authored symbols
• texture synthesis

That work is expected to grow later on top of the current embedded map representation.

Terrain Legend Entries

Map legend symbols can also represent terrain cells instead of only flat colors.

Examples:

1legend {2    # = rock3    # = grass>dirt>rock4    / = slope_up:grass5    \ = slope_down:grass6}

Current rules:

• bare material like rock means:
  • solid topology
  • material rock
• explicit forms are:
  • solid:rock
  • slope_up:grass
  • slope_down:grass
• stacked materials are also allowed:
  • grass>dirt>rock
  • solid:grass>dirt>rock
  • slope_up:grass>dirt>rock

Current stack behavior:

• top-facing outer surfaces use the first material
• side and underside outer surfaces fall back to the next material
• deeper cells step further into the stack by boundary distance

From those authored cells, RPU derives a neighborhood-based terrain shape such as:

• Top
• Left
• TopLeftOuter
• Interior

Right now terrain entries render as generated debug colors so these derived shape classes are visible while the system is still being built out.

Terrain Render Modes

Terrain maps can choose how the main terrain render/preview path behaves:

1map Terrain {2    origin = (80, 176)3    cell = (48, 48)4    render = basic5}

Supported values:

• debug
  • uses the structural debug-colored terrain view
• basic
  • uses the explicit cap/body terrain renderer
  • no WFC or solved surface strip is used
• synth
  • uses the current solved surface-cap path on top of the same body fill

This lets users keep the same topology/material authoring and choose later whether they want:

• pure debugging
• a simple non-synth terrain render
• or the experimental synthesized surface pass

Terrain Style Controls

Terrain maps can also tune the generated cap and shoulder shape:

1map Terrain {2    render = synth3    cap_depth = 0.684    ramp_cap_depth = 0.625    join_cap_depth = 0.726    shoulder_width = 0.827    surface_roughness = 0.0458    shoulder_shape = bend9}

Supported style properties:

• cap_depth
  • grass/cap thickness on flat top surfaces, as a fraction of tile height
• ramp_cap_depth
  • cap thickness on explicit / and \ ramp tiles
• join_cap_depth
  • cap thickness on plateau cells that connect to a ramp
• shoulder_width
  • how much of a plateau join cell is shaped by the ramp shoulder
• surface_roughness
  • small world-coordinate surface waviness applied to caps
  • 0.0 keeps authored terrain perfectly geometric
• shoulder_shape
  • linear for a straight shoulder
  • bend for a smoother eased shoulder

These controls affect basic and synth terrain rendering. They do not change the ASCII topology; they only change how the generated terrain surface is shaped and sampled.