# 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.
```luau
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 gridKit `Board` model 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)
1. Install the package: search ZeroMind for "procLevelKit" and install `procLevelKit.package` (`zeromind_install guid=76d5ae78-3202-41e9-a84e-7d12e1566d77 at=/source`, or `zero zeromind installAsset 76d5ae78-3202-41e9-a84e-7d12e1566d77` in the shell). It brings gridKit, spawnerKit (with the kits spawnerKit uses) and the material collections its themes wear.
2. Open `scenes/main.scene/entrypoint.luau` and add at the bottom:
```luau
local ProcLevel = require("~procLevelKit.ProcLevel")
function onLoad()
ProcLevel.generate("dungeon", { seed = 7 })
end
```
3. 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) -> level` plans 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, or `false`), `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) -> data` the level as plain data, no entities: `width`, `height`, `cells` (one character each), `start`, `exit`, `markers` (`enemy` / `loot`), `props`.
- `ProcLevel.build(data, opts) -> level` builds 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 gridKit `Board` model: 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 within `budget` steps, 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?)` (also `level: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
```luau
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
```luau
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`; `path` runs on gridKit), and `level:spawnEnemies` plugs 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; `spawnEnemies` waits 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:setTheme` keeps 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 = false` turns them off, and `maxLights` now 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.