Seedforge: Procedural Dungeons, Caves, Mazes and Islands from a Seed
README.md
procLevelKit 1.0.4: procedural levels from a seed
Give it a seed and it builds a level you can play: solid floors and walls you walk on and bump into, a start pad, an exit portal that is always reachable from the start, marked spots where enemies and loot can appear, and props spread by simple rules. The same seed gives the same level every time, for every player in a multiplayer game, after a restart and on the web build.
local ProcLevel = require("~procLevelKit.ProcLevel")
local level = ProcLevel.generate("dungeon", { seed = 7 })
Change the word to change the kind of level, and theme to change the look. The theme never moves anything.
procLevelKit is built on two shared kits, and installing it brings both:
- gridKit (grids and boards): every level is a gridKit board.
ProcLevel.board(level)hands you the gridKitBoardmodel of a level, and routes, move ranges and line of sight (ProcLevel.path,reach,canSee) are gridKit's. - spawnerKit (enemy spawners and waves):
level:spawnEnemies("MySpawner")puts a spawnerKit spawn point on every enemy spot and has the host spawn an enemy on each through your spawner, the same enemies for every player.
Try it in a fresh world (one minute)
- Install the package: search ZeroMind for "procLevelKit" and install
procLevelKit.package(zeromind_install guid=76d5ae78-3202-41e9-a84e-7d12e1566d77 at=/source, orzero zeromind installAsset 76d5ae78-3202-41e9-a84e-7d12e1566d77in the shell). It brings gridKit, spawnerKit (with the kits spawnerKit uses) and the material collections its themes wear. - Open
scenes/main.scene/entrypoint.luauand add at the bottom:
local ProcLevel = require("~procLevelKit.ProcLevel")
function onLoad()
ProcLevel.generate("dungeon", { seed = 7 })
end
- Press Play. You stand on the dungeon's start pad (a level puts its start on the world origin, where the default spawn is). Find the glowing portal.
Swap "dungeon" for "cave", "island" or any kind below, add theme = "scifi", change the seed. For pools and pits to show, delete the default scene's ground (it sits under the level).
Kinds (one call, change the name)
| kind | what you get | also answers to |
|---|---|---|
dungeon | rooms joined by corridors (spanning tree + a few loops) | rooms, roguelike |
cave | natural, organic cave (cellular automata), moss and pools | cavern, organic |
fortress | keep split into halls, chambers and a courtyard (binary space partition), doors in every split, pillared halls | keep, castle, bsp |
tiles | ruined village and temple from 7x7 pieces that fit their neighbours (wave function collapse) | village, temple, ruins, wfc |
runner | endless-runner lanes; with endless = true chunks keep appearing ahead of the player | track, endless, lanes |
island | island with sea, beach, grassland, rolling hills, palms and boulders | |
maze | maze with a few loops and chambers | labyrinth |
forest | dense wood with clearings joined by winding paths and a pond | woods |
Themes (one setting, layout unchanged)
crypt (Stone Crypt), scifi (Sci-Fi Station), ice (Frozen Ice Cavern), jungle (Overgrown Jungle Ruins), toon (Cartoon), retro (Retro Pixel). Each names materials of the materialLibraryKit library (stone, masonry, ground, woods, organic, sci-fi, fantasy, glass, toon and retro collections) at their real tile size, picks how trees, pillars and torches look, and its light colours. level:setTheme("ice") rebuilds the look of a built level in place. Add your own with ProcLevel.registerTheme { name = ..., surfaces = { floor = { id = "...", color = { r, g, b } }, ... } }.
The calls
ProcLevel.generate(kind, opts) -> levelplans and builds. Options:seed(any number, default 1),theme,lighting = true(adds the theme's sun, ambient light and sky),position(where the start pad stands, default the origin),anchor("start","center"or"corner"),cellSize(metres, default 2),wallHeight,enemies,loot(counts),props(rules, orfalse),showMarkers,showLoot,maxLights(default 64),fillLights(soft light in every open area of enclosed levels, default on), plus each kind's own (width,height,rooms,fill,size,lanes,chunks,endless, ...).ProcLevel.plan(kind, opts) -> datathe level as plain data, no entities:width,height,cells(one character each),start,exit,markers(enemy/loot),props.ProcLevel.build(data, opts) -> levelbuilds data you already have.ProcLevel.clear(level?)removes a level, or with no argument every level built here: every entity, collider, light and mesh it left behind.ProcLevel.toText(level)/ProcLevel.fromText(text)/ProcLevel.load(text, opts)levels as rows of characters (below).ProcLevel.scatter(data, rules, seed?)props by rules (below).ProcLevel.board(level, opts?)the level as a gridKitBoardmodel: square, cell (x, y) is (q, r), walls, water, trees and solid props blocked, slow ground (sand, hills) priced. Pieces, turns, ranges, save and load all work on it.ProcLevel.path(level, from?, to?)the cheapest walking route as{ x, y }cells, found by gridKit (start to exit by default).ProcLevel.reach(level, cell, budget)every cell withinbudgetsteps, as{ x, y, cost }(gridKit's movement range).ProcLevel.canSee(level, a, b)whether a straight line between two cells is clear of walls and trees.ProcLevel.spawnEnemies(level, spawner, opts?)(alsolevel:spawnEnemies(spawner, opts?)) spawnerKit spawn points on the enemy spots and one enemy on each, below.ProcLevel.hash(level)a short fingerprint of a level: equal hashes, equal levels.ProcLevel.registerKind(name, fn, description?)add your own kind.
A built level answers level:startPosition(), level:exitPosition(), level:spawnPoints() and level:lootPoints() (each { position, cell }), level:cellToWorld(x, y), level:worldToCell(pos), level:isAtExit(pos, radius?), level:lootNear(pos, radius?), level:takeLoot(i), level:setTheme(name), level:spawnEnemies(spawner, opts?), level:onClear(fn) and level:clear(). An endless runner answers track:update(playerPosition) each frame (builds chunks ahead, drops them behind).
Enemies with spawnerKit
local SK = require("spawnerKit.api")
-- in a scene's build.luau content(): one spawner, on a synced entity
SK.addSpawner(entity.spawnSynced("LevelSpawner"), { pattern = "point", behavior = "chase", autoStart = false })
-- in play, after generating:
local level = ProcLevel.generate("cave", { seed = 3, enemies = 6 })
level:spawnEnemies("LevelSpawner", { kinds = { "grunt", "runner" } })
Each enemy spot gets a spawnerKit spawn point (group = the spawner's name). In the first moments of play nobody owns the spawner yet, so asking "am I the host?" then can wrongly answer no; spawnEnemies waits until the host is settled, then the host spawns and everyone else stands down. Options: kinds (cycled over the spots, starting at offset), kind = function(i, spot) ... end, reset (default true: the spawner's earlier enemies go back to the pool first), pattern, timeout (seconds to wait for a host, default 15). It returns the job (state is "waiting", "spawned", "remote" or "timedOut"; points, enemies). Clearing the level removes its spawn points and returns its enemies to the pool. Give the spawner autoStart = false: a spawnerKit spawner with no waves otherwise starts an endless trickle of its own.
Levels as text
##########
#S..#...E#
#.c.#.e..#
#...+..$.#
##########
ProcLevel.load(text) builds this exactly as typed. Terrain: # wall, . floor, , path, : sand, " grass, ^ hill, ~ water, T tree or pillar, + door, space = nothing (a pit). Markers: S start, E exit, e enemy spot, $ loot. Props are lowercase letters: c crate, b barrel, t torch, r rubble, k rock, x crystal, m mushroom, u bush, l log, p statue, n banner, o pot, f bones. A typed level without S or E gets them placed for it. ProcLevel.toText(level) writes any level (generated or loaded) in the same form with a header (;proclevel kind=... seed=..., ;props ... and ;under ... for what lies under a marker), and loading that text gives back exactly the same level.
Props by rules
local data = ProcLevel.plan("cave", { seed = 3, props = false })
ProcLevel.scatter(data, {
{ name = "crystal", near = "wall", density = 0.06, spacing = 5 },
{ name = "rock", on = { ".", '"' }, density = 0.04, spacing = 2, solid = true },
}, 3)
local level = ProcLevel.build(data, { theme = "ice" })
A rule says name (its look comes from the theme), on (terrain characters or names, default floor), near (must touch one of: characters, "wall", "blocked", "open"), density (chance per cell), spacing (cells to the nearest prop of the same rule), max, solid (blocks movement; never placed where it would cut the level in two), awayFromStart and char (its letter in the text form). Every kind has sensible default rules (ProcLevel.DEFAULT_PROPS).
Multiplayer, restarts and the web
Layouts use only the engine's seeded Random, integer hashing (bit32) and exact arithmetic, never math.random, the clock or platform maths, so a seed gives the same level everywhere. Every entity a level builds is temporary (never saved into the scene) and unsynced: each player builds the level locally from the same (kind, seed, options), so all you share is those few values (a synced field or multiplayer.send). The test suite pins golden hashes of every kind.
What is inside
ProcLevel (the interface), generators (the eight kinds), place (start, exit, markers, scatter), board (the level as a gridKit board: routes, ranges, sight), enemies (enemy spots on spawnerKit), codec (text), grid (data and helpers), noise (cross-platform value noise), themes, build (merged runtime meshes per material with world-space UVs, one CompoundCollider of merged boxes, a HeightfieldCollider for the island, point lights, loot entities), the procLevelKit test suite, and two guides:
- How to generate procedural levels from a seed (
how-to-generate-procedural-levels-from-a-seed): procedural dungeon generator, random level from a seed, cave generator, maze, island, forest, runner, themes, text levels and props. - Make a roguelike dungeon crawl from an empty world (
make-a-roguelike-dungeon-crawl-from-an-empty-world): start at the entrance, enemies from the marked spots (spawnerKit), loot, the exit, and a new seed every floor.
Open them with man <name>, the guides tool or the Docs panel.
Known limits
- Levels are grid-based and single-storey (the island rolls but has no caves under it).
- Runtime mesh collision is boxes and a heightfield: thin decorative props (torches, mushrooms, bushes) do not collide; solid props, walls, trees and pillars do.
- Themes fall back to tinted engine materials for any library id that is not installed.
Version history
- 1.0.4 New store-listing description (what the kit gives a creator, how to install it and how to use it). No code or layout changes: every seed builds the same level as in 1.0.3.
- 1.0.3 Renamed from procLevel to procLevelKit (require
~procLevelKit.ProcLevel; the package keeps its guid). Built on the shared kits, which now install with it: levels are gridKit boards (ProcLevel.board,reach,canSee;pathruns on gridKit), andlevel:spawnEnemiesplugs enemy spots into spawnerKit. Fixes the empty first floor of the crawl guide: the crawl asked "am I the host?" in the first frame, before the spawner had an owner, got no, and never spawned;spawnEnemieswaits for the host to settle. Fixes untextured levels on the web: a level built before the material collections had arrived kept flat colours for good; misses are no longer cached and the level rebuilds its look as soon as its materials resolve (materialWait, default 120 s).level:setThemekeeps what hangs on the level (enemies, spawn points). - 1.0.2 Checked in a brand-new world by following this README and the dungeon crawl guide word for word. Crawl guide fixes: the spawner is added with
autoStart = false(without it spawnerKit runs an endless trickle and floods the floor with enemies), and the HUD panel sits inside a transparent full-screen root (as the root itself, its dark background covered the whole view). Enclosed levels get soft fill lights so no room is pitch dark;fillLights = falseturns them off, andmaxLightsnow defaults to 64. - 1.0.1 Install line in the README and guides names the package guid; the jungle theme's beaches are sand; islands carry fewer hill boulders (island layouts differ from 1.0.0 for the same seed; the golden hash moved with it).
- 1.0.0 First release: eight kinds, six themes, markers, prop rules, text levels, tests and two guides.