Log inGet started
← Explore
World media

Endless Stairs: Infinite Streamed Staircase and Themed Areas Kit

An infinite, seeded staircase that streams around whatever falls down it: 12 stair shapes (spiral, switchback, floating slabs, waterfall cascade...) through 10 storybook themed areas with props, lighting, fog, music and ambience. Invisible guards keep a tumbling ragdoll on course, a tumbling preset (steeper flights, rounded nosings, slippery treads), a camera corridor and camera fade, and a guided set-up workflow. Flat memory, local per peer.

0score
Embed

Embed this world

Paste this code into your own page and the world plays right there.

Updated Nov 17, 2026
endlessendless-runnerstairsstaircaseproceduralstreaminginfinitelevel-generatorthemeskit

endlessStairs: an infinite streamed staircase with ten themed areas

Endless Stairs builds an infinitely long, seeded staircase that streams in chunks around whatever is falling down it (a ragdoll, a ball, a runner, a camera) and recycles what is left behind, so a run of many kilometres keeps the same memory, entity count and frame time. Every few hundred metres the course passes through an archway into a new themed area with its own stair materials, props, lighting, sky, fog, ambience and music. It is made for endless-falling / endless-runner games (it powers Tumblestep: The Endless Stair) and for anyone who needs an endless course.

Art direction is a "storybook toy diorama": chunky, softly bevelled shapes, saturated palettes, warm key light and cool fill, stairs in calm mid values with a bright readable nosing on every step edge.

What changed in 1.2.0

  • Tumbling bodies stay on the course. Every wall run now carries an invisible guard (a collider-only sheet) up to guardHeight (2.6 m) above the rail line, and the switchback spine carries one too, so a tumbling ragdoll is turned back onto the stairs instead of rolling over a 1 m wall. The guards are a separate collider (endlessStairsGuard attribute) that is never drawn, so the camera still sees over the low walls. Floating-slab gaps keep their catch floors.
  • Tumbling-friendly geometry, opt in. slope (degrees) scales every drop so a standard flight has that pitch (36 keeps a ragdoll tumbling), landingPitch tilts landings downhill, roundNosings / nosingRadius round every step edge (in the collider too), stepFill puts invisible wedges in the step corners and treadFriction makes the treads slippery without changing the surface name a game plays sounds from; tumbling = true turns them all on as a preset.
  • Camera corridor. A box above and behind the stair centre line (cameraClearance, 6 m wide, 6 m high by default) is kept clear: wall-top lamps, candy canes, light poles and set-pieces that would reach into it are left out or stood further out, floating candles and hanging chains go above it, and the visible wall is capped at cameraClearance.rail (1.05 m). Set cameraClearance = false for the 1.1 dressing.
  • See the character through anything. course:occluders(cameraPos, characterPos) lists what stands in between (prop, set-piece, wall or gate, with its entity and box), and course:setCameraFade(cameraPos, characterPos) dithers away exactly the pixels of stairs, walls and props inside the camera-to-character capsule in the stair shader (no CPU cost).
  • Clean stone. The swirly contour lines on the rooftop stone are gone: UVs were wrapped per vertex at 512 m, so every tread straddling x = 0 squeezed hundreds of metres of pattern into one triangle. The UV origin is now wrapped once per mesh, and every pattern in stairSurface is filtered by its pixel footprint (joints widen and fine noise fades before it can alias into moire).
  • Sky dome winding. The inward sky sphere was wound outward against its own normals (the engine warned "winds 1840 of its 1920 triangles away from the normals" on every rebuild). Every runtime mesh the kit builds now winds with its normals (checked: 0 of 56,568 triangles over 18 chunk meshes, plus the dome).
  • New: Course.VERSION, the set-up-endless-stairs workflow (install, place, configure, verify), a sixth entity per chunk (the guard).

What changed in 1.1 (1.1.0, and 1.1.1 adding the stairSurface preview image)

  • Colliders fixed. On a recycled chunk the stairs collider kept the previous chunk's shape, so bodies fell through most of the course after the first few chunks. Colliders are now rebuilt for every chunk; 0 of 108 thin CCD capsules fired at 30-60 m/s (also on chunk seams) tunnelled.
  • Streaming keeps up with fast falls. Build-ahead, the forced range and the per-frame budget scale with the focus speed (0 misses at 60 m/s). New course:prewarmAsync(pos, onDone) and course:isReady() for a hitch-free restart.
  • New look for every theme. Retuned key/fill light, saturated skies with depth on the kit's own sky dome, fog only as distance haze and abyss colour, darker walls, mid-value treads, bright nosings; procedural surface detail with bump (wood, stone, carpet, candy glaze, ice, metal, neon glass, cloud-stone, mossy stone) from the new stairSurface shader.
  • Post you can turn down. Per-theme bloom + one-pass colour grade and vignette (stairGrade), no motion blur or DOF, fixed exposure; Themes.setPost({...}) for a graphics setting.
  • API to know: Themes.fogScale / sunScale / ambientScale now default to 1 (1.0.0's 0.35 / 1.25 / 0.5 are baked into the themes; a game that set them to the old defaults should remove those lines). Themes.useKitSky = false keeps a game's own sky. The sky dome is 700 m out (Themes.skyRadius): a camera far plane under ~750 m should lower it.

Quick start

local Course = require("endlessStairs.course")
local Themes = require("endlessStairs.themes")

local course = Course.new({ seed = 42 })          -- deterministic: same seed, same course
local start = course:startFrame()                  -- {pos, yaw, forward} on the top landing
course:on("areaEnter", function(a)
    Themes.playAudio(a.theme)                      -- music + ambience for this peer
end)

-- every frame:
course:update(character.position)                  -- streams ahead/behind, blends lighting

StairsDemo (component) is a complete example: put it on a camera entity and press play.

API: endlessStairs.course

Course.new(opts): opts:

fielddefaultmeaning
seed1the course; same seed = same course on every peer
origin{0,0,0}world position of the top step
yaw0overall heading (0 runs toward -Z)
areaLength300metres of course per themed area
themesall tenlist of theme ids in course order (repeats cyclically)
shapeWeightsbuilt in{ shape = weight }, 0 disables a shape
width4.4standard walking width in metres
ahead / behind80 / 40metres kept built in front / behind the focus
syncedfalseentities are always local; see Multiplayer
decoratenilfn(chunk) called for every spawned chunk
applyLightingtrueblend the scene's sun/sky/fog to each area on entry
propstruebuild the theme dressing
budgetMs3Luau build time per frame
catchUpMs8build time per frame while chunks within ~1.5 s of travel are still missing
autoRebasenilmetres from the origin past which the world shifts back
rise / run0.27 / 0.56standard step rise and tread depth
slopenildegrees: scale every drop so a standard flight has this pitch (e.g. 32-40 for a ragdoll that keeps tumbling)
landingPitch0degrees landings fall over their length (8 keeps a tumble going across them)
roundNosingsfalseround every step edge (radius 0.09 m, in the mesh and the collider)
nosingRadiusnilthe step-edge radius in metres (overrides roundNosings; the default edge is a 0.035 m chamfer)
treadFrictionnilfriction of the treads (the theme surface's other values and its name are kept)
stepFill00..0.9: an invisible collider wedge in the inner corner under every nosing (this share of the riser and of the tread below), so limbs cannot lock into the corners
tumblingfalsethe preset for a ragdoll that falls down the stairs: slope = 36, landingPitch = 12, roundNosings, stepFill = 0.6, treadFriction = 0.25, and no switchback, narrow or spiral flights (U-turn landings stop a passive tumble, a body jams across the narrow flight, the spiral's inner wedge ends are cliffs against its column); every value you pass yourself wins

Tumbling set-up used for Tumblestep-style games: Course.new({ seed = s, tumbling = true }).

Tumble test (1.2.0): an 11-segment, 70 kg jointed ragdoll (box torso, capsule limbs, ball joints) dropped and pushed down the course, side by side on several courses, about 1.6 km in total over every shape and the first four themes. Falls off the course (nothing of the course under it for 0.6 s while outside the walls or far below the stairs): 0. With the tumbling preset the doll kept moving on its own for most of the course (one kick every ~4.6 m on seed 23, 348 m, versus one every ~1.6 m on the default geometry); a passive doll still comes to rest on long landings and gate landings, so a game should keep nudging its tumbler down the course. | guards / guardHeight | true / 2.6 | invisible collider sheets on every wall and the switchback spine, this many metres above the rail line | | cameraClearance | {width = 6, height = 6, rail = 1.05, floor = 0.35} | the corridor over the centre line kept clear of dressing: width across, up to height above the rail line, starting floor above the visible wall, which is capped at rail; false turns it off |

Methods:

  • course:update(focusPos): call every frame. Streams chunks (spread over frames), recycles old ones, fires events, blends lighting.
  • course:prewarm(focusPos): build everything in range now, in one frame (a few hundred ms: use it behind a loading screen).
  • course:prewarmAsync(focusPos, onDone?, {budgetMs = 8, maxFrames = 600}) → cancel fn: build everything in range over the next frames, then call onDone(course). Use it for a restart ("Again") so the game never hitches; keep calling update meanwhile.
  • course:isReady(): true once every chunk in range of the last focus is built.

Streaming follows the focus speed: the course measures how fast the focus travels along it, builds ahead + 1.5 s × speed in front, forces the chunks within 12 m + 0.5 s × speed to finish now, and raises the per-frame budget to catchUpMs whenever a chunk within ~1.5 s of travel is missing. Measured: a focus flown at 60 m/s never reached an unbuilt chunk (0 misses under the focus or 25 m ahead over 440 frames).

  • course:startFrame() → {pos, yaw, forward} where a character stands on the top landing.
  • course:distanceAt(pos, hint?) → metres along the course nearest to a world position.
  • course:sample(dist) → {pos, forward, right, up, width, yaw, shape, theme} on the walking surface centre line.
  • course:areaAt(dist) → {index, theme, name, d0, d1}.
  • course:on(event, fn) → unsubscribe function. Events:
    • "chunkSpawned" (chunk): chunk = {index, area, theme, shape, d0, d1, root, slots}; slots = list of {dist, pos, forward, right, width, kind = "step"|"landing"|"gap"|"ramp", length}, one per tread / landing / ramp / gap, where other kits place trampolines, bumpers, coins…
    • "chunkDespawned" (chunk): remove what you placed (anything you parented under chunk.root is removed for you).
    • "areaEnter" ({index, theme, name, d0, d1}).
    • "rebase" ({delta}): the world shifted by -delta; move your own bodies and camera by -delta.
  • course:rebase(delta?): shift the world so delta (default: the focus) becomes the origin.
  • course:chunks(): live chunks in order; course:stats(): live/pooled chunks, entities, build timings (buildMsMax is a chunk's total build time across frames, uploadMsMax, updateMsAvg / updateMsMax / slowUpdates = this course's own cost per update), shift.
  • course:destroy(): removes every entity and mesh.

API: endlessStairs.themes

  • Themes.list() / Themes.get(id) → {id, name, description, surface, palette = {primary, secondary, accent, landing, wall, wallTop, gate, p1..p4, glowA, glowB, liquid, bg}, lighting = {sunColor, sunIntensity, sunDir, ambientColor, ambientIntensity, zenith, horizon, ground, stars, fogColor, fogSunColor, fogDensity, fogFalloff, bloom, exposure}, ambience = soundClip ref, music = soundClip ref}. Palette colours are sRGB.
  • Themes.apply(id, {blend = seconds}): blends the scene's sun, ambient, sky, height fog, bloom and colour grade.
  • Themes.setPost({enabled, strength, bloom, vignette, grade, exposure}): how much of the kit's post a game wants (wire it to a graphics setting): enabled = false removes bloom and grade from the chain, strength 0..1 fades both, bloom / vignette are multipliers, grade = false keeps bloom only, exposure is a fixed multiplier. Themes.getPost() reads it back. The kit never adds motion blur or depth of field and never adapts exposure. The grade is the kit's own stairGrade post shader (contrast, saturation, temperature gain, shadow lift, vignette in one pass); it does not use the engine's colorGrade/color_correction shaders.
  • Themes.useKitSky (true): draw the sky as the kit's dome: an inward sphere (Themes.skyRadius, 700 m; keep it inside your camera's far plane) whose vertex colours carry the theme's gradient, drawn unlit by stairSkyDome. The course keeps it centred on the focus (Themes.setSkyCenter(x, y, z) if you drive Themes yourself). Set it false before the first apply to keep your own sky; Themes.removeSky() takes the dome away. The scene's ProceduralSky colours are written either way.
  • Themes.setFogAnchor(y): keeps the haze centred on the action (the course does this).
  • Themes.playAudio(id, {fade, music, ambience, musicOn, ambienceOn}) / Themes.stopAudio(): this peer's music + ambience crossfade.
  • Themes.defineSurfaces(): registers the physics surfaces; Themes.fogScale, sunScale, ambientScale are global multipliers on the tuned look (1 = as tuned; they were 0.35 / 1.25 / 0.5 in 1.0.0, whose values are now baked into the themes).

Themes (ids)

idlooksurface
rooftopsterracotta steps over city roofs: chimneys, water towers, laundry lines, lit windows, peach sunsetstone
librarycrimson carpet with brass nosings between bookshelves, reading lamps, globes, floating candlescarpet
candyglossy icing steps, mint walls, gumdrops, lollipops, candy canes, cupcakes, donutscandy
hauntedgrey planks, pumpkin-orange edges, tombstones, jack-o'-lanterns, dead trees, ghost lights, nightwood
iceglassy ice steps with snow edges, crystals, icicles, pines, snowmen, peaksice
neondark glass steps with glowing edges, neon signs and towers, light poles, synthwave nightglass
cloudscloud-stone with gold trims, cloud banks, hot-air balloons, rainbows, pennantscloud
forgeiron steps with hot edges, lava channels, anvils, cauldrons, braziers, chains, smokestacksmetal
junglemossy temple steps, palms, ferns, vines, stone idols, firefliesstone
clockworkwalnut and brass, giant gears, clock faces, pendulums, pipesmetal

Every theme follows the same look rules: a strong warm key sun low enough to rake the treads, a cool, fairly dark fill, a saturated sky whose zenith is much darker than its horizon, height fog that starts 22-45 m out and pools in the void below (it is the colour of the abyss, never a veil over the stairs), dark walls, mid-value treads and a bright nosing on every step. Each theme also carries its grade (lighting.vignette, contrast, saturation, gain, lift, bloom) and sky extras (clouds, cloudColor, horizonGlow, fogStart).

Surface detail: the stairs, walls and props draw with the kit's stairSurface shader: the vertex colour is the paint, and the shader cuts analytic detail on top with a bump normal (rooftops dressed stone, library velvet carpet, candy glaze with sprinkles, haunted weathered boards, ice cracks and frost, neon glass tiles with a glowing grid, cloud-stone with gold veins, forge riveted brushed plate, jungle mossy temple stone, clockwork lacquered walnut). No texture memory is used; detail is read from path-space UVs the mesh builder writes, so it runs on across chunk seams and origin rebases.

Each theme ships materials under materials/ (<id>_solid, <id>_glowA, <id>_glowB, <id>_liquid) and generated audio under audio/ (amb_<id>, music_<id>).

Stair shapes

straight, grand (twice as wide, deep treads, urns), narrow (slim, tall walls), switchback (three flights round a central spine), spiral (two turns of wedge steps round a core column), curved (one sweeping arc), zigzag (S-bends), floating (slabs with gaps over glowing catch floors), terraces (big ledges), broken (cracked, chipped, sunken pieces), rampsteps (smooth ramps mixed with flights), cascade (wide treads with a waterfall stream down the middle), plus the gate landing with an archway that opens every area. Widths ease between shapes so walls never jump; every chunk starts exactly where the last one ended.

Physics

Each chunk's treads, risers, walls, column and spine are one merged mesh of closed volumes with one exact MeshCollider whose surface is the theme's surface (and the entity carries the attribute surface). Physics.defineSurface gives each surface its friction/bounce (ice slides, clouds and candy bounce, carpet grips). Fixed in 1.1.0: on a recycled chunk the collider kept the shape of the chunk the pooled entity drew before (bodies fell straight through most chunks after the first few); the collider is now rebuilt with every new mesh, after the entity is active. Tunnelling test (1.1.0): thin capsules (radius 0.06 m, CCD on and off) fired at 30, 45 and 60 m/s into treads, landings and exactly on chunk seams: 0 of 108 passed through any built chunk (the engine sweeps fast bodies against static colliders). A new chunk's collider takes a frame or two to exist, which is why the streaming keeps the chunks ahead built early. Visible walls are 1.05 m above the rail line (capped by cameraClearance.rail); since 1.2.0 an invisible guard collider on every wall run and on the switchback spine reaches guardHeight (2.6 m) above the rail line, so a tumbling body stays on course. The spiralx27s inner side is closed by its core column. Floating-slab gaps are intended and have a catch floor 0.32 m below the next slab, between the walls.

Performance

A chunk is 7 entities (root + stairs/collider, props, two glow meshes, liquid, invisible guard collider), about 5 draw calls and 2 colliders. 5-8 chunks are live at a time (about 42-56 entities). Building runs as a coroutine inside a per-frame budget (budgetMs, default 3 ms) with the GPU upload split across frames; entity sets are pooled and meshes are freed when replaced. Measured on desktop (1.0.0): about 60 fps steady with 5.7 ms engine CPU per frame. 1.1.0 adds one post pass (grade), one sky-dome draw (~2k triangles) and the procedural detail in the stair shader; the course's own update averaged 0.5-3 ms while streaming at 25 m/s in a dev build; the physics step averaged 1.35 ms with spikes up to ~11 ms on the frames a new chunk's exact collider is built. An endurance run of 1.75 km at 25 m/s through six areas with two rebases held at 5-7 live chunks and 42-48 course entities.

Multiplayer

All course entities are local and temporary (unsynced), so every peer streams its own course around its own character without touching anyone else's game. Because the layout is a pure function of the seed, two peers with the same seed see the same staircase. synced = true is not supported (runtime GPU meshes do not replicate); share the seed instead.

Large coordinates

The course descends forever (≈ 0.4 m per metre of course), so positions grow. Call course:rebase() or set autoRebase (e.g. 1500 m): the course shifts every live chunk and fires "rebase" with the delta so your bodies and camera move with it. Course distance (dist) is unaffected and stays exact in double precision.

Guides

  • how-to-make-an-endless-runner-track-that-streams-forever: how the streaming works and how to use it.
  • example-make-an-endless-falling-stairs-game: a small game built on it, step by step.

Comments · 0

Open discussion, no rating attached. Ask questions, swap notes, follow threads.

Sign in to join the discussion.

Documented parts · 6