A scripting language for procedural level generation. Programs transform a stack of correlated grids through pattern-rewrite rules; output is a pure function of (seed, params).
LevelScript is the successor of the MGSL experiment (../mgsl), reimplemented
with its lessons applied and an embedding API designed for games first.
tag geo { wall, floor }
layers {
level: grid of geo
}
rule fill {
level[.]
=>
level[floor]
}
sequence main {
resize(8, 4)
everywhere fill
}
auto gen = ls::generator::compile(source, "dungeon.lvs", resolve); // resolve maps `use` paths
auto level = gen.generate(gen.sequence("main"), seed);
auto geo = level["level"];
int wall = gen.tag("geo.wall");
if (geo.at(x, y) == wall) ...Installers for Windows and macOS are attached to every
release. Both install
levelscript and levelscript-debugger and add them to your PATH; open a new
terminal afterwards.
To build them yourself:
- Windows:
python packaging/windows/build_installer.pybuilds a per-user installer (needs Inno Setup 6.3+) atdist/LevelScript-setup-<version>-x64.exe. - macOS:
python packaging/macos/build_pkg.pybuilds an Apple Silicon (macOS 11+) package atdist/LevelScript-<version>-macos-arm64.pkg. It installs to/usr/local/levelscriptand putsbin/on PATH via/etc/paths.d. The package is unsigned: the first time, allow it under System Settings > Privacy & Security > Open Anyway. Uninstall withsudo /usr/local/levelscript/uninstall.sh.
Compiles a .lvs file, runs one sequence and prints every layer as text.
levelscript [--seed N] [--entry name] [--param name=value ...] [--inspect | --profile] <file.lvs>
levelscript --ast [--no-spans] <file.lvs>
| Option | Meaning |
|---|---|
--seed N |
Seed for the run. The output is a pure function of (seed, params); omitted, a random seed is used. |
--entry name |
Sequence to run (default main). If it doesn't exist, the available sequences are listed. |
--param name=value |
Set an integer parameter; repeatable. |
--inspect |
Don't run; print a JSON report (diagnostics, symbols) for editor tooling. |
--profile |
Run once and print, instead of the level, the time and rule applications spent in each statement (sequences include their bodies). |
--ast |
Don't run; print the file's syntax tree, each node with its source range. --no-spans leaves the ranges out. The file is parsed alone; its uses are not followed. |
levelscript --seed 42 samples/games/roguelike/roguelike.lvs
levelscript --seed 7 --param difficulty=2 tests/golden/programs/arena.lvs
Compile errors and warnings go to stderr; a compile error exits with 1.
use paths are resolved relative to the importing file.
An interactive window over the same program: step through the generation one rule application at a time and watch the layers change.
levelscript-debugger [--seed N] [--entry name] [file.lvs]
Without a file the window opens empty: open a script with the folder button
(Ctrl+O, Cmd+O on macOS) or by dropping a .lvs file on the window.
Breakpoints are set by clicking the gutter next to a statement in the code view (red dot). Keys follow VS Code:
| Key | Action |
|---|---|
F5 |
Run / continue to the next breakpoint |
F6 |
Pause |
F10 |
Step over: finish the statement, called sequences included |
F11 |
Step into: one rule application |
Shift+F11 |
Step out: finish the current sequence |
Ctrl+Shift+F5, R |
Restart |
Space |
Toggle timed playback |
Q |
Quit |
Per-layer display settings (text or tileset, opacity, visibility, zoom,
background colour) are saved next to the script as <file>.lvs.json
(see samples/games/roguelike/roguelike.lvs.json). The theme, window geometry and seed are
remembered per user.
cmake -S . -B build
cmake --build build --config Debug --parallel
build/tests/Debug/ls_tests.exe
python tools/run_goldens.py
Single-config generators (Makefiles, Ninja) default to RelWithDebInfo; pass
-DCMAKE_BUILD_TYPE=Debug for an unoptimized build. Generation runs about 10x
slower at -O0.