level_design - jonathanperis/super-mango-editor GitHub Wiki
Level Design β TOML Reference
Super Mango levels are defined as TOML files inside the levels/ directory. The game engine loads them at startup via level_loader.c; the level editor reads and writes the same format. All positions are in logical pixels (400Γ300 coordinate space).
TOML rule: All scalar key-value pairs must appear before any
[array tables](/jonathanperis/super-mango-editor/wiki/array-tables)in the file. The parser (tomlc17) will fail silently or error if arrays precede scalars.
Quick Start
# Run a level file directly
make run-level LEVEL=levels/00_sandbox_01.toml
# Open a level in the visual editor
make run-editor
# Then File β Open inside the editor
Top-Level Scalars
Every level file begins with these key-value pairs. All are required unless marked optional.
name = "Creator's Playground"
description = """
Optional multi-line description of the level.
"""
generated_by = "Author Name" # optional credit string
screen_count = 4 # world width = screen_count Γ 400 px
player_start_x = 79.0 # player spawn x in logical pixels
player_start_y = 124.5 # player spawn y in logical pixels
music_path = "assets/sounds/levels/water.wav"
music_volume = 13 # SDL_mixer volume 0β128
floor_tile_path = "assets/sprites/levels/grass_tileset.png"
initial_hearts = 3 # starting hit points
initial_lives = 3 # starting lives
score_per_life = 1000 # score at which a bonus life is awarded
coin_score = 100 # points per coin collected
floor_gaps = [0, 192, 560, 928] # world-space x positions of sea gaps
| Field | Type | Description |
|---|---|---|
screen_count |
int | Number of 400px-wide screens. 4 β world is 1600px wide. |
player_start_x/y |
float | Spawn position in logical pixels. |
music_path |
string | Path to WAV/OGG, relative to repo root. |
music_volume |
int | SDL_mixer channel volume: 0 (silent) β 128 (full). |
floor_tile_path |
string | PNG used to tile the ground. Per-level theming. |
floor_gaps |
int array | Sea gap x-positions. Blue flames spawn at each gap automatically. |
Rails
Rails define closed or open tracks that spike blocks and float platforms ride on.
[rails](/jonathanperis/super-mango-editor/wiki/rails)
layout = "RECT" # "RECT" = rectangular loop, "HORIZ" = horizontal line
x = 444 # top-left tile x in logical pixels
y = 35 # top-left tile y in logical pixels
w = 10 # width in tiles (for RECT)
h = 6 # height in tiles (for RECT)
end_cap = 0 # 0 = open end (rider detaches), 1 = capped end (rider bounces)
Rail layouts:
layout |
Shape | Typical use |
|---|---|---|
RECT |
Closed rectangular loop | Continuous-circuit spike blocks / float platforms |
HORIZ |
Open horizontal line | Spike block that bounces leftβright; w = length in tiles |
The end_cap flag only applies to open (HORIZ) rails. With end_cap = 1 the rider bounces back; with end_cap = 0 it falls off the far end as a projectile.
Platforms
Ground-level pillar columns. The player can land on the top surface only.
[platforms](/jonathanperis/super-mango-editor/wiki/platforms)
x = 80.0 # left edge of the pillar in logical pixels
tile_height = 2 # pillar height in 48px tiles (1 = 48px, 2 = 96px, 3 = 144px)
tile_width = 1 # pillar width in 48px tiles (usually 1)
Pillar top Y: FLOOR_Y β (tile_height Γ TILE_SIZE) = 252 β (tile_height Γ 48).
tile_height |
Top surface Y | Notes |
|---|---|---|
| 1 | 204 | Short hop |
| 2 | 156 | Standard β medium bouncepads clear this |
| 3 | 108 | Tall β requires high bouncepad or triple-jump |
Coins
[coins](/jonathanperis/super-mango-editor/wiki/coins)
x = 46.0 # centre-ish x in logical pixels (render width = 16px)
y = 236.0 # top edge y in logical pixels
Each coin is worth coin_score points (default 100). Every score_per_life points grants a bonus life.
Stars
[star_yellows](/jonathanperis/super-mango-editor/wiki/star_yellows)
x = 272.0
y = 108.0
[star_greens](/jonathanperis/super-mango-editor/wiki/star_greens)
x = 500.0
y = 80.0
[star_reds](/jonathanperis/super-mango-editor/wiki/star_reds)
x = 800.0
y = 100.0
Each star variant restores 1 heart on pickup. All are 16Γ16 px display size.
Last Star
[last_star]
x = 1492.0
y = 100.0
Single-instance. Triggers the level-complete event when collected. Displayed at 24Γ24 px.
Enemies
Spiders
Ground patrol enemy. Walks back and forth between patrol_x0 and patrol_x1.
[spiders](/jonathanperis/super-mango-editor/wiki/spiders)
x = 600.0 # starting x in logical pixels
vx = 50.0 # initial horizontal speed (px/s); sign sets direction
patrol_x0 = 592.0 # left patrol boundary
patrol_x1 = 750.0 # right patrol boundary
frame_index = 0 # starting animation frame (0β2)
Jumping Spiders
Variant that leaps across sea gaps. Same fields as spider.
[jumping_spiders](/jonathanperis/super-mango-editor/wiki/jumping_spiders)
x = 130.0
vx = 55.0
patrol_x0 = 46.0
patrol_x1 = 310.0
Birds
Slow sine-wave sky patrol. base_y is the vertical centre of the wave.
[birds](/jonathanperis/super-mango-editor/wiki/birds)
x = 100.0
base_y = 60.0 # vertical centre of the sine wave in logical pixels
vx = 45.0 # horizontal speed (px/s)
patrol_x0 = 0.0
patrol_x1 = 700.0
frame_index = 0
Faster Birds
Same schema as [birds](/jonathanperis/super-mango-editor/wiki/birds). Higher vx for more aggressive patrol.
[faster_birds](/jonathanperis/super-mango-editor/wiki/faster_birds)
x = 600.0
base_y = 50.0
vx = -80.0
patrol_x0 = 300.0
patrol_x1 = 1100.0
frame_index = 0
Fish
Water-lane patrol with random upward jumps.
[fish](/jonathanperis/super-mango-editor/wiki/fish)
x = 700.0
vx = 70.0
patrol_x0 = 500.0
patrol_x1 = 950.0
Faster Fish
Same schema as [fish](/jonathanperis/super-mango-editor/wiki/fish). Higher vx.
[faster_fish](/jonathanperis/super-mango-editor/wiki/faster_fish)
x = 1100.0
vx = 120.0
patrol_x0 = 900.0
patrol_x1 = 1400.0
Hazards
Axe Traps
Swinging or spinning axe mounted at the top of a platform pillar.
[axe_traps](/jonathanperis/super-mango-editor/wiki/axe_traps)
pillar_x = 256.0 # x of the platform column the axe is mounted on
y = 0.0 # pivot y (0 = top of pillar; engine computes exact Y from pillar)
mode = "PENDULUM" # "PENDULUM" = sinusoidal Β±60Β° swing | "SPIN" = full 360Β°
mode |
Behaviour | Period |
|---|---|---|
PENDULUM |
Swings β60Β° to +60Β° and back | 2 seconds per cycle |
SPIN |
Continuous clockwise rotation | 180Β°/s β one full rotation per 2 s |
Circular Saws
Fast horizontal patrol with constant spin. Does not use a rail.
[circular_saws](/jonathanperis/super-mango-editor/wiki/circular_saws)
x = 1350.0
y = 0.0 # engine snaps to floor level
patrol_x0 = 1350.0
patrol_x1 = 1446.0
direction = 1 # 1 = starts moving right, -1 = starts moving left
Patrol speed: 180 px/s. Spin speed: 720Β°/s. Pushes player on contact (220 px/s + β150 vy).
Spike Rows
Static strip of 16Γ16 spike tiles placed on the ground floor.
[spike_rows](/jonathanperis/super-mango-editor/wiki/spike_rows)
x = 780.0 # left edge of the strip in logical pixels
count = 4 # number of 16Γ16 tiles in the row
Spike Platforms
Elevated spike hazard surface.
[spike_platforms](/jonathanperis/super-mango-editor/wiki/spike_platforms)
x = 370.0
y = 200.0 # top edge in logical pixels
tile_count = 3 # number of tiles wide
Spike Blocks
Rail-riding hazard. References a rail by index (0-based order of [rails](/jonathanperis/super-mango-editor/wiki/rails) in the file).
[spike_blocks](/jonathanperis/super-mango-editor/wiki/spike_blocks)
rail_index = 0 # which rail to ride (0 = first [rails](/jonathanperis/super-mango-editor/wiki/rails) entry)
t_offset = 0.0 # starting position on the rail (0.0 = first tile)
speed = 1.5 # traversal speed in tiles per second
Blue Flames
Erupts from a sea gap. The engine automatically places one per gap; use this entry to override or add extras.
[blue_flames](/jonathanperis/super-mango-editor/wiki/blue_flames)
x = 192.0 # world-space x of the sea gap centre
Eruption cycle: waiting (1.5 s) β rising (β550 px/s launch) β flipping (180Β° over 0.12 s at apex) β falling β repeat.
Surfaces
Float Platforms
Hovering surfaces with three behaviour modes.
[float_platforms](/jonathanperis/super-mango-editor/wiki/float_platforms)
mode = "STATIC" # "STATIC" | "CRUMBLE" | "RAIL"
x = 172.0
y = 200.0
tile_count = 4 # platform width in 16px pieces
rail_index = 0 # only used for RAIL mode
t_offset = 0.0 # rail starting position (RAIL mode)
speed = 0.0 # rail traversal speed in tiles/s (RAIL mode)
mode |
Behaviour |
|---|---|
STATIC |
Hovers at fixed position forever |
CRUMBLE |
Falls after player stands on it for 0.75 s |
RAIL |
Travels along the referenced rail path |
Bridges
Tiled crumble walkway. Bricks fall when the player walks across.
[bridges](/jonathanperis/super-mango-editor/wiki/bridges)
x = 1350.0
y = 172.0
brick_count = 8 # number of 16Γ16 brick tiles
Bouncepads
Spring pads that launch the player vertically. Three size tiers.
[bouncepads_small](/jonathanperis/super-mango-editor/wiki/bouncepads_small)
x = 734.0
launch_vy = -380.0 # upward impulse in px/s (negative = up)
pad_type = "GREEN"
[bouncepads_medium](/jonathanperis/super-mango-editor/wiki/bouncepads_medium)
x = 310.0
launch_vy = -536.2
pad_type = "WOOD"
[bouncepads_high](/jonathanperis/super-mango-editor/wiki/bouncepads_high)
x = 1420.0
launch_vy = -700.0
pad_type = "RED"
| Array | pad_type |
Default launch_vy |
Clears |
|---|---|---|---|
bouncepads_small |
GREEN |
β380.0 | 1-tile pillars |
bouncepads_medium |
WOOD |
β536.25 | 2-tile pillars |
bouncepads_high |
RED |
β700.0 | 3-tile pillars |
Climbable Surfaces
Vines, ladders, and ropes are placed as vertical stacks of 16px tiles.
[vines](/jonathanperis/super-mango-editor/wiki/vines)
x = 88.0
y = 172.0 # top tile y in logical pixels
tile_count = 2 # height in 16px tiles
[ladders](/jonathanperis/super-mango-editor/wiki/ladders)
x = 1552.0
y = 0.0
tile_count = 30
[ropes](/jonathanperis/super-mango-editor/wiki/ropes)
x = 460.0
y = 172.0
tile_count = 1
The player can climb all three by pressing Up/Down while overlapping the surface. Vines and ropes require the player to jump into them; ladders are entered by pressing Up at the base.
Background & Foreground Layers
[background_layers](/jonathanperis/super-mango-editor/wiki/background_layers)
path = "assets/sprites/backgrounds/sky_blue.png"
speed = 0.0 # parallax scroll factor: 0.0 = static, 1.0 = locks to camera
[background_layers](/jonathanperis/super-mango-editor/wiki/background_layers)
path = "assets/sprites/backgrounds/glacial_mountains.png"
speed = 0.2
[foreground_layers](/jonathanperis/super-mango-editor/wiki/foreground_layers)
path = "assets/sprites/foregrounds/fog_1.png"
speed = 0.6
Layers are drawn in array order (first = furthest back). Up to 8 background layers are supported. Speed 0.0 tiles the image but doesn't scroll; speed 1.0 would scroll at the same rate as the camera (appears fixed in world space). Most parallax layers use 0.1β0.5.
Available background images in assets/sprites/backgrounds/:
| File | Suggested speed |
|---|---|
sky_blue.png |
0.0 |
sky_fire.png |
0.0 |
clouds_bg.png |
0.1 |
glacial_mountains.png |
0.2 |
volcanic_mountains.png |
0.2 |
forest_leafs.png |
0.3 |
clouds_mg_1/2/3.png |
0.3β0.5 |
clouds_lonely.png |
0.4 |
castle_pillars.png |
0.5 |
Minimum Valid Level File
name = "My Level"
screen_count = 2
player_start_x = 40.0
player_start_y = 200.0
music_path = "assets/sounds/levels/water.wav"
music_volume = 15
floor_tile_path = "assets/sprites/levels/grass_tileset.png"
initial_hearts = 3
initial_lives = 3
score_per_life = 1000
coin_score = 100
floor_gaps = []
[background_layers](/jonathanperis/super-mango-editor/wiki/background_layers)
path = "assets/sprites/backgrounds/sky_blue.png"
speed = 0.0
[last_star]
x = 760.0
y = 200.0
See levels/00_sandbox_01.toml for a full-featured reference level using every entity type.