Skip to content

Custom levels

Custom overlays are WIP

Custom levels that ship their own code overlay are a work in progress. The engine will load them into game memory, but they are not currently recompiled and executed.

A [[level]] block plus two files under assets/levels/ makes a playable custom level with no C. The engine claims the level slot, declares the WAD table-of-contents entry, serves the files when the game streams the level, and restores everything when the mod is disabled.

[[level]]
name  = "Grim Garden"      # menu name and sort key; also the in-game title
files = "grim_garden"      # stem: assets/levels/grim_garden.WAD + .OVL
donor = "dark_hollow"      # level whose code the hack was authored against:
                           # lower_snake name or numeric id 10..64
replace = true             # optional: serve over the donor's own level
music = "grim_garden.wav"  # optional: the level's own song, from assets/music/
title = "GRIM GARDEN"      # optional: in-game title when it differs from name
  • <stem>.WAD is the level's data segment and can be any size. <stem>.OVL is the donor's code overlay and must keep the donor's stock size. Omit the overlay to run the stock one. Extension case does not matter.
  • Up to 4 [[level]] blocks per mod.
  • Custom levels from every mod currently share level slot ID 65, so per-level progress (gems, dragons) is shared between them. replace = true takes over the donor's slot instead, and the donor's homeworld portal preview then shows the custom level's own skybox, parsed from the .WAD file.
  • Without music, the level plays the donor's track. With it, the engine plays the WAV whenever the level starts its music and sizes the game's loop bookkeeping to the file's length. Format: see Music.
  • name appears in the inventory rows, on the entry title card, and in the homeworld portal's floating letters (in replace mode, in place of the donor's name). Names are filtered to A-Z, 0-9, space, and ! , ? . '. The portal letters render A-Z, 0-9, and .; other characters render as an apostrophe there. Set title when the in-game string should differ from the menu name.

In play

The M overlay's Mods section shows one row per level, with a Warp button, a switch between own-slot and replace-donor mode, and a tooltip naming the level's Custom World number and donor. Levels from all mods sort alphabetically, five per world.