nihilurk

nihilurk is a free, open-source Rogue-like (roguelike) for the terminal, written in Rust. A Rogue retroclone about descending thirteen floors, taking the Element of Yoord off the Dungeon Lord, and carrying it back up. Life is unfair and death is permanent. Terminal only, one binary, no assets, a lot of punch.

If you’re enjoying nihilurk, buy me a coffee.

What you get:

• A classic roguelike on a turn-based grid: thirteen floors, traps, gear of unknown quality, and permanent death. There is one save, and it is deleted when an expedition ends.
• Auto-explore (o) and auto-fight (Tab), so safe ground is quick and the fights are the game.
• Trick shots, the thing nihilurk does that Rogue never did: shoot a trap, a coin or a potion on the floor from across the room and it goes off over everything around it. Bursts chain. Only ranged attacks do it, and it catches you too if you stand close.
• Seeded floors (-s 1234), and two ways down: nihil, who carries gear, or the lurk (-b lurk), who has claws and fur.
• Four languages, English, Portuguese, Spanish and Haitian Creole, one binary each, picked at build time.

Download a prebuilt game (v0.6.0), no Rust needed:

• Windows, x86_64 (.zip)
• macOS, Apple Silicon (.tar.gz)
• Linux, x86_64 (.tar.gz)
• Linux, aarch64 (.tar.gz)

Unpack it and run ./nihilurk (nihilurk.exe on Windows). All four languages are in the download: ./nihilurk --lang pt picks one (en, pt, es, ht), and with no flag it follows your LC_ALL, LANG or LANGUAGE. Keep the files together: the dispatcher starts the nihilurk-<lang> binary next to it. The binaries are not signed, so macOS quarantines a browser download: xattr -d com.apple.quarantine nihilurk* clears it. Every file has a checksum at the same address plus .sha256, and older versions are on the releases page.

Or install from crates.io (needs Rust 1.91 or newer) and play:

cargo install nihilurk                  # install the English game
cargo install nihilurk --force --no-default-features --features lang-pt    # or lang-es, lang-ht
nihilurk                                # play

A crates.io install holds one language, and --lang does nothing there. Run the install line again with another lang-* to switch. The prebuilt download is the way to keep all four.

If the shell says nihilurk: command not found, the cargo bin directory is not on your PATH. rustup normally adds it, but a rebuilt dotfile or a distro Rust package may not. Add it, then open a new shell:

# bash: append to ~/.bashrc    zsh: append to ~/.zshrc
export PATH="$HOME/.cargo/bin:$PATH"

# PowerShell on Windows, once (it sticks for your user)
[Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\.cargo\bin;" + [Environment]::GetEnvironmentVariable("Path", "User"), "User")

Until then, ~/.cargo/bin/nihilurk (on Windows %USERPROFILE%\.cargo\bin\nihilurk.exe) runs it.

From a clone:

cargo run -p nihilurk                  # play
cargo run -p nihilurk -- -s 1234       # play a specific seed
cargo test                           # everything

The game needs a terminal of at least 80 columns by 25 rows. In a smaller one the message log draws garbled letters. That is a known limit and will not be fixed.

It runs on Windows: a tester built it there and played it. On macOS the prebuilt binary is built and started by CI (Apple Silicon), but nobody has played it there yet. If you try Windows or macOS, open an issue and say what happened, good or bad.

Where things are

MANUAL.md      how to play: controls, combat math, items, monsters.
the site       https://bae-alves.github.io/nihilurk/, the manual and docs/, built from this repository.
doc/nihilurk.6     the command reference. `man nihilurk` works from the prebuilt tarball (it ships `nihilurk.6`) and the AUR package; `cargo install` installs the binary only, so use `nihilurk -h` or `man ./doc/nihilurk.6` from a clone.
docs/          how to add content to the game. Start at docs/README.md.
CONTRIBUTING.md    reporting bugs, sending patches and translations, and the LLM rule.
gdd.md         what nihilurk is trying to be. Design, not code.
models/        the game: rules, content tables, ECS systems.
strings/       every player-facing sentence, one file per language.
engine/        the terminal front end: input, rendering, the loop.
particle-core/ the particle arithmetic, `no_std` and dependency-free.
compat/        the machine matrix. Does it still run on a Pi?

compat/ is a test rig, kept out of the workspace’s default members, so a bare cargo build or cargo test never compiles it:

./compat_test.sh                     # nihilurk, built and checked on six machines
./docs_style.sh                      # docs/, held to the house style
./aur_check.sh                       # aur/PKGBUILD, against the tag it pins and this working copy

Once per clone, git config core.hooksPath .githooks turns on a pre-commit check that runs docs_style.sh and refuses a commit that changes the turn schedule or an intent queue without touching a page under docs/. It also names the pages to update when you add a ring, a flag, a key or the like, and never refuses for that – see .githooks/pre-commit.

Adding content

There is no pink dragon in nihilurk. The whole point is putting one in.

Open models/src/monsters.rs, find BESTIARY, add a line:

MonsterDef::row("pink dragon", 'D', Color::Magenta, Chase,
                8, 12, 2, 10, 2, 7)
    .grants(&[Grant::of::<FireImmune>()]),

That is: name, glyph, colour, how it moves, then hit points, attack die, attack bonus, armour die, armour bonus, and the shallowest floor it can appear on – plus, chained on, the fact that fire does nothing to it.

cargo build

That is the change. The pink dragon now populates floors from depth 7, is something a wand of polymorph can turn a foxbat into, something a scroll of create monster can summon, a legal bane for a vorpal weapon, and it comes back correctly out of a save file. Nothing else in the codebase had to be told it exists, because nothing else enumerates species.

Items are the same shape, in models/src/catalog.rs – one table per kind, one row per thing:

WeaponDef::new("quarterstaff", Color::DarkYellow, 7).missile(6),
ArmorDef { name: "brigandine", color: Color::Grey, armor_die: 6 },

A row is a name, an appearance, and the components the thing carries into the world. There is no dragon code and no ring code: combat reads components and never learns what kind of thing put them there. A few categories need one edit more – somebody has to say what drinking a new potion does – and the docs say which, and why.

To see what you made without playing down to floor 7:

NIHILURK_SPAWN="pink dragon" cargo run -p nihilurk
cargo run -p nihilurk -- -content       # every name the game knows

Documentation

docs/ is split by what you need at the moment you open it.

Learning        docs/tutorial/       a lesson, followed start to end
Solving         docs/how-to/         a recipe for one real task
Information     docs/reference/      every field, flag and signature
Understanding   docs/explanation/    why it is built this way

cat docs/README.md                          # the index
cat docs/tutorial/add-your-first-item.md    # start here, ~15 minutes
cat docs/tutorial/add-your-first-monster.md # then the bestiary
cat docs/how-to/add-a-monster.md            # or go straight to a recipe

Changing the engine rather than the content is a different door:

cat docs/explanation/ecs-in-nihilurk.md         # how bevy_ecs is used here
cat docs/how-to/work-with-the-ecs.md        # and how to get past the borrow checker

gdd.md is a fifth thing: what nihilurk is trying to be. Design, not code.

License

nihilurk is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. It comes with no warranty. The full text is in LICENSE.

nihilurk: instruction manual

Descend thirteen floors, take the Element of Yoord, and carry it back to the surface. Monsters, traps, gear of unknown quality, and permanent death stand between you and the exit.

If you have played other roguelikes, this table shows where nihilurk parts from them:

Starting the game

If you built the game using cargo, start a new expedition with:

cargo run -p nihilurk                  # start a game
cargo run -p nihilurk -- YourName       # name your nihilurk
cargo run -p nihilurk -- -s 1234        # play a particular seed
cargo run -p nihilurk -- -b lurk        # descend as a lurk
cargo run -p nihilurk -- -am dragon     # descend as any monster in the dungeon

nihilurk needs a terminal of at least 80 columns by 25 rows. In a smaller one the message log draws garbled letters. That is a known limit and will not be fixed.

The commands above run the game from a clone. After cargo install nihilurk, type nihilurk in their place. If your shell cannot find it, ~/.cargo/bin is not on your PATH; the README’s install steps shows how to add it.

Your name, if you give one, comes first. A name cannot start with -; an argument that does and is not a flag is refused. Everything else comes after it.

Other flags, in any order after the name:

nihilurk speaks English and a bit of Portuguese (pt). Spanish (es) and Haitian Creole (ht) exist in the codebase but need help, so please contribute! The installed nihilurk command picks the language from LC_ALL, LANG or LANGUAGE, and falls back to English if none matches. To choose one yourself, put --lang first:

nihilurk --lang pt

A cargo install holds one language and has no --lang; switch by reinstalling with cargo install nihilurk --force --no-default-features --features lang-pt (or lang-es, lang-ht). The prebuilt download from the releases page holds all four.

From a clone, a language is a build choice and there is no flag:

cargo run -p nihilurk --no-default-features --features lang-pt

Other roguelikes keep a wizard mode for testing. nihilurk has three environment variables instead. NIHILURK_SPAWN drops the things you name around you on every floor, NIHILURK_LEVEL makes every floor one kind of special level, and NIHILURK_MAGICMAP picks the magic mapping animation. The list is in docs/reference/cli-and-env.md.

You may quit and return to one expedition later. Saves are for stopping, not for undoing a death: when an expedition ends, the save is gone. A completed expedition is kept as clear data, so beginning another game after a victory is a choice to enter the dungeon again.

Who goes down

Two creatures were written to go down there, and -b picks between them.

Nihil is the default, and the rest of this manual describes nihil’s expedition: twelve hit points, four magic, and a mace, a bow and a suit of ring mail to start with. Everything nihil is worth in a fight is something nihil is carrying, which means everything can be improved, and everything can be lost.

Nihil plays forward. Every sword, suit and ring you find goes on and makes you better at the one thing nihil does well, which is walk up to trouble and hit it. That makes nihil the body to start with: the choices are few and plain, and a bad one costs you a fight, not the run.

Nihil is born knowing one trick, the charge. Hold Shift and press a direction with a creature two to six tiles off that way, and nihil crosses the gap in one turn and strikes. The way there has to be straight and clear: open floor, no creature in between. The price is that until the creatures have had their turn, every blow they land on you is 25% harder (VULN on the status line). You cannot charge with a foe already next to you; you are in the thick of it, and nihil knows better. A trap on the tile you land on goes off; a trap you jump over does not.

The lurk (-b lurk) is quadruped, fanged, clawed and furred, and shows on the map as a magenta @. It is the other way of playing:

• Seven hit points and two magic. It is thinner than nihil in every way that can be measured at the start.
• It carries nothing and can put nothing on but rings. The claws are the weapon and the fur is the armour, so no sword and no breastplate will ever add to either.
• It is quick — half again as fast as anything else in the dungeon, marked QUIK on the status line. Three moves for every two the floor gets.
• It moves quietly, the way a ring of stealth does: nothing notices it until it is within reach.
• It fights like a fencer without a blade. Step toward a creature with one empty tile between you and the lurk lunges across it: a sure hit at triple the roll, armour ignored. Every blow that lands winds the next one up. Shift still runs, but it cannot charge; that is nihil’s.
• It knows Bide, and pays magic for it like anybody else.
• It eats and grows. Any creature that dies on the floor may feed it: roughly one in three does, and the lurk gains a point of health, magic, attack or defence, at random. FEAR THE LURK! There is no counter to watch and nothing to save up for – it happens while you hunt or it does not.

Where nihil gets stronger by finding things, the lurk gets stronger by killing things. A lurk that avoids fights stays a lurk that can be killed by a bat.

The lurk plays slower than nihil, though it moves faster. With seven hit points it cannot trade blows, so every fight is a question: lunge or wait, bide or step away, drink the potion now or keep it. Nothing it finds can be worn but a ring, so the potions, scrolls, wands and coins carry the run, and each one is spent once. Pick the lurk once nihil’s dungeon feels familiar.

The dungeon screen

Two lines carry everything you need at a glance. Above the map:

DEPTH 3                              SCORE 000140

and below it:

BAE · HP 9/12 · Ma 4/4 · Pow. 8+1 · Arm. 5+1

DEPTH tells you where you are. SCORE is your score, except when the dungeon flashes a recent reward or warning in its place.

HP is your health and Ma is your magic, each shown as what you have out of what you can hold. Pow. and Arm. are your attack and your defence: the first number is the die that gets rolled – 8 means a roll of one to eight – and anything after it is added to that roll every time, so 8+1 is two to nine. A cursed item shows as a minus. Pow. turns green when something has poisoned your strength below its usual ceiling.

Short words may follow, one for each thing currently true of you – FAST, QUIK, SLOW, STLH for moving unnoticed, and one apiece for confusion, blindness and the rest.

The message log below the map describes what has just happened. When --MORE-- appears, press Space or Enter to continue reading. Until you do, the rest of the dungeon is waiting for you.

The map uses these symbols:

A monster that cannot fight at full strength is highlighted with a different tint. Dark blue is asleep. Cyan is paralysed: it loses half its turns. Dark green is held fast by a bear trap or a scroll of hold monster. Yellow is confused or fleeing. Grey is slowed.

Grey tiles are places you have seen but cannot currently see. The dungeon remembers walls and corridors, but not the creatures hiding beyond your sight.

Moving and fighting

nihilurk is turn-based. Your action gives the dungeon its turn. You cannot pass a turn, so choose an action whenever you press a key.

Move one square at a time with the arrows, vi keys, or number pad:

Walk into a monster to attack it. There is no separate attack command. You cannot walk diagonally through the corner of two walls, and you cannot attack a wall. Nothing heals you as you walk.

Health is scarce. Armour can turn a blow aside, but no weapon is guaranteed to save you. Now and then you land an excellent hit, and it shatters whatever armour your foe has on. Cursed armour bursts into splinters of evil magic that hurt the monsters around it and spare you and your allies. If a fight is going badly, leave it, use a potion, or find another way around.

Spirits are the shops. They are & creatures, and you make a deal by walking into one. Some give away a choice of items. Others trade if you carry something they want. Deal with them too much, or hurt them, and you upset the balance: every spirit turns hostile. A scroll of atonement makes them peaceful again.

You also carry a hidden alignment, from -3 to +3, between two camps of spirit. The yellow, red, blue and pink demons pull you down. The angel, the sphynx, sylphids, salamanders, undyne and gnomes pull you up. Each time a spirit leaves the floor (a deal done, a kill, a polymorph, anything that removes it) your alignment moves one step toward its camp. Gaining a Helper moves you up one, so a pink demon who joins you pulls you down one and up one. Blowing one up moves you down two, whether a new Helper replaces it or system shock bursts it. Reach +3 or -3 and you upset the balance. Off centre, the word BALANCE shows under the status line, left of the map, as a thermometer: one of its seven letters is tinted for your level, red for the demons’ side and cyan for the angels’, the rest white. When the spirits turn, it reads BROKEN instead, in the colour of the side you leaned to (white if a wound broke it while you were centred). A scroll of atonement and a potion of adjustment both bring it back to 0.

Several commands let you spend less time walking:

Auto-explore heads for whatever is nearest: unexplored ground, or an item worth taking. It leaves alone what you dropped, and what you saw in a room and walked out of without.

Automation stops when a monster enters view. Auto-fight will not start when you are badly hurt or confused. Treat these commands as a way to handle safe ground, not as a substitute for looking at the screen.

Using your pack

Items you find are picked up automatically when there is room. Press i to open the pack. Select an item with its letter, the direction keys, and Enter. An item keeps the same letter in every item menu.

These commands go directly to the relevant kind of action:

Throwing, firing, and most wands open an aiming cursor. Move it with the direction keys, press Enter to act, or press x to cancel. Arrows, quarrels and blowdarts are stronger, and carry twice as far, with the matching bow, crossbow or blowgun in your hand; a blowdart saps the power of whatever it wounds. Anything thrown that was not made for throwing does 1d2, and armour a creature wears (its plus) always takes some of the damage off. Small things — potions, scrolls, wands, rings — fly further out of a bare hand than a spear or a sack of arrows does. A thrown dagger or spear can pass through more than one target; other things may stop at the first creature they hit. A thrown boomerang hits the first creature in its way and flies back to you: to its old place in your pack, and into your hand if you were wielding it. With one in hand, f, v and Tab throw it.

Your pack has limited space. Ammunition shares a slot with matching ammunition, but other items take their own place. Coins are not carried: stepping on one spends it immediately. If a coin cannot help you yet, the dungeon leaves it where it is.

Trick shots. A trap has nobody to bite when nobody is standing on it, so a missile that lands on one sets the whole mechanism off at once, over every square around it. A coin shot the same way bursts just as far and gives its effect to you from across the room. You can only do this to a trap you have already found. A creature standing on a trap you know about, on a coin, or on the Element of Yoord is drawn on a magenta square: hit it and you set off what it is standing on. One burst sets off anything it covers, including traps nobody has found, so a good shot can run a long way. None of this is on your side. Stand too close to your own trick shot and it will catch you as readily as anything else.

Decks of cards

A deck of cards is as rare as a ring. It holds five cards, stacked when the deck turns up, and one or two of them lie reversed. Read it (r) and you play the top card; a reversed card plays its darker side. Some cards play other cards. Throw the deck instead and all that is left plays at once as a poker hand, never reversed, on you. Every card that makes up the hand pays 5,000 points, and a FOOL counts as any card. Five of a kind plays its card five times, then sets everything you wear to +5 and burns off its curses.

Helpers

A treat is food for a creature that is not you. You cannot use one, so throw it. Throw the right treat at a monster and it eats the treat. Half the time it becomes your Helper.

A Helper fights the monsters you can see, comes back to your side when there is nothing to fight, and turns up next to you on every new floor, healed. It has its own background colour. Walk into it to trade places. You get one Helper at a time. A second one blows up the first in a shower of gore, and that costs you alignment (see Spirits above). Wands of polymorph, haste and slow reach your Helper and other allies, not only enemies. Polymorph a Helper that is already polymorphed and it can burst from system shock, which costs you alignment too.

Thrown wands

Zap a wand (z) and it spends one charge. Throw it (t) and it bursts where it lands.

Coins

You do not carry coins. Stepping on one spends it on the spot, and a coin that would do nothing for you stays where it is until it would. Shoot one instead and its effect reaches you from where you stand.

• Some coins are treasure and add to your score.
• Some coins heal you, refill your magic, lift your afflictions, or restore drained strength, up to four points each.
• Two coins make you a promise. Reach a staircase unhurt and it pays: the first adds a point to your attack die or your armour die, the second adds a plus to your weapon or your armour. Any blow that lands on you before then takes the promise back.
• The hero coin teaches you a spell you do not know.

Conducts

A conduct is something you go without. Win a run and each one you kept adds 10% of your score on top, so a clean run is worth much more than a loud one. Die and you earn nothing for them.

• No potions, no scrolls, no wands, no runes.
• No casting, no coins, no throwing or firing, no melee attacks.
• No charming, no boon companion.
• No damage taken, no gear put on, never saved by your armour.
• Played as the lurk.

The win screen shows one coloured mark for each conduct you kept. The run dump lists them by name, and -scores prints the marks after each win.

Unknown things

Potions, scrolls, and wands tell you exactly what they are the moment you find them.

Weapons, armour, and rings hold back one thing: their own quality. An item may be plain, unusually good, or cursed, and you cannot tell which just by picking it up — though a ring always tells you what it does. A ring that is a number (protection, strength, increase damage, sharpshooting) is +2 when plain, +3 when unusually good, and anywhere from -3 to +2 when cursed; the other rings have no number to hide, only the curse. Wearing it settles the question; so does a scroll of identify, read before you commit. A cursed item may be powerful, but once you put it on, it may refuse to come off. Keep a way to remove a curse before testing something you cannot afford to lose. Put on a cursed item you already know about when its slot is full and holds a cursed item, and the two merge (a free finger just takes the ring). Monsters that catch or steal cursed gear merge it too: 45% of the time the worn item survives, 45% the new one does, and 10% both break. Whatever survives takes the new item’s plus and vorpal bane, replacing its own. With two cursed rings on, the first in your pack is the one that merges.

Magic and spells

The Ma pool powers your spells. Stairs refill it; it does not return merely because you wait. Press Z to open the spells menu and pick a spell by its row letter, or press Alt+Q, Alt+W, Alt+E or Alt+R to cast spell one to four directly.

The Alt shortcuts need your terminal to send Alt as a key modifier. Linux and Windows terminals do by default. On macOS, turn on “Use Option as Meta key” in Terminal (Settings, Profiles, Keyboard), or set “Left Option key” to “Esc+” in iTerm2 (Profiles, Keys). Without that, Option types a symbol and the shortcut never reaches the game. Z always works.

A hero coin teaches a new spell when you step on it. You can know only a few spells at once. A spell that needs a target uses the same aiming cursor as a wand.

A staff in your hand changes what your attacking spells are worth: each one costs more magic than usual and hits harder than usual, and it hits harder than it costs. The spells that heal, ward, reveal or steady you are untouched. Nothing on the screen shows this, so the staff says so itself – when you take it up, and again when you put it away.

Polymorph lends you a creature’s powers until the next staircase. A potion, a wand, a ring (which rolls on its own) and two spells, Polymorph Self and Polymorph Other, all do it. You keep your own face and numbers. A shape with no hands cannot hold gear: yours comes off and stays off. POLY on the status line shows it. Polymorph something that is already polymorphed and it is a coin flip: system shock, where a monster bursts and you are left on 1 HP, or a chimera, a typhon or an echidna. The ring never shocks. A ring of sustain form turns every polymorph aside, shock included.

Some effects change how you act. Confusion makes movement unreliable. Blindness limits what you can see. Paralysis and sleep steal time. A medusa’s gaze steals them too, by turning you to stone – but stone is hard: while it lasts nothing gets more than a chip through you and nothing can take your last point of health, unless what is standing over you is swinging a war hammer. Haste makes you quicker; slow makes you slower. A staircase clears these effects.

Exploring the floors

You can always see the squares immediately around you. A lit room reveals its whole interior; corridors reveal much less. Monsters disappear from the map when they leave your sight, even though the floor remains in your memory.

Traps may announce themselves, wait until you approach, or remain hidden until they spring. A discovered trap is marked with ^. Do not assume that an empty-looking corridor is safe merely because the last one was.

The Dungeon Lord allows only so much hesitation on each floor. If you stay too long, a portal carries you to another depth whether you are ready or not. The automatic movement commands exist partly to help you cross ground that has already proved safe.

Reaching a new floor restores some health and all of your magic. A trapdoor is not a rest; it is a fall.

The seed fixes the shape of the floors, but not everything you will meet there. A familiar corridor may hold unfamiliar monsters, traps, and treasure when you return.

The descent and the return

Take the down stairs to reach deeper floors. On the thirteenth floor there is no staircase down. The Element of Yoord waits there instead.

Taking a staircase tells you how the new floor looks against the usual for its depth. A magenta line says it is dangerous, a dark magenta one says it is safe. A yellow line says it is rich, a dark yellow one says it is poor. An ordinary floor says nothing. The count covers every monster and every item, hidden ones included. Trapdoors and portals give no feeling.

When you take the Element, you must climb instead of descend. The creatures you meet may be drawn from anywhere in the dungeon.

To win, carry the Element up and walk out of the dungeon from the first floor. A portal can move you between floors, but it cannot win the expedition for you.

Death is permanent. There is no retry or resurrection.

Useful commands

x takes the next weapon in your pack, wrapping round, but only across the divide: a melee weapon gives way to a launcher and a launcher to a melee weapon. It skips weapons whose quality you have not learned yet and weapons you know are cursed, and a cursed weapon in hand blocks it. Quitting saves the current expedition unless saving has been disabled. While time is stopped nothing is saved: the game saves as time stops and again as it starts. Quitting in between warns you in red and asks a second time, and those turns are lost.

The map can be centred, screen shake can be disabled, and blood can be hidden with command-line options. For the complete list, see docs/reference/cli-and-env.md.

Quick reference

Move          arrows / hjkl / numpad; diagonals yubn or 7913
Attack        walk into a monster
Run           Shift + direction
Explore       o        A toggles pickups
Travel        O, steer, Enter
Auto-fight    Tab
Fire          f        with a bow, crossbow or blowgun drawn
Reach         v        with a reach weapon
Look          ;        steer the cursor, no turn spent
Stairs        > down, < up (or . and ,)
Pack          i
Use           a        throw t        drop d
Quaff         q        read r          zap z
Equip         e        wield w         wear W        ring P
Spells        Z        pick a slot by its row letter
              Alt + Q/W/E/R for slots one to four
Cancel        x or X   never spends a turn
Quit          Q or X   with nothing open; Ctrl+C skips confirmation

Tutorial: add your first body

Audience       Anyone who wants a new way to play the whole game,
               not a new thing to meet in it. You have done
               `add-your-first-monster.md`, or you are comfortable
               enough to skip it.
Prerequisites  A checkout, and a working `cargo`.
Time           About twenty minutes.
You will       Add a ninja: quick, quiet, poisoned steel, and a
               fistful of daggers — built almost entirely out of
               abilities and gear that already exist.

This is a lesson, not a recipe. When you want the short version, read ../how-to/add-a-body.md.

%%{init: {'theme':'base','themeVariables':{
  'primaryColor':'#20242b','primaryTextColor':'#d7dae0',
  'primaryBorderColor':'#5c6370','lineColor':'#8a8f98',
  'fontFamily':'ui-monospace, SFMono-Regular, Menlo, monospace',
  'fontSize':'13px'}}}%%
flowchart LR
  S1["1 · find<br/>enum Body"]:::cold --> S2["2 · add<br/>the variant"]:::hero
  S2 --> S3["3 · borrow<br/>Quick + Stealthy"]:::magic
  S3 --> S4["4 · borrow<br/>Venomous"]:::magic
  S4 --> S5["5 · Sting in<br/>the spell bar"]:::magic
  S5 --> S6["6 · gear:<br/>equip_silently"]:::hero
  S6 --> S7["7 · -b ninja<br/>meet it"]:::peril
  S7 --> S8["8 · a staircase,<br/>not a reload"]:::cold
  classDef hero fill:#3a3418,stroke:#d7ba4a,color:#e8dfa8
  classDef peril fill:#3a1f1f,stroke:#c05050,color:#f0c8c8
  classDef magic fill:#2f2038,stroke:#a86fc0,color:#e6cdf0
  classDef cold  fill:#17323a,stroke:#4aa3c0,color:#bfe4f0

What you are about to learn

There is no Class trait and no impl Ninja. body.rs is one enum, Body, with a hand-written function per variant that dresses the player — wear_lurk is the one that already exists. A new body is a sibling of that function, not a new shape.

The point of this lesson is that a body barely has to invent anything. Every piece of the ninja — its speed, its quiet, its poison, even the fact that it starts holding a weapon — is something the game already knows how to do for somebody else. Writing the ninja is mostly pointing at those things.

By the end you will have a body that:

• moves at the lurk’s tempo and walks as quietly as the lurk does,
• bites like a rattlesnake,
• carries the spell Sting, the way the lurk carries Bide,
• and spawns already wearing armour and a ring, and wielding a dagger — which is also your look at equipment::equip_silently, the function that hands somebody gear without a word being logged about it.

Step 1: find the enum

Everything a body is lives in one file:

models/src/body.rs

Open it and find the enum:

pub enum Body {
    #[default]
    Nihil,
    Lurk,
    Monster(&'static MonsterDef),
}

Three answers today, and the module’s own doc comment at the top of the file explains why it’s one enum and not a flag per body: a player is exactly one of these, and the argument parser has nothing to cross-check. Read that comment before you touch anything below it.

Step 2: add the variant

pub enum Body {
    #[default]
    Nihil,
    Lurk,
    Ninja,
    Monster(&'static MonsterDef),
}

Body::name() needs an arm too — it’s what -b matches against, and what an error about the body prints:

pub fn name(self) -> &'static str {
    match self {
        Body::Nihil => "nihil",
        Body::Lurk => "lurk",
        Body::Ninja => "ninja",
        Body::Monster(def) => def.name,
    }
}

And wear needs to route to a function you haven’t written yet:

pub fn wear(world: &mut World, player: Entity, body: Body) {
    match body {
        Body::Nihil => {}
        Body::Lurk => wear_lurk(world, player),
        Body::Ninja => wear_ninja(world, player),
        Body::Monster(def) => crate::monsters::wear_monster(world, player, def),
    }
}

Build:

cargo build

It won’t compile — there is no wear_ninja yet. That’s the whole rest of the lesson.

Step 3: borrow the lurk’s tempo and its quiet

Scroll down to wear_lurk. It inserts a bundle of components and then grants a slice of effects through grant_all:

const LURK_GRANTS: &[Grant] = &[
    Grant::of::<Lurk>(),
    Grant::of::<Lunges>(),
    Grant::counted::<Fencer>(lurk::NUMBER_OF_ATTACKS),
    Grant::of::<BuildsMomentum>(),
    Grant::of::<Stealthy>(),
];

Stealthy is a plain marker component — the same one a ring of stealth grants, the same one rings::STEALTH_RANGE reads back out regardless of who is wearing it. Nothing about it belongs to the lurk; the lurk just happens to be the first thing that asked for it unconditionally instead of from a ring. A ninja can ask for the same marker:

const NINJA_GRANTS: &[Grant] = &[Grant::of::<Stealthy>()];

And the tempo is the same story. wear_lurk inserts:

Speed::new(SpeedKind::Quick),

SpeedKind::Quick already exists — it’s the lurk’s tempo, half again as fast as Normal. Start wear_ninja the same way wear_lurk starts, borrowing both:

fn wear_ninja(world: &mut World, player: Entity) {
    world.entity_mut(player).insert((
        Renderable {
            glyph: '@',
            color: Color::DarkGrey,
        },
        Fighter {
            hp: 8,
            max_hp: 8,
            power: 2,
            max_power: 2,
            power_bonus: 0,
            armor: 2,
            armor_bonus: 0,
        },
        Magic {
            points: 2,
            max_points: 2,
        },
        Speed::new(SpeedKind::Quick),
    ));
    grant_all(world, player, NINJA_GRANTS);
}

The numbers are placeholders for now — 8 HP, nihil’s own bare 2/2 dice, 2 Magic. You’ll pull them out to constants.rs in the step where you decide you’re keeping this.

Step 4: borrow the rattlesnake’s poison

Venomous is not a body’s effect at all — it’s the rattlesnake’s, over in monsters.rs:

MonsterDef::row("rattlesnake", 'R', Color::DarkGreen, Chase, 6, 6, 0, 8, 0, 5)
    .grants(&[Grant::of::<Venomous>()]),

Nothing stops the same marker riding on a player instead of a bestiary row — Grant::of::<Venomous>() doesn’t know or care what kind of entity is carrying it, the same way Stealthy didn’t. Add it to the ninja’s own list:

const NINJA_GRANTS: &[Grant] = &[Grant::of::<Stealthy>(), Grant::of::<Venomous>()];

Add Venomous to the use crate::effects::{...} line at the top of body.rs.

Rebuild:

cargo build

Still short one thing: wear_ninja is called from nowhere until you also handle the spell and the gear.

Step 5: put Sting in the spell bar

wear_lurk ends by handing the lurk one spell it has to pay for:

if let Some(mut spellset) = world.get_mut::<Spellset>(player) {
    spellset.slots.push(SpellEffect::Bide);
}

Sting already exists — a venomed dart at range, 1 Magic, in items/spells.rs. Give the ninja the same push, at the end of wear_ninja:

if let Some(mut spellset) = world.get_mut::<Spellset>(player) {
    spellset.slots.push(SpellEffect::Sting);
}

It costs Magic like anybody else’s copy of it would — nothing is special-cased in spell_cost, and a dragon-bodied player pays for its Fireball the same way (see ../reference/cli-and-env.md, “-am <species>”).

Step 6: gear, and equip_silently

Everything so far was an effect with nothing to spawn. Gear is different — a dagger, a suit of armour and a ring are entities, and wear_ninja has to build them the same way the floor stocks anyone else’s kit: spawn at the origin, strip the Position so it’s carried and not lying on a tile (levels.rs::starting_kit does the identical thing for nihil’s mace and ring mail), put it in the Backpack, then equip it.

equipment::equip_silently(world, wearer, item) is the function for that last part — it puts the item on without narrating it, which is exactly what you want for something the player is born wearing rather than something they just picked up and pulled on. Import it beside Slot in the use crate::equipment:: line.

let origin = Position { x: 0, y: 0 };
let strip = |world: &mut World, item: Entity| {
    world.entity_mut(item).remove::<Position>();
};

let armor = crate::catalog::spawn_armor(world, "leather armor", origin);
strip(world, armor);
let ring = crate::catalog::spawn_ring(world, RingEffect::Protection, origin);
strip(world, ring);
let daggers: Vec<Entity> = (0..5)
    .map(|_| {
        let dagger = crate::catalog::spawn_weapon(world, "dagger", origin);
        strip(world, dagger);
        dagger
    })
    .collect();

if let Some(mut pack) = world.get_mut::<Backpack>(player) {
    pack.items.push(armor);
    pack.items.push(ring);
    pack.items.extend(daggers.iter().copied());
}
equip_silently(world, player, armor);
equip_silently(world, player, ring);
equip_silently(world, player, daggers[0]);

Five daggers: one wielded, four spare in the pack — a dagger is also .missile(4), built to be thrown, so the spares are a ninja’s ammunition as much as a backup blade. equip_silently refuses quietly if a slot is already full or the item has nowhere to go (Equipped names its own slot), so the order above — armour, then ring, then the first dagger — is safe to follow literally.

Build:

cargo build

It compiles. -b doesn’t know the word “ninja” yet — that’s the last wire.

Add a line in engine/src/main.rs, next to the two that are already there:

match (flag, name.as_str(), models::MonsterDef::lookup(name)) {
    ("-b", "nihil", _) => body = Some((models::Body::Nihil, "-b")),
    ("-b", "lurk", _) => body = Some((models::Body::Lurk, "-b")),
    ("-b", "ninja", _) => body = Some((models::Body::Ninja, "-b")),
    ("-b", _, _) => unknown_body = Some((name.clone(), "-b")),
    ...
}

Step 7: meet it

cargo build
cargo run -p nihilurk -- -b ninja

You wake up quick, quiet, venomous, holding a dagger, wearing leather and a ring of protection, with four spare daggers and Sting in your spell bar. Open the pack (i) and look — the armour and ring show as worn, the same as nihil’s ever do.

Fight something and watch the log: “Venom courses through the <name> - its strength ebbs away,” the same sentence a rattlesnake’s bite would read against you, just turned around to name what you bit instead.

Step 8: the part a body cannot skip

It is tempting to guess this bug lives behind a save and reload, the way a lurk’s identity does. It doesn’t — try it first, so you believe the actual answer:

cargo run -p nihilurk -- -b ninja -ns
# play a turn or two, quit, then:
cargo run -p nihilurk -- -b ninja -ns

You come back quick, quiet and venomous, exactly as you left. Speed.kind, Stealthy and Venomous are all ordinary saved state — a plain field and two rows in the EFFECTS ledger — and none of them need the body to be identified to round-trip correctly. A reload is not where this breaks.

A staircase is. Find one and take it (>):

You come back Normal-paced. Not hasted, not slowed — the HUD’s tempo badge is simply gone, because Normal prints nothing. Nothing else about you changed: still quiet, still venomous, still holding the same daggers.

Here’s why, and it’s narrower than it first looks. crate::conditions::clear_player_conditions runs on every staircase (and on a wand of cancellation), and it always sets Speed.kind back to crate::body::innate_tempo(world, player) — “back to the body’s own tempo… it has no business lifting what the player is made of,” in its own comment. innate_tempo answers that question by checking for a Lurk marker, then a MonsterBody marker, and defaulting to Normal if it finds neither. The ninja has neither. So the very first staircase — not a reload, not anything special — asks “what is this creature’s own tempo?”, gets the only honest answer available (“nothing marks it as anything”), and quietly demotes a body that was supposed to be permanently quick.

Stealthy and Venomous don’t have this problem only because nothing else in the game ever takes them away and asks what to give back — a staircase lifts a ring of stealth’s temporary loan the same way it lifts a potion’s, but nothing analogous exists for these two, so their absence of an identity marker never gets tested. Tempo is the one property in the whole body system that is actively restored rather than merely held, which is exactly why it’s the one that exposes a body with no identity of its own.

The fix is the one line the lurk’s Lurk component exists for: give the ninja a marker of its own that nothing else in the game would ever attach to a player by accident (Stealthy and Venomous both fail that test — a ring of stealth and a rattlesnake’s bite can each hand a plain nihil the same marker), and teach innate_tempo to read it the way it already reads Lurk and MonsterBody. Picking that marker, and confirming it survives a save the way Lurk does, is left as the next step — exactly the shape ../how-to/add-a-body.md describes it in.

Step 9: keep it or drop it

If you like the ninja, decide on its save marker and finish the job. If this was a dry run:

git checkout models/src/body.rs engine/src/main.rs

What you actually learned

• A body is a hand-written function, not a table row — ../how-to/add-a-monster.md’s “one line in one table” does not apply here. What does carry over is reuse: almost nothing a body needs has to be invented.

• An effect marker doesn’t belong to whoever you first saw it on. Stealthy is the lurk’s in the same sense Venomous is the rattlesnake’s — which is to say, not really. Both are just components a Grant can hand to any entity at all.

• Gear a creature is born with is built exactly like gear the floor hands out: spawn it, strip its Position, and either put it in a Backpack or (for something worn from the first turn) also run it through equip_silently.

• A body needs an identity marker for reasons sharper than “does it survive a save” — ordinary saved state survives a save regardless. It’s the code that actively restores something (innate_tempo, read on every staircase) that needs to ask “what is this creature, really” — and a body that never answers that question gets the default answer, silently, the first time anything asks. Borrowing an effect for its behaviour and borrowing one for its identity are two different questions, and the ninja above answered only the first.

Where to go next

../how-to/add-a-body.md the short version, as a recipe — including the save marker this tutorial left undone add-your-first-monster.md the same kind of lesson, for a bestiary row ../how-to/add-an-effect.md where Stealthy and Venomous actually come from ../reference/cli-and-env.md -b and -am, from the player’s side ../reference/components.md Body, MonsterBody, StartingBody

Tutorial: add your first item

Audience       Anyone who wants to add content to nihilurk. You have
               written a little Rust, or a little of something like
               it. You have never touched this codebase.
Prerequisites  A checkout, and a working `cargo`. That is all.
Time           About fifteen minutes.
You will       Add a weapon to the game, see it in the dungeon,
               prove it works, then change how it behaves.

This is a lesson, not a recipe. It takes the longest road on purpose. When you want the short version, read ../how-to/add-an-item.md.

%%{init: {'theme':'base','themeVariables':{
  'primaryColor':'#20242b','primaryTextColor':'#d7dae0',
  'primaryBorderColor':'#5c6370','lineColor':'#8a8f98',
  'fontFamily':'ui-monospace, SFMono-Regular, Menlo, monospace',
  'fontSize':'13px'}}}%%
flowchart LR
  S1["1 · find<br/>the table"]:::cold --> S2["2 · add<br/>a row"]:::hero
  S2 --> S3["3 · -content<br/><i>the game knows it</i>"]:::cold
  S3 --> S4["4 · NIHILURK_SPAWN<br/><i>hold it</i>"]:::hero
  S4 --> S5["5 · cargo test<br/><i>it stays proved</i>"]:::cold
  S5 --> S6["6 · .missile(6)<br/><i>change what it does</i>"]:::magic
  S6 --> S7["7 · keep it,<br/>or git checkout"]
  classDef hero fill:#3a3418,stroke:#d7ba4a,color:#e8dfa8
  classDef peril fill:#3a1f1f,stroke:#c05050,color:#f0c8c8
  classDef magic fill:#2f2038,stroke:#a86fc0,color:#e6cdf0
  classDef cold  fill:#17323a,stroke:#4aa3c0,color:#bfe4f0

What you are about to learn

In nihilurk, a piece of content is a row in a table. Not a class, not a file, not a subclass of Weapon – a line. The line says what a thing is called, how it draws, and what it carries into the world. Nothing else in the game enumerates weapons, so nothing else needs to hear about yours.

By the end you will have added a quarterstaff, and you will believe that sentence.

Step 1: find the table

Every item in the game lives in one file:

models/src/catalog.rs

Open it and search for WEAPONS. The top of it looks like this:

#[rustfmt::skip]
pub const WEAPONS: &[WeaponDef] = &[
    WeaponDef::new("dagger",           Color::Grey,     4).missile(4).piercing(),
    WeaponDef::new("spear",            Color::DarkGrey, 6).missile(8).piercing(),
    WeaponDef::new("mace",             Color::DarkGrey, 6),
    WeaponDef::new("long sword",       Color::White,    8),
    WeaponDef::new("two-handed sword", Color::Cyan,    10),
    // ... more rows ...
];

One weapon, one line. Read one:

WeaponDef::new("mace", Color::DarkGrey, 6)
                 |          |           |
              its name   its colour   its damage die

The mace rolls 1d6 when you swing it. The long sword rolls 1d8. That third number is the whole of what a weapon is worth in a fight – see ../reference/content-tables.md if you want the combat maths now, though you do not need it yet.

Step 2: add a row

A quarterstaff should sit between the mace and the long sword: a bit better than a club, nowhere near a sword. Add this line after the mace:

WeaponDef::new("quarterstaff",     Color::DarkYellow, 7),

Line the columns up with its neighbours. The table carries #[rustfmt::skip], which means cargo fmt will leave your alignment alone – these tables are meant to be read as columns.

Now build:

cargo build

It compiles. That is the entire change. There is no registration step, no match arm waiting for you, no list of weapon names somewhere else that is now out of date.

Step 3: see that the game knows about it

Ask the game what content it has:

cargo run -p nihilurk -- -content | grep quarterstaff

You should get:

  quarterstaff

That listing is not a hand-maintained document. It reads the tables at run time, walks every row, and prints what it finds. Your weapon is in it because the table is the only place weapons are defined.

Step 4: hold it in your hands

Waiting for a rare drop to prove your work is a miserable way to spend an evening. So there is a shortcut:

NIHILURK_SPAWN="quarterstaff" cargo run -p nihilurk

The floor is built as normal, and then the things you named are dropped on free tiles next to you. Walk one step, pick it up, wield it.

You can ask for several at once, and mix kinds freely:

NIHILURK_SPAWN="quarterstaff,dragon,ring of protection" cargo run -p nihilurk

Anything the tables do not recognise is skipped in silence. See ../reference/cli-and-env.md.

Step 5: prove it, so it stays proved

Looking at it is not the same as knowing it works. Run the table tests:

cargo test --test it content::

Several of those tests just read your new row. They checked that no two rows share a name, that every name spawns something, that what spawns keeps the name it was spawned by, and that the loot table can still produce one of everything. Your quarterstaff was included automatically, because those tests iterate the tables too.

That is the pattern worth taking away: in this codebase, the tables are data, so tests can check the data. You did not have to write a test to get your row tested.

Step 6: change what it does

A row is not only numbers. It is also behaviour, expressed by chaining. Look at the dagger again:

WeaponDef::new("dagger", Color::Grey, 4).missile(4).piercing(),

.missile(4) says: this thing is built to be thrown, and rolls 1d4 when it lands. .piercing() says: a throw does not stop at the first body – it runs the whole line you aimed down.

Suppose your quarterstaff is really a javelin. Change your row to:

WeaponDef::new("quarterstaff", Color::DarkYellow, 7).missile(6),

Rebuild, and throw it at something:

NIHILURK_SPAWN="quarterstaff,emu" cargo run -p nihilurk

It now flies properly: it is spent on what it hits, and nothing can pluck it out of the air. You did not implement any of that. Those behaviours belong to .missile(...), and every row that asks for them gets both.

Nothing in the throwing code knows a quarterstaff exists. It asks “is this a Projectile?”, and your row answered.

Step 7: keep it or drop it

If you like the quarterstaff, leave it. If this was a dry run:

git checkout models/src/catalog.rs

What you actually learned

• Content is a row in a table, and the table is the only definition.

• Behaviour is attached by naming it, not by writing it. .missile() and .piercing() are shorthands for components, and the systems that care look for the components, never for your item.

• Nothing else has to be told. No registry, no factory, no match.

• The tables are data, so the tools work on them for free: the -content listing, NIHILURK_SPAWN, and the table tests all read the same rows you edited.

Weapons are the easy case. Some categories need one more edit – a potion needs somebody to say what drinking it does. The next section is one worked row for each kind, so you can see exactly where the line falls.

One row for every kind

Every category that drops in nihilurk falls into one of two halves: the ones that are a row and nothing else, and the ones that also need somebody to say what the new thing does.

The second half is not a chore the design failed to remove. A potion is a promise that drinking it will do something, and no table can invent what. What the design does remove is everything else: you never register a type, never touch the loot roller, never add a name to a list.

Try any of these the way you tried the quarterstaff – add the row, cargo build, then NIHILURK_SPAWN="<name>" cargo run -p nihilurk.

A row and nothing else

Armour. ARMORS in catalog.rs. One number: what wearing it adds to your defence die.

ArmorDef { name: "brigandine", color: Color::Grey, armor_die: 6, grants: &[] },

A weapon. WEAPONS, as above.

A coin, as long as it does something a coin already does. COINS pairs a PickupEffect with the one number that effect works with – so a cheaper treasure coin is a row, full stop:

CoinDef { name: "copper coin", color: Color::DarkYellow,
          effect: PickupEffect::Coin, amount: 250, weight: 10 },

A ring, as long as what it does is a number combat already folds or a marker some system already asks about. This one is the whole argument for the design in three lines:

RingDef::new(RingEffect::FireResistance, "ring of fire resistance")
    .grants(&[Grant::of::<FireImmune>()]),

FireImmune is what a dragon is born with. The wand-of-fire code asks whether its target carries it and has never heard of rings, so wearing one works the moment the row exists. RingEffect::FireResistance is a variant you append to the enum. It is just the key the row is spawned by – an identity, not behaviour.

A treat. TREATS. A treat is thrown at a creature as an offer of loyalty; for_item_users says whether it is meant for a creature with hands.

TreatDef { name: "bone", color: Color::Grey, for_item_users: false },

Ammunition and a launcher are one job in two rows, and neither names the other. They meet at an effect:

// in effects.rs, alongside FireArrow and FireQuarrel
#[derive(Component, Default, Clone, Copy)]
pub struct FireStone;

// in AMMO
AmmoDef { name: "sling stone", color: Color::Grey, die: 3, venom: false, launched_die: 6,
          launched_by: Grant::of::<FireStone>() },

// in LAUNCHERS
LauncherDef { name: "sling", color: Color::DarkYellow,
              grants: &[Grant::of::<FireStone>()], melee_cap: 1 },

Thrown by hand the stone rolls its die. Loosed by somebody carrying FireStone it rolls its larger launched_die. The sling is not consulted – only the effect is, which is why a hobgoblin that picks one up shoots just as well as you do. Add FireStone to the EFFECTS registry so it survives a save; see ../how-to/add-an-effect.md.

A row, plus one place that says what it does

Each of these is keyed by an enum, and the mechanic that reads it is an exhaustive match with no catch-all. That is deliberate: a new variant does not compile until somebody has said what it does. You cannot ship a potion that silently does nothing.

A potion. Row in POTIONS, variant on PotionEffect, arm in apply_potion_effect (items/potions.rs):

PotionDef { effect: PotionEffect::Levitation,
            name: "potion of levitation", color: Color::Cyan },

The arm returns bool – whether the dose visibly took hold.

A scroll. Row in SCROLLS, variant on ScrollEffect, arm in apply_scroll_effect (items/scrolls.rs). A scroll has no colour: it is always white, and what varies is its unreadable title.

ScrollDef { effect: ScrollEffect::ProtectArmor,
            name: "scroll of protect armor" },

A wand. Row in WANDS, variant on WandEffect, arm in apply_wand_effect (items/wands.rs) – plus one more, because a wand can be thrown as well as zapped: give it a colour in blast_palette, and add it to is_attack_wand if it should deal damage rather than deliver an effect.

WandDef { effect: WandEffect::Sleep, name: "wand of sleep",
          color: Color::Blue, range: 6 },

Most of a wand’s arm is borrowed. Sleep is conditions::snare(world, victim, Grant::of::<Asleep>(), turns) and nothing else; the trap and the scroll that also put things to sleep call the same verb.

A genuinely new kind of coin – one that does something no coin does yet – needs a PickupEffect variant and arms in both apply and would_help (items/pickups.rs). would_help is the interesting one: it is what leaves a coin on the floor when taking it would do nothing, so a red coin waits at full health for the fight that goes badly.

The one thing to check afterwards

Potions, scrolls, wands and rings are always shown by their true name – there is no cosmetic appearance to keep in step with the table you just edited, and nothing to check. The one thing a new row must not be is a dud: cargo test --test it content:: fails if a catalog row ever spawns PotionEffect::Water, ScrollEffect::BlankPaper or WandEffect::Nothing, which exist only as what a wand of cancellation turns a carried item into.

cargo test --test it content::

Where to go next

add-your-first-monster.md the same lesson, for the bestiary ../how-to/add-an-item.md every item category, one recipe each ../how-to/add-an-effect.md adding a property like FireImmune ../reference/content-tables.md every field of every table ../explanation/data-driven-content.md why it is built like this

Tutorial: add your first monster

Audience       Anyone who wants to put a creature in the dungeon.
               You have written a little Rust, or a little of
               something like it. You have never touched this
               codebase.
Prerequisites  A checkout, and a working `cargo`. That is all.
               `add-your-first-item.md` first if you have it in you;
               this page assumes nothing from it, but they rhyme.
Time           About fifteen minutes.
You will       Add a creature to the bestiary, meet it, prove it
               works, then give it magic nobody wrote code for.

This is a lesson, not a recipe. It takes the longest road on purpose. When you want the short version, read ../how-to/add-a-monster.md.

%%{init: {'theme':'base','themeVariables':{
  'primaryColor':'#20242b','primaryTextColor':'#d7dae0',
  'primaryBorderColor':'#5c6370','lineColor':'#8a8f98',
  'fontFamily':'ui-monospace, SFMono-Regular, Menlo, monospace',
  'fontSize':'13px'}}}%%
flowchart LR
  S1["1 · find the<br/>bestiary"]:::cold --> S2["2 · add<br/>a row"]:::hero
  S2 --> S3["3 · -content<br/><i>and five other<br/>systems, free</i>"]:::cold
  S3 --> S4["4 · NIHILURK_SPAWN<br/><i>meet it</i>"]:::peril
  S4 --> S5["5 · content +<br/>determinism"]:::cold
  S5 --> S6["6 · .grants()<br/>.casts()<br/>.weight()"]:::magic
  S6 --> S7["7 · keep it,<br/>or git checkout"]
  classDef hero fill:#3a3418,stroke:#d7ba4a,color:#e8dfa8
  classDef peril fill:#3a1f1f,stroke:#c05050,color:#f0c8c8
  classDef magic fill:#2f2038,stroke:#a86fc0,color:#e6cdf0
  classDef cold  fill:#17323a,stroke:#4aa3c0,color:#bfe4f0

What you are about to learn

There is no emu class in nihilurk. There is no Monster trait, no impl Dragon, and no file called monsters/ full of behaviour. There is one table, and an emu is a line in it.

By the end you will have added a basilisk that is immune to fire, invisible, rare, and waiting on the deep floors – and you will not have written a single line of behaviour to get any of that.

Step 1: find the bestiary

Every creature in the game lives in one file:

models/src/monsters.rs

Open it and search for BESTIARY. One line per species. Read the emu:

//              name       glyph  colour            move   hp  pow  pb  ar  ab  dep
MonsterDef::row("emu",     'E',   Color::DarkGreen, Chase,  6,   4,  0,  4,  1,   1),

Ten columns, and the header comment above the table names them. The four that decide how a fight goes are the middle ones:

hp   how much it can take
pow  its attack die: it rolls 1d[pow] against you
pb   a flat number added to that roll, once
ar   its defence die: it rolls 1d[ar] against your swing
ab   a flat number added to *that* roll, once

There is no to-hit roll and nothing ever misses. A blow is your roll minus its roll, and what is left comes off somebody’s hit points. That is the whole of combat; see ../explanation/combat-and-balance.md when you want to know why the numbers are small.

The last column, dep, is the shallowest floor the creature appears on. The emu starts at 1. The dragon starts at 10.

Step 2: add a row

A basilisk should sit in the middle stat band: tough, slow to kill, and hitting hard. Add this line after the emu, keeping the columns lined up:

MonsterDef::row("basilisk",  'b',   Color::DarkGreen,  Chase,  5,   8,  1,   8,  1,   5),

Chase is the only tactic that walks toward you. The others are Flee (walks away), Static (never acts at all – the inert placeholder the test suite reaches for), Ambush (lies in wait and never approaches, but lunges the instant you draw alongside it – the venus flytrap, the ice monster) and Confused (staggers at random, which is what anything does after a flash of light).

The table carries #[rustfmt::skip], so cargo fmt will leave your alignment alone. These tables are meant to be read as columns.

Now build:

cargo build

It compiles. That is the entire change. There is no registration step, no spawn function to teach, no list of species anywhere else that is now out of date.

Step 3: see that the game knows about it

Ask the game what it has:

cargo run -p nihilurk -- -content | grep basilisk

You should get:

  basilisk

That listing is not a hand-maintained document. It walks the tables at run time. Your basilisk is in it because the table is the only place creatures are defined.

More than the listing changed, and this is the part worth pausing on. Your basilisk is now:

• something a floor at depth 5 or deeper can populate itself with,
• something a wand of polymorph can turn an emu into,
• something a scroll of create monster can conjure,
• a legal bane for a scroll of vorpalize weapon,
• and something that comes back correctly out of a save file.

You did not do any of that. Every one of those five reads the same table, so none of them had to be told.

Step 4: meet it

Playing down to floor 5 to look at your own work is a miserable way to spend an evening. So:

NIHILURK_SPAWN="basilisk" cargo run -p nihilurk

The floor is built as normal, and then the things you named are dropped on free tiles near you. NIHILURK_SPAWN ignores the depth gate, so you can look at a floor-10 creature on floor 1.

Fight it. Then try it with company:

NIHILURK_SPAWN="basilisk,basilisk,potion of healing" cargo run -p nihilurk

Step 5: prove it, so it stays proved

Looking at it is not the same as knowing it works:

cargo test --test it content::

Several of those tests just read your new row. They checked that no two species share a name, that every name spawns something, that what spawns keeps the name it was spawned by, and – the one that matters most for a monster – that nothing ever turns up above its min_depth.

Then run the one that protects everybody else’s saved seeds:

cargo test --test it determinism::

That test says adding content cannot move a wall. A floor’s layout is a pure function of (seed, depth) and is drawn from its own RNG stream, so your basilisk cannot reach into somebody’s seed 1234 and rearrange it. If you ever make that test go red, you have drawn from the wrong stream – and it is much better to find out here.

Step 6: give it magic nobody wrote

A row can carry more than numbers. Chain onto it:

MonsterDef::row("basilisk",  'b',   Color::DarkGreen,  Chase,  5,   8,  1,   8,  1,   5)
    .grants(&[Grant::of::<FireImmune>()])
    .casts(2, &[SpellEffect::Thunderbolt])
    .invisible()
    .weight(4),

Four things happened, and you wrote no code for any of them.

.grants(...) hands the creature a property. FireImmune is a plain marker component. The wand-of-fire code asks whether its target carries one, and that is the whole check. It has never heard of a basilisk, or of a dragon, or of any ring that might grant the same thing to a player. Every effect on the list works this way; see ../reference/content-tables.md for what is available, and ../how-to/add-an-effect.md for adding one.

.casts(2, &[...]) teaches it a spell and the Ma for two casts of it. Thunderbolt costs 1, so the basilisk is born with 2 Ma and a spellset of one. The chaser rule set tries a spell before it tries a bite, so the basilisk zaps you from range until the Ma runs out, and then it walks up and bites. The pool never refills.

.invisible() makes it unseeable without second sight. The visibility system already knows what to do with that, because the phantom needed it first.

.weight(4) makes it rarer. DEFAULT_SPAWN_WEIGHT is the baseline every row sits at unless it says otherwise, so a weight below it is rarer than its floor-mates. The weights are relative to each other and to nothing else: you can make one creature rarer without touching any other number.

Rebuild and meet it now:

NIHILURK_SPAWN="basilisk" cargo run -p nihilurk

It is somewhere next to you and you cannot see it. Try burning it with NIHILURK_SPAWN="basilisk,wand of fire" – it will shrug, and the log will say so in as many words.

A creature made of grants

The best row to read next is the dog. Find it in models/src/monsters.rs:

MonsterDef::row("dog", 'd', Color::DarkYellow, Chase, 8, 6, 0, 7, 0, 3)
    .grants(DOG_GRANTS)
    .weight(2),

The numbers are a plain chaser’s. It uses Chase, so it thinks with the same rule set as the dragon and tries a spell first. Everything that makes it a dog is in DOG_GRANTS, a list of grants with one behaviour each:

• AlwaysTamed: any treat tames it, every time.
• AlwaysHelper: a charm or a scroll of create monster makes it your Helper, not a plain ally.
• PriorityHelper: it never explodes to make room, so you can keep any number of dogs. Recruiting one explodes the ordinary Helper.
• ShapeshiftOnKill: each melee kill may turn it into another random monster (constants::helpers::SHAPESHIFT_CHANCE).
• FaerieOnDeath: when it dies it is revealed as a faerie shapeshifter and is gone, with no gore.

No system in the game mentions dogs. Each one asks about its own grant, so any creature that carries the grant gets the behaviour. Try it:

NIHILURK_SPAWN="dog,snack" cargo run -p nihilurk

Pick up the snack and throw it at the dog (t). A snack tames a creature without hands on a constants::helpers::ACCEPT_CHANCE roll. It tames a dog every time. Walk a dog into a fight and watch for “It was never a dog, but a …!”. The (d) is a dogppelganger: a faerie shapeshifter wearing a dog, which is why it can change its shape and why no dog ever dies.

Now pick up a wand of cancellation (NIHILURK_SPAWN="dog,wand of cancellation") and zap the dog. Nothing changes. The dog’s grants are identity effects: a short list in models/src/effects.rs, IDENTITY_EFFECTS, that cancellation skips. Zap the basilisk and it loses FireImmune, because a species’ ordinary magic stays cancellable. The only difference between the two cases is whether the grant’s id is on that list. See “Parts nothing can cancel” in ../how-to/add-a-monster.md to build a creature that way.

Step 7: keep it or drop it

If you like the basilisk, leave it – and add a line about it to MANUAL.md’s bestiary, because documentation ships with the change that makes it true. If this was a dry run:

git checkout models/src/monsters.rs

What you actually learned

• A species is a row, and the row is the only definition. Nothing else in the game enumerates creatures.

• A creature’s special behaviour is a property it carries, named on the row. The systems look for the property and never for your monster, which is why .grants(&[Grant::of::<FireImmune>()]) is the whole of “fire does nothing to it”.

• A whole creature can be nothing but grants. The dog is a plain chaser plus its grants, one per behaviour, and the ones listed in IDENTITY_EFFECTS cannot be cancelled.

• Rarity and depth are two numbers on the row, relative to the rest of the table, and changing one changes nothing else.

• The tables are data, so the tools work on them for free: the -content listing, NIHILURK_SPAWN, the table tests and the save file all read the same row you edited.

The one thing a row cannot express is a behaviour that does not exist yet. If your creature needs to do something no effect covers – breathe a cone of frost, get in a mech – that is a new effect plus the mechanic behind it, and then a row that names it. Which is the next page.

Where to go next

add-your-first-item.md the same lesson, for the catalog ../how-to/add-a-monster.md the short version, as a recipe ../how-to/add-an-effect.md giving it a property nothing else has ../how-to/tune-rarity-and-depth.md weights and debut depths in full ../reference/content-tables.md every field of every table ../explanation/combat-and-balance.md what good numbers look like

Tutorial: add your first spell

Audience       Anyone who wants to add content to nihilurk. You have
               done `add-your-first-item.md`, or you are
               comfortable enough to skip it.
Prerequisites  A checkout, and a working `cargo`. That is all.
Time           About ten minutes.
You will       Add an active spell, aim it, feel it cost Magic,
               then see where the pattern stops looking like an
               item.

This is a lesson, not a recipe. When you want the short version, read ../how-to/add-a-spell.md.

%%{init: {'theme':'base','themeVariables':{
  'primaryColor':'#20242b','primaryTextColor':'#d7dae0',
  'primaryBorderColor':'#5c6370','lineColor':'#8a8f98',
  'fontFamily':'ui-monospace, SFMono-Regular, Menlo, monospace',
  'fontSize':'13px'}}}%%
flowchart LR
  S1["1 · find<br/>SpellEffect"]:::cold --> S2["2 · add<br/>a row"]:::hero
  S2 --> S3["3 · write<br/>the mechanic"]:::magic
  S3 --> S4["4 · give it<br/>to yourself"]:::hero
  S4 --> S5["5 · cast it"]:::peril
  S5 --> S6["6 · where it<br/>isn't an item"]:::cold
  classDef hero fill:#3a3418,stroke:#d7ba4a,color:#e8dfa8
  classDef peril fill:#3a1f1f,stroke:#c05050,color:#f0c8c8
  classDef magic fill:#2f2038,stroke:#a86fc0,color:#e6cdf0
  classDef cold  fill:#17323a,stroke:#4aa3c0,color:#bfe4f0

What you are about to learn

nihilurk teaches its active spells to the player at random, through a hero coin (an uncommon coin-table pickup), rather than starting anyone with any. A spell is coded the way a potion or a wand is – one identity enum, one catalog row, one mechanic keyed off it – because it is exactly as active as either of those. This tutorial adds one more, by hand, the way every spell in the table was first tried.

It is also, on purpose, not an item. It has no Position, no Item marker, no pack slot. It cannot be dropped, thrown, or found on a floor. It lives permanently in whoever’s Spellset it’s in, and it spends Magic instead of a battery.

By the end you will have added Ice Bolt, and you will know exactly which parts of “add an item” still apply and which ones stopped applying the moment you left Position off the struct.

Step 1: find the enum and the table

A spell’s identity is SpellEffect, in:

models/src/components.rs

Search for it:

pub enum SpellEffect {
    DragonBreath,
    Sting,
    Thunderbolt,
    // ... more variants ...
}

Next to it, in models/src/catalog.rs, is the table that gives each variant a name, a cost, a reach and a kind:

pub const SPELLS: &[SpellDef] = &[
    SpellDef { effect: SpellEffect::DragonBreath, name: "Fireball", cost: 2, range: 8, kind: SpellKind::Attack },
    // ... more rows ...
];

Read Fireball’s row:

SpellDef { effect: SpellEffect::DragonBreath, name: "Fireball", cost: 2, range: 8, kind: SpellKind::Attack }
                          |                          |          |       |                |
                    the identity                its label   Magic    reticle      Attack or Skill --
                                                              spent    reach       a staff's business
                                                                                    when it's Attack

cost is Magic points, spent by spell_system the instant the spell actually fires (multiplied by a wielded staff’s TurboMagic, but only for an Attack). range feeds the aiming reticle exactly the way a wand’s Ranged.range does – you will aim Ice Bolt the same way you’d zap a wand of cold. kind is read once, by spell_cost and by whatever mechanic you write in step 3.

Step 2: add a row

Ice Bolt is Fireball’s cold twin. Append a variant at the very end of the enum – never in the middle, since a save encodes a SpellEffect as its position:

pub enum SpellEffect {
    DragonBreath,
    // ... the other variants ...
    GateDown,
    IceBolt,
}

And a row anywhere in SPELLS (the table’s order doesn’t matter, only the enum’s does):

SpellDef { effect: SpellEffect::IceBolt, name: "Ice Bolt", cost: 2, range: 6, kind: SpellKind::Attack },

Build:

cargo build

It will not compile. That is the point of the next step – unlike a weapon or a suit of armour, a spell’s row is not the whole of it.

Step 3: write the mechanic

The error names a missing match arm in models/src/items/spells.rs:

fn apply_spell_effect(
    world: &mut World,
    user: Entity,
    target: Position,
    effect: SpellEffect,
    power_mult: i32,
) {
    match effect {
        SpellEffect::DragonBreath => breathe_fire(world, user, target, power_mult),
        // ... more arms ...
    }
}

The match has no catch-all, on purpose – the same discipline apply_wand_effect holds over WandEffect. A variant that compiled without an arm would be a spell that silently did nothing, and nihilurk does not ship those. power_mult is constants::spells::TURBO_MAGIC_POWER_MULT when a staff multiplied an Attack’s cost, 1 otherwise – fold it into your damage the way every existing Attack arm does. The staff gives back more damage than it takes in Magic; both multipliers live in constants::spells, one beside the other, so the trade stays readable.

Add the arm, and the function it calls:

SpellEffect::DragonBreath => breathe_fire(world, user, target, power_mult),
SpellEffect::IceBolt => ice_bolt(world, user, target, power_mult),

fn ice_bolt(world: &mut World, user: Entity, target: Position, power_mult: i32) {
    let (power, power_bonus) = {
        let fighter = world.get::<Fighter>(user);
        let loadout = loadout(world, user);
        (
            fighter.map_or(0, |f| f.power) + loadout.power_die,
            fighter.map_or(0, |f| f.power_bonus) + loadout.power_bonus,
        )
    };
    let damage = ((world.resource_mut::<GameRng>().0.gen_range(1..=power.max(1)) + power_bonus)
        .max(0))
        * power_mult;
    world
        .resource_mut::<GameLog>()
        .add("A wave of killing frost radiates outward!".to_string());
    elemental_blast(
        world,
        Some(user),
        target,
        BLAST_RADIUS,
        damage,
        Some(Element::Cold),
        BlastPalette::Frost,
    );
}

Look closely and you’ll notice you wrote almost nothing. elemental_blast is the same function a zapped wand of cold calls – the disc, the line-of-sight check, the animation, the chain reaction into any trap or coin caught in it, all of it borrowed. The only thing ice_bolt supplies is how much damage, computed from the caster’s own claws rather than a wand’s dice. That computation is copied verbatim from breathe_fire right above it; a spell that inflicts a status instead of damage would instead borrow from crate::conditions, the way a wand’s utility effects do.

Build again:

cargo build

It compiles. cargo test has one more exhaustive match: every_spell_has_a_catalog_row in models/tests/it/creature_casts.rs lists every spell, so add SpellEffect::IceBolt to its match and to its all array.

Step 4: give it to yourself

There is no NIHILURK_SPAWN for a spell – there is no entity to spawn. In play, the only way to learn one is a hero coin (an uncommon coin-table pickup that teaches a random not-yet-known spell); to try Ice Bolt without hunting for a coin, replace the empty Spellset::default() in initialize_world (models/src/map/levels.rs) with:

Spellset {
    slots: vec![SpellEffect::IceBolt],
},

Tests about the lurk, the hero coin and amnesia expect an empty starting Spellset, so cargo test fails while this edit stands. Step 7 reverts it.

Build and run:

cargo build
cargo run -p nihilurk

Step 5: cast it

Press Z. You should see a small box listing Ice Bolt and its Magic cost. Press a (or confirm the highlighted row) to pick it, and the aiming reticle opens exactly as it would for a wand.

Rows are lettered a to d, the way the pack’s are, and the menu is the only way to a spell – no key fires a slot directly. While the reticle is up, Tab snaps it to the next monster or item in view instead of nudging it one tile at a time.

Confirm the shot at something, and watch your Magic drop by two. Try it again with an empty pool: the reticle never even opens, and the log says why.

Step 6: where it stops being an item

Try the things that work on a potion, a wand, a dagger:

• Open the pack (i) and look for Ice Bolt. It isn’t there. A spell never enters a Backpack; the player’s copy of it lives only in Spellset.
• Try to throw it (t). There is nothing to select – the throw menu only ever lists Backpack contents, and a spell was never in one.
• Save and reload. Your Magic total survives, and so does your Spellset – models/src/saveload.rs round-trips it like every other piece of the player. If Ice Bolt ever left a marker of its own lying around on you (the way the spell Magic Ward or Bide does), that marker would need a row in the EFFECTS registry and an effects::lend to put it there – see ../how-to/add-a-spell.md for the two that already do.
• Give a monster the same trick. SpellEffect is a shared mechanic – ice_bolt doesn’t care who user is – and a monster casts from its spellset out of its own Magic. Chain .casts(3, &[SpellEffect::IceBolt]) on a bestiary row, and that creature is born with the spell and the Ma for three casts of it, and its rule set will pick it and fire it at you until the Ma runs out. The dragon’s Fireball is exactly that. See ../reference/agents.md.

None of that is a bug in what you built. It’s the shape of the thing: a spell is a mechanic on loan to whoever’s Spellset names it, not a possession with a life of its own on the floor.

Step 7: keep it or drop it

If you like Ice Bolt, leave it. If this was a dry run:

git checkout models/src/components.rs models/src/catalog.rs \
             models/src/items/spells.rs models/src/map/levels.rs

What you actually learned

• A spell is identified the same way a potion or a wand is: one enum variant, one catalog row, one arm of an exhaustive match that will not let a variant ship silent.

• Almost all of a spell’s behaviour is borrowed from whatever already does the thing – elemental_blast for a blast, crate::conditions for a status – the same reuse a wand’s own mechanic leans on.

• A spell is not an item, deliberately: no Position, no Item, no pack slot, no NIHILURK_SPAWN, nothing to throw or drop. It lives in a Spellset, and it costs Magic instead of running out of charges.

• A SpellEffect’s mechanic is shared and reusable — a monster can do the same trick, as the dragon does. .casts(...) on a bestiary row gives it the spell and the Magic to pay for it, and its rule set does the triggering.

Where to go next

../how-to/add-a-spell.md the short version, as a recipe add-your-first-item.md the same lesson, for items ../how-to/add-an-item.md the pattern this one borrows ../reference/input-and-turn-loop.md where spell_system sits in the schedule

Tutorial: give a monster a mind

Audience       Anyone who has added a monster and now wants it to
               behave differently, not just hit harder.
Prerequisites  `add-your-first-monster.md`, or the same comfort with
               the bestiary.
Time           About twenty minutes.
You will       Write one rule and one rule set, give them to the
               emu, test them on a percept you build by hand, and
               watch an emu run from you.

This is a lesson, not a recipe. When you want the short versions, read ../how-to/add-a-rule.md and ../how-to/add-a-rule-set.md.

What you are about to learn

A monster does not have behaviour code. Each turn it is handed a Percept (what is true right now, around it) and a RuleSet (an ordered list of rules). The first rule that fires decides the turn. That is all a mind is here. You will write a coward: an emu that fights anything next to it, but bolts the moment you come within three tiles, and otherwise stands still.

Step 1: look at a mind that already exists

Open models/src/agents.rs and find CHASER:

pub static CHASER: RuleSet = RuleSet {
    name: "chaser",
    leashed: true,
    rules: &[CAST, SHOOT, STRIKE, CLOSE_IN],
};

Read it as a sentence: cast a spell if it can, else shoot if it can, else strike what is next to it, else walk at the nearest foe, which is the player unless one of their allies stands nearer. Every emu on the floor thinks exactly that today.

Step 2: write the rule

There is no rule for “run when close”, so write one. Next to flee, add:

fn bolt_when_close(p: &Percept) -> Option<Action> {
    let player = p.foes.iter().find(|f| f.is_player)?;
    if chebyshev(p.at, player.at) > 3 {
        return None;
    }
    let (dx, dy) = toward(p.at, player.at);
    Some(Action::Step(-dx, -dy))
}

/// A noticed player within three tiles: step straight away from them.
pub const BOLT_WHEN_CLOSE: Rule = Rule {
    name: "bolt when close",
    fire: bolt_when_close,
};

Two things to notice. The rule reads only p: it never touches the world. And p.foes holds the player only once the emu has noticed them, so a player with a ring of stealth walks up to a coward unchased.

Step 3: write the set

With the other sets:

/// Bites what is next to it, bolts from a player who comes close,
/// and otherwise stands its ground.
pub static COWARD: RuleSet = RuleSet {
    name: "coward",
    leashed: false,
    rules: &[STRIKE, BOLT_WHEN_CLOSE],
};

The order is the personality. STRIKE first means a cornered coward still bites. Swap the two and it would rather run than bite, even with you standing on its toes.

Step 4: test it before you play it

In the tests module at the bottom of agents.rs:

#[test]
fn a_coward_bolts_then_bites_when_cornered() {
    let map = room();
    let e = entities(1);
    let mut p = percept(&map, (8, 6), (10, 6));
    p.foes = vec![sighting(e[0], (10, 6), true)];
    assert_eq!(think(&p, &COWARD), Action::Step(-1, 0));
    p.foes = vec![sighting(e[0], (9, 6), true)];
    assert_eq!(think(&p, &COWARD), Action::Strike(e[0]));
}

cargo test -p nihilurk-models --lib coward

No world was built. That is the point of a mind made of plain functions: the test is three lines of percept.

Step 5: give the emu the mind

A set is picked by the monster’s tactic. Add a variant at the end of MovementType in models/src/components.rs (a save writes it by position):

Cower,

Then build. The compiler lists every match that needs to hear about it. The one that matters is rule_set_for in agents.rs:

MovementType::Cower => &COWARD,

In models/src/monsters.rs, change the emu’s movement from Chase to Cower, and add Cower to the use MovementType::{...} line at the top.

Step 6: meet it

NIHILURK_SPAWN="emu" cargo run -p nihilurk

Walk toward it. At three tiles it runs. Corner it and it bites. Step back past three and it stops and watches. Walk out of the room: it does nothing at all, because a mob off your view never acts.

Step 7: keep it, or put it back

git checkout models/src

If you keep it, add the rule and the set to ../reference/agents.md.

See also

../reference/agents.md every rule, every set ../explanation/agents.md why a mind is a list

How to add a new playable body

Audience       Engine developer.
Prerequisites  ../explanation/ecs-in-nihilurk.md, ../how-to/work-with-the-ecs.md.
               ../tutorial/add-your-first-body.md is the long version,
               as a lesson, if you want to feel the save-marker bug first.
Result         A third hand-written `Body::Variant`, selectable with
               `-b <name>`, that survives a save/load round trip.

Not a content-table recipe. -am <species> already lets anyone wear a bestiary row (add-a-monster.md is that whole story) — this page is for the other kind of body, one written by hand the way the lurk was: its own dice, its own kit, its own rules about gear. Reach for this only when a species from -am genuinely won’t do.

The table

models/src/body.rs      ->  enum Body

Three variants today: Nihil (the default), Lurk, Monster(&'static MonsterDef). One enum, not a flag per body, because a player is exactly one of them and the argument parser has nothing to cross-check — see the doc comment at the top of body.rs before you touch it.

The recipe

Follow wear_lurk line for line; a fourth body is a sibling of it, not a new shape.

1. Add the variant.

   pub enum Body {
       Nihil,
       Lurk,
       Wraithkin,                       // new
       Monster(&'static MonsterDef),
   }
   

   Body::name() needs an arm too — it is what -b matches against and what an error about the body prints.

2. Write wear_wraithkin, next to wear_lurk. It inserts the starting Renderable, Fighter, Magic and Speed the same way, and grants whatever innate effects the body is born with through grant_all — a const &[Grant] slice, the same shape LURK_GRANTS uses, so it can be handed to grant_all unchanged. Pull every number out to its own constants::wraithkin module (see ../reference/constants.md below) rather than writing them inline — that is the one line wear_lurk itself would fail review on if it didn’t.

3. Wire it into wear:

   Body::Wraithkin => wear_wraithkin(world, player),
   

4. Give it a marker that survives a save. A monster body is the one body the save writes down (SaveGame::monster_body, the species id); the lurk is read back from its own Lurk effect marker, which rides the effect ledger like anything else a creature was born with. Your body needs the same: an effect (or existing marker) that (a) is already saved, and (b) nothing else in the game would attach to the player by accident. A new saved field changes the save format: see the EntitySave note in add-an-item-category.md.

5. Teach innate_tempo if the body doesn’t return to SpeedKind::Normal after a staircase lifts whatever the floor lent it (the lurk always returns to Quick).

6. Teach equip_refusal if the body can’t wear everything nihil can. The lurk refuses every slot but Slot::Finger; a monster body refuses everything unless its bestiary row carries ItemUser. Say why in the refusal string — it’s what the player reads when they try.

7. Wire the flag. engine/src/main.rs matches ("-b", "nihil") / ("-b", "lurk") literally; add ("-b", "wraithkin") => body = Some((models::Body::Wraithkin, "-b")). -b and -am already refuse being passed together and refuse an unrecognised name — nothing else to touch there.

8. brings_a_pack. Only Nihil returns true. Leave it that way unless the new body is meant to start holding a mace, which none of the hand-written ones are — the whole point is a body with nothing to buy.

Checks that will catch you

models/tests/it/body.rs and lurk.rs are the pattern to copy for a new wraithkin.rs, declared as mod wraithkin; in models/tests/it/main.rs and run with cargo test --test it wraithkin::. Build a World with StartingBody(Body::Wraithkin), call initialize_world, then assert the glyph, the dice, the grants, and that a save/load round trip comes back as the same body. Nothing else in the suite exercises a body that doesn’t exist yet.

cargo test --test it content:: won’t see this at all — a hand-written body is not a table row, so none of its checks apply. That absence is the tell that you’re outside the tables and should be moving carefully, not the sign that you can skip testing.

Ship it with the docs that describe it

Every one of these said something specific about the lurk when it landed, and will say something wrong about your body if you don’t touch it:

• ../reference/cli-and-env.md — the -b <body> section spells out each body’s dice, kit and quirks for the player.
• ../reference/constants.md — a row in the modules table for the new constants::<name> module.
• ../reference/components.md — the “what the player is” section, if the new marker or resource is worth a reader reaching for.
• MANUAL.md / doc/nihilurk.6 — the shipped manual page.

Appendix: quick check

1. Add the Body variant in models/src/body.rs, and its arm in Body::name().
2. Write wear_<name> next to wear_lurk, with every number in a new constants::<name> module.
3. Add the Body::<Name> => wear_<name>(world, player) arm in wear.
4. Give it a save marker: an effect already in EFFECTS that nothing else puts on the player.
5. Teach innate_tempo if the body does not return to SpeedKind::Normal.
6. Teach equip_refusal if the body cannot wear everything, and say why in the string.
7. Add the ("-b", "<name>") arm in engine/src/main.rs.
8. Leave brings_a_pack returning false.
9. Copy models/tests/it/body.rs and lurk.rs into a new test file named for the body: glyph, dice, grants, save round trip.
10. Run that test with cargo test --test <file>, then cargo test.
11. Fix the docs: update-the-docs.md, “A playable body”.

See also

../tutorial/add-your-first-body.md the long version, as a lesson ../reference/cli-and-env.md the player-facing story, -b and -am both add-a-monster.md the other way to play as something else add-an-effect.md writing the Grants a body is born with ../reference/components.md Body, MonsterBody, StartingBody ../explanation/combat-and-balance.md picking dice that don’t need gear to matter

How to add a monster

Audience       Content author.
Prerequisites  You have done `../tutorial/add-your-first-item.md`,
               or you are comfortable enough to skip it.
Result         A new species that populates floors, can be
               polymorphed into, can be created by a scroll, and
               can be played as with `-am <name>`.

One line in one table. There is no second place.

The table

models/src/monsters.rs      ->  BESTIARY

Every creature in the game is a row in it. Level population, the scroll of create monster, the wand of polymorph and the scroll of vorpalize weapon all draw from this table, so a row is a species everywhere at once.

The recipe

1. Open models/src/monsters.rs and find BESTIARY.

2. Copy a row that is close to what you want and change it. A basilisk, say – slow, armoured, nasty, and not something floor 1 should meet:

   MonsterDef::row("basilisk", 'b', Color::DarkGreen, Chase,
                   5, 10, 1, 10, 2, 5),
   

   The arguments, in order:

   name          "basilisk"          unique, lowercase, displayed
   glyph         'b'                 one character on the map
   color         Color::DarkGreen    see the palette note below
   movement      Chase               Static | Chase | Ambush | Flee | Confused
                                     picks its rule set: see
                                     ../reference/agents.md
   hp            5                   total hit points
   power         10                  attack die: damage rolls 1d10
   power_bonus   1                   flat, added once to that roll
   armor         10                  defence die: rolls 1d10
   armor_bonus   2                   flat, added once to that roll
   min_depth     5                   first floor it can appear on
   

3. Build and look at it:

   cargo build
   NIHILURK_SPAWN="basilisk" cargo run -p nihilurk
   

4. Run the table tests, which will now include your row:

   cargo test --test it content::
   

That is the whole procedure. Nothing else in the codebase needs to be told that basilisks exist.

The row you just wrote is also the whole recipe for playing as one: -am basilisk puts a player inside it, dice and innate magic and all – see ../reference/cli-and-env.md, “-am <species>”. Nothing about that is a special case for the player; it is the same row a floor-5 basilisk is built from. If what you actually want is a hand-written playable body, with its own kit and its own rules rather than a bestiary row worn as a costume, that is add-a-body.md instead.

Choosing the numbers

Copy the stat band your creature belongs to:

fodder      hp 1-2    power 4-8     armor 4-8       min_depth 1
mid         hp 3-6    power 6-10    armor 6-10      min_depth 5
deep        hp 8-12   power 8-12    armor 6-10      min_depth 10

Raise armor to make it hard to kill, power to make it frightening to stand next to, hp only to buy it one more exchange. Why that is so – and why nothing in the bestiary has thirty hit points – is ../explanation/combat-and-balance.md.

min_depth in use is 1, 5 and 10. Nothing stops you using 2 or 11.

Optional extras, chained on

Anything past the ten numbers is chained, so a plain creature stays one readable line.

Innate magic – attach effect components at birth:

MonsterDef::row("basilisk", ...).grants(&[Grant::of::<ColdImmune>()]),

The effect must already exist. See add-an-effect.md. There is a shorthand for the common one – .grants(ITEM_USER) – which makes a creature clever enough to catch thrown gear, wear it, and read scrolls that land on it.

Spells – a Spellset and the Magic to pay for it (the dragon):

MonsterDef::row("basilisk", ...).casts(3, &[SpellEffect::Thunderbolt]),

The first number is how many casts of its dearest spell the creature has the Ma for (MonsterDef::magic_pool): two for the beefy, three for the weak. The pool never refills; each cast spends the spell’s SpellDef::cost, and a dry caster goes back to its claws. A player wearing the row gets the spells in the spell bar.

Parts nothing can cancel – what the creature is, as opposed to magic it has. A wand of cancellation strips everything in .grants(...) except effects whose id is in IDENTITY_EFFECTS, so give the row such effects and cancellation leaves them. The dog is built this way:

MonsterDef::row("dog", ...).grants(DOG_GRANTS),

DOG_GRANTS is five grants, one per behaviour (any treat tames it, a charm makes it the Helper, it outranks the ordinary Helper, a kill may reshape it, and its death reveals a faerie shapeshifter with no gore), and all five are identity effects. The (d) is a (d)oppelganger, or rather a dogppelganger: a faerie shapeshifter wearing a dog. That is why nothing cancels what makes it a dog (bar its shapeshifting), why a kill can change its shape, and why no dog ever dies. What “dies” was never a dog. A shapeshift keeps whichever of them the old body held (monsters::reshape). To build a creature like that, write one effect per behaviour (add-an-effect.md, “An effect nothing can cancel”), list their ids in IDENTITY_EFFECTS, and grant them from the row. Keep the behaviours separate: one grant per atomic behaviour, so each can be given and tested on its own.

Born invisible – unseeable without see-invisible (the phantom):

MonsterDef::row("basilisk", ...).invisible(),

Rarity – how often it is drawn against the rest of the floor’s eligible pool. The default is DEFAULT_SPAWN_WEIGHT; leave it alone unless you mean it:

MonsterDef::row("basilisk", ...).weight(3),

See tune-rarity-and-depth.md.

Chains combine in any order:

MonsterDef::row("basilisk", 'b', Color::DarkGreen, Chase,
                5, 10, 1, 10, 2, 5)
    .grants(&[Grant::of::<ColdImmune>()])
    .weight(4),

Do not write Aggravated in a row. It is a fifth MovementType, applied at run time by the scroll of aggravate monsters. The four legal values for a row are the ones listed above; what each does is in ../reference/content-tables.md.

Only 16 colours survive a save. The file packs a colour into one byte against a fixed palette; anything off it – an RGB value, a 256-colour index – draws correctly and reloads as White. The palette is listed in ../reference/content-tables.md.

Renaming a row breaks old saves. A saved monster stores its row’s id (the name) and looks its species back up on load. Rename "basilisk" and every basilisk in an existing save comes back without its innate magic. Adding and removing rows is safe; renaming is not.

Checks that will catch you

cargo test --test it content:: fails if:

• two rows share a name (every_content_name_is_unique)
• your row cannot be built by name (every_content_name_spawns_and_...)
• a species turns up above its min_depth (a_species_never_appears_above_its_min_depth)

Glyph collisions are not checked. Two creatures may share a letter; the existing bestiary uses one letter per species by convention, and D is already the dragon’s.

Appendix: quick check

1. Copy the closest row in BESTIARY (models/src/monsters.rs) and change it.
2. Give it a unique lowercase name, a stat band from “Choosing the numbers”, and a min_depth.
3. Chain extras only if you need them: .grants(..), .casts(..), .invisible(), .weight(..).
4. Pick a colour from the sixteen in the palette, and never write Aggravated as the movement.
5. Never rename an existing row; saved monsters look their species up by id (the name).
6. Run NIHILURK_SPAWN="<name>" cargo run -p nihilurk and look at it.
7. Run cargo test --test it content::.
8. Fix the docs: nothing, unless the row brings a new mechanic (update-the-docs.md).

See also

../tutorial/add-your-first-monster.md the long version, as a lesson

add-a-body.md a hand-written body instead of a bestiary row add-an-effect.md give it a property nothing else has tune-rarity-and-depth.md where and how often it shows up ../reference/content-tables.md every field, every type, the palette ../reference/spawn-api.md MonsterDef::pick, spawn_monster ../explanation/combat-and-balance.md what the numbers mean

How to add a rule set

Audience       Engine developer.
Prerequisites  `../reference/agents.md`. For a rule that does not
               exist yet, `add-a-rule.md` first.
Result         A new way for a creature to think, picked by its
               tactic.

A rule set is an ordered list of rules. The first one that fires takes the turn.

Step 1: write the set

In models/src/agents.rs, with the other sets:

/// Keeps its distance and shoots; never closes in.
pub static SKIRMISHER: RuleSet = RuleSet {
    name: "skirmisher",
    leashed: false,
    rules: &[SHOOT, KEEP_DISTANCE, STRIKE],
};

Order is the behaviour. Write the set as a sentence first (“shoot if it can, otherwise back off, otherwise bite”) and list the rules in that order.

leashed: true keeps it from stepping out of a room into a doorway or a corridor. Only a set that hunts the player wants it.

Step 2: give it a tactic

A set is picked from the monster’s MovementType in rule_set_for. Add a variant at the end of the enum in models/src/components.rs (a save writes it by position), then one arm:

MovementType::Skirmish => &SKIRMISHER,

The compiler will not build until every match on MovementType has the new arm. Those are the places that still read the tactic directly (the renderer’s tints, the garrote).

Step 3: use it

Put the variant on a bestiary row’s movement column (add-a-monster.md).

Step 4: test it

A unit test in agents.rs per rule the set lists, built on percept(...): one where the rule should win and the ones before it should pass.

Verify

cargo test -p nihilurk-models --lib agents
NIHILURK_SPAWN="your monster" cargo run -p nihilurk

Then add the set’s row to the sets table in ../reference/agents.md.

Appendix: quick check

1. Write pub static <NAME>: RuleSet in models/src/agents.rs; the order of rules is the behaviour.
2. Set leashed: true only for a set that hunts the player.
3. Append a MovementType variant at the end in models/src/components.rs, and add its arm to rule_set_for.
4. Fix every other match on MovementType the compiler names.
5. Put the variant in the movement column of a bestiary row.
6. Test each rule the set lists: one case where it wins, one where an earlier rule passes.
7. Run cargo test -p nihilurk-models --lib agents and NIHILURK_SPAWN="<monster>" cargo run -p nihilurk.
8. Add the set’s row to the sets table in ../reference/agents.md.

See also

add-a-rule.md when no rule does what you need ../reference/agents.md every set, and what picks it ../tutorial/give-a-monster-a-mind.md the same thing, taught slowly

How to add a rule

Audience       Engine developer.
Prerequisites  `../reference/agents.md`.
Result         A new reflex any rule set can list.

A rule is a condition on the percept and the action it calls for, in one function. It answers None when its condition does not hold.

Step 1: write the function

In models/src/agents.rs, next to the other rule functions:

fn keep_distance(p: &Percept) -> Option<Action> {
    let near = p.foes.iter().find(|f| chebyshev(p.at, f.at) <= 2)?;
    let (dx, dy) = toward(p.at, near.at);
    Some(Action::Step(-dx, -dy))
}

Read only the percept. If the rule needs something the percept does not carry, add a field to Percept and fill it in ai::perceive. Never reach into the world from a rule: that is what keeps every rule testable on a hand-built percept.

If the rule needs chance, read p.roll. Do not roll your own.

Step 2: name it

/// A foe within two tiles: step straight away from the nearest.
pub const KEEP_DISTANCE: Rule = Rule {
    name: "keep distance",
    fire: keep_distance,
};

The doc comment is the rule’s one-line “fires when”: copy its shape from the others.

Step 3: list it in a set

A rule does nothing until a set lists it. See add-a-rule-set.md.

Step 4: test it

In the tests module of agents.rs, build a percept with percept(...), set the fields your rule reads, and assert what think returns for a set that lists it. Test both sides: once where it fires, once where it passes.

Verify

cargo test -p nihilurk-models --lib agents

Then add the rule’s row to the rules table in ../reference/agents.md.

Appendix: quick check

1. Write fn <name>(p: &Percept) -> Option<Action> in models/src/agents.rs; read only the percept, and take chance from p.roll.
2. Name it as a pub const <NAME>: Rule, with a one-line “fires when” doc comment.
3. List it in a rule set (add-a-rule-set.md).
4. Test both sides on a hand-built percept(...): once where it fires, once where it passes.
5. Run cargo test -p nihilurk-models --lib agents.
6. Add the rule’s row to the rules table in ../reference/agents.md.

See also

add-a-rule-set.md putting the rule to work ../reference/agents.md every rule that exists already ../explanation/agents.md why a rule may only read the percept

How to add a spell

Audience       Content author.
Prerequisites  You know where `models/src/catalog.rs` is. If not,
               do `../tutorial/add-your-first-spell.md` first.
Result         A new active ability the player can trigger from
               the `Z` menu, that costs Magic -- an
               aimed **attack** like a wand, or a self/room-wide
               **skill** like a potion or a scroll.

One enum variant, one catalog row, one arm of an exhaustive match. The same shape as a potion, a scroll or a wand – with one difference worth saying up front, and a fork partway through depending on which of the two you’re building.

A spell is not an item

Every other thing you can pick up in nihilurk is an entity: it has a Position on the floor, an Item marker, a pack slot, and a fate when you drop or throw it. A spell has none of that. It is never spawned, never lies on a floor, and cannot be dropped or thrown – there is nothing to drop.

A spell lives as a bare SpellEffect value inside a creature’s Spellset component:

pub struct Spellset {
    pub slots: Vec<SpellEffect>,
}

Today only the player has one, taught in play by a hero coin (an uncommon coin-table row that puts a random, not-yet-known spell straight into the taker’s Spellset, up to constants::spells::SPELLSET_CAP – four) rather than started with any. Giving a spell to the player for testing without going through the drop table means putting it in that Vec by hand – there is no NIHILURK_SPAWN for this, because there is no entity to spawn. See “Hold it in your hands” below.

The other consequence of not being an item: a spell costs Magic, not a battery. SpellDef::cost is spent by spell_system every time the player triggers it. A monster that does the same trick under its own steam – the dragon’s fireball, the eel’s thunderbolt – has a Spellset and a Magic pool of its own, put there by its bestiary row (MonsterDef::casts). It pays SpellDef::cost out of that pool through the same spell_cost the player does (pay_for_spell), and it never refills.

The recipe

Two steps are the same whatever you’re building; then the path forks on SpellKind.

1. Append a variant to SpellEffect in models/src/components.rs – at the end, never in the middle (see the warning below):

   pub enum SpellEffect {
       DragonBreath,
       // ... more variants ...
       GateDown,
       IceBolt,
   }
   

2. Add the row in SPELLS (models/src/catalog.rs):

   SpellDef { effect: SpellEffect::IceBolt, name: "Ice Bolt", cost: 2, range: 6, kind: SpellKind::Attack },
   

   cost is Magic points, multiplied by constants::spells::TURBO_MAGIC_COST_MULT when a staff (TurboMagic) is wielded and kind is SpellKind::Attack, never for a SpellKind::Skill. cost is also calibrated against constants::player::START_MAGIC and sits in one of four Magic-cost tiers, 1 through 4; the rows already in SPELLS show where each tier lands. range feeds the aiming reticle exactly like a wand’s Ranged, and is meaningless – leave it 0 – for a spell you’re about to make a Skill.

   List the spell in every_spell_has_a_catalog_row (models/tests/it/creature_casts.rs), in its match and in its all array. cargo test will not build until you do.

Which of the two you’re building decides everything from here.

Create an attack

An Attack opens the aiming reticle, deals damage (or a status a target can shrug off, like Thunderbolt’s paralyse), and is the one TurboMagic touches at all: a staff multiplies its cost by constants::spells::TURBO_MAGIC_COST_MULT and its damage by the larger TURBO_MAGIC_POWER_MULT, which is what makes the staff worth the Magic.

3. Write the mechanic as one arm of apply_spell_effect (models/src/items/spells.rs):

   fn apply_spell_effect(world: &mut World, user: Entity, target: Position, effect: SpellEffect, power_mult: i32) {
       match effect {
           SpellEffect::DragonBreath => breathe_fire(world, user, target, power_mult),
           SpellEffect::IceBolt => ice_bolt(world, user, target, power_mult),
       }
   }
   

   The match has no catch-all, the same as apply_wand_effect over WandEffect – step 1’s new variant will not build until this step gives it an arm. The compiler names the function and the missing variant, so there is nothing to remember. power_mult is constants::spells::TURBO_MAGIC_POWER_MULT when a staff multiplied the cost, 1 otherwise – fold it into your damage roll (multiply the final number, the way every existing Attack arm does; see sting, thunderbolt, force_lance for the shape when armour is or isn’t subtracted).

   Most of an attack’s mechanic is borrowed rather than written:

   • A blast at a point – breathe_fire, lux, meteor_strike all call elemental_blast (items/wands.rs), the same function a zapped or thrown wand calls. Pick a radius (BLAST_RADIUS for a zap-sized disc, GRENADE_RADIUS for a thrown-sized one), a damage roll, and an Element (or None for non-elemental).
   • A line – force_lance traces get_line(user_pos, target) by hand, stopping at the first wall, and rolls damage per creature it crosses. Copy it when the flavour is “a bolt” or “a beam” rather than “an explosion”.
   • A single target hit like a trap or a wand bolt – sting (the dart trap’s own formula, aimed rather than laid) and thunderbolt (a plain armour-ignoring roll, like a wand bolt) both just call crate::helpers::monster_at(world, target) and roll once.
   • Everything in view, no target needed – circle_of_death and frost_nova call crate::helpers::hostiles_in_view(world, user) instead of aiming at a point; pair this shape with step 4’s “no target” answer below.

   Whichever shape you pick, land the damage through helpers::apply_hit with a Hit::magic or Hit::elemental rather than writing to a Fighter’s hp yourself – that one call is what makes Magic Ward, elemental immunity and a petrified victim’s damage cap apply to your spell. See “Play fair with Magic Ward” below.

4. Say whether it needs a target. Every attack above that hits one aimed tile does; SpellEffect::needs_target (models/src/components.rs) lists the ones that don’t, because they hit everyone in view instead (Circle of Death, Frost Nova) – add your variant there if that’s the shape you picked in step 3, the same way WandEffect::needs_target carves the wand of light out from every other wand. Leave it out (needing a target is the default) for anything aimed.

Create a skill

A Skill never opens on damage. It changes the caster (Cure, Heal, Bide, Magic Ward, Haste Self), the floor around them (Setup), or borrows a scroll’s own effect outright (Identify, Magic Mapping) – and TurboMagic never touches its cost.

3. Decide if it needs a target at all. Almost none do – a skill works on the caster or on everyone in view, the same as a room-wide attack. Add your variant to SpellEffect::needs_target’s false list (models/src/components.rs) unless you are building the rare aimed skill (Polymorph Other is the one today: kind: Skill with a range, so a staff does not double its cost; treat target as step 3 of “Create an attack” would).

4. Write the mechanic, the same match arm as an attack, but built one of two ways:

   • Borrow a scroll wholesale. Identify and Magic Mapping are one line each:

     SpellEffect::Identify => super::scrolls::apply_scroll_effect(world, user, ScrollEffect::Identify),
     

     Reach for this whenever an existing scroll already does exactly what you want – a spell is a delivery method, not a reason to write the mechanic twice.

   • Write it fresh, reaching into crate::conditions for anything that changes the caster’s state (cure_one_condition, hasten, paralyse, …) the way cure_self and haste_self do, or lending a marker component through effects::lend the way magic_ward lends MagicWard for Lifetime::Floor and bide lends Bided for Lifetime::NextAction. A skill that plants something on the floor (Setup) reaches into crate::traps instead – see setup for spawning a revealed trap and springing it immediately if something is already standing there.

   power_mult is still a parameter every arm takes, by convention (every arm in the match has the same signature) – a Skill is free to ignore it, since spell_system never doubles a Skill’s cost.

Play fair with Magic Ward

Any damage your spell deals to another creature goes through helpers::apply_hit, the same way every existing damaging spell does:

if apply_hit(world, victim, Hit::magic(damage), Some(&line)) == 0 {
    return; // or `continue`, in a loop over several victims
}

Hit::magic (no element) and Hit::elemental (fire, cold, …) both set the hit’s magical flag, and apply_hit reads it: a warded victim takes nothing, the log says so, and wands::ward_ricochet plays the bounce. Hit::physical is the opt-out – steel, wood and gravity, which a ward is no help against.

No spell checks MagicWard by hand, and none should. apply_hit owns that question along with elemental immunity and the stone-chip cap, so routing through wands::elemental_blast gets all three for free – the blast calls apply_hit per victim itself. The only other ward check in the game is abilities::fire_on_hit, and it answers a different question: whether the trick riding on a landed blow takes hold. Roll damage straight onto a Fighter and your spell becomes the one hole in an otherwise complete shield, which is worse than it sounds: the player bought that immunity with three whole Magic points.

Hold it in your hands

There is no NIHILURK_SPAWN for a spell. In play the only way to learn one is a hero coin (see “A spell is not an item” above); to try Ice Bolt without hunting for a coin, replace the player’s starting Spellset::default(), in initialize_world (models/src/map/levels.rs), with:

Spellset {
    slots: vec![SpellEffect::IceBolt],
},

Build, run, and press Z to see it listed, then its row letter to aim it, or Alt+Q/W/E/R for slots one to four. Tab while aiming snaps the reticle to the next thing in view.

If this was a dry run, git checkout models/src/map/levels.rs along with catalog.rs, components.rs and items/spells.rs.

Append enum variants; never insert or reorder them. SpellEffect derives Serialize, and a save encodes a variant as its position in the enum – including inside a saved Spellset (see the next warning). Adding one at the end is safe; putting one in the middle silently turns a saved spell into a different one, for every save that had it.

Spellset does survive a save – models/src/saveload.rs round-trips it like every other piece of the player. So do the two marker components spells have left behind so far, MagicWard and Bided – but not through a field of their own: each is a row in the EFFECTS registry (models/src/effects.rs, "magic_ward" => MagicWard;) lent through effects::lend, and EntitySave::effects saves it by id with the Lifetime it is being held for. If your new spell leaves a marker of its own lying around outside Spellset, register it there and lend it; a component inserted directly is the one a reload quietly forgets.

A monster casts from its spellset, out of its own Ma. Its rule set picks one of the spells in its Spellset that its Magic can pay for, at random each turn, and fires it if it can (../reference/agents.md, the cast rule). To give a species your spell, chain .casts(n, &[SpellEffect::YourSpell]) on its bestiary row – that is all the dragon’s Fireball is. Only an Attack spell with a range is ever fired this way; a skill never is. A player wearing the row (-am) gets the spells in the spell bar and pays from the player’s Ma.

Verify what you added

cargo build
cargo test --test it spells::

There is no cargo test --test it content:: coverage for spells the way there is for monsters and items – SPELLS is not part of spawn_named or content_names(), because nothing about a spell is spawned. models/tests/it/spells.rs pins a spell’s mechanic instead: it pushes a WantsToCast onto SpellQueue and runs spell_system against a dummy. Copy sting_bites_like_the_dart_trap_it_borrows_from if your spell has a number worth holding still.

Then prove it by hand: give it to the player, aim it, and watch the log line spell_system prints ("You cast ___!") followed by whatever apply_spell_effect logs itself.

Appendix: quick check

1. Append a variant at the end of SpellEffect in models/src/components.rs.
2. Add the SpellDef row to SPELLS in models/src/catalog.rs: cost, range (0 for a skill), kind. List it in every_spell_has_a_catalog_row (models/tests/it/creature_casts.rs).
3. Attack: write the arm in apply_spell_effect (models/src/items/spells.rs), and land damage through apply_hit with Hit::magic or Hit::elemental.
4. Attack that hits everyone in view: add it to SpellEffect::needs_target.
5. Skill: add it to the needs_target list unless it is aimed, then write the arm, borrowing a scroll if one already does the job.
6. A marker the spell leaves behind: add it to EFFECTS and lend it through effects::lend.
7. Give it to a species with .casts(n, &[SpellEffect::<Name>]); only a ranged attack is ever cast that way.
8. Try it: put it in the starting Spellset in initialize_world, press Z, then revert that edit.
9. Run cargo test --test it spells::.
10. Fix the docs: nothing, unless it adds a constants:: module (update-the-docs.md).

See also

../tutorial/add-your-first-spell.md the long version, as a lesson add-an-item.md the pattern this one borrows ../reference/input-and-turn-loop.md where spell_system sits in the schedule

How to add a trap

Audience       Content author.
Prerequisites  Comfortable adding a row. See
               `../tutorial/add-your-first-item.md`.
Result         A new trap the dungeon lays on floors, that reveals
               itself in the usual three ways, and that survives a
               save.

Four edits, and the compiler enforces the last two.

The mechanics are one file:

models/src/traps.rs

The components a trap is built from – Trap, TrapEffect, TrapReveal, EntityMoved – are nouns and live in models/src/components.rs with everything else the ECS is made of. The three holds a trap can put on a victim (Asleep, Pinned, Rooted) are ordinary effects and live in models/src/effects.rs. You add a TrapEffect variant there; the row and the mechanic stay here.

The recipe

1. Append a variant to TrapEffect (in components.rs):

   pub enum TrapEffect {
       ...
       Dart,
       Pit,        // <- at the end; see the save-format warning
   }
   

2. Add the row to TRAPS (in traps.rs):

   TrapDef { effect: TrapEffect::Pit, name: "pit trap",
             glyph: '^', color: Color::Red, weight: 10, min_depth: 1 },
   

   The name is what the player sees once the trap is known – there is no separate label function to update. weight is how often the dungeon lays this one against the others it could lay; min_depth is the first floor it appears on. Every existing trap is 10 and 1, which is to say equally likely from the start.

3. Write the mechanic as an arm of apply_trap_effect:

   TrapEffect::Pit => pit_effect(world, victim, is_player, seen),
   

   apply_trap_effect’s match has no catch-all, so the compiler will refuse to build until you write this arm. That is deliberate: a trap that does nothing is not a trap.

4. Say what it looks like as an arm of trap_flourish:

   TrapEffect::Pit => {
       if let Some(mut fx) = world.get_resource_mut::<Particles>() {
           fx.poof(p.x, p.y, 0.0);
       }
   }
   

   Same deal: no catch-all, so the compiler refuses to build until the new trap answers “and what does it look like?”. A trap that springs with nothing on screen reads as a bug in the log. If the animation only makes sense once the mechanic has run – a teleport puffs on the tile the victim left – write an empty arm saying so and do it there, the way Teleport and Trapdoor do.

Then:

cargo build
cargo test --test it content::
NIHILURK_SPAWN="pit trap" cargo run -p nihilurk

Writing the mechanic

Look at what the existing six do, and reuse the pieces:

trapdoor_effect       moves the victim to the next floor down
snare_victim(...)     Holds the victim for `TrapDef.snare_turns` turns
                      (bear trap pins the feet, gas takes the turn)
teleport_effect       relocates the victim on this floor
arrow_effect          damage, and drops a real arrow on a miss
dart_effect           damage, plus a permanent bite of strength

If your trap snares, put the duration in the row’s snare_turns and let apply_trap_effect pass it through – no constant to add.

The arrow and dart also scale with depth. trap_damage_tier(depth) steps up at the depths in TRAP_DAMAGE_TIER_LAST_DEPTH, and it adds to the arrow’s roll and the dart’s drain. The bands and every per-tier amount are in constants::traps (TRAP_DAMAGE_TIER_LAST_DEPTH and friends). This band is the trap’s own – coarser than the floor-crowding map::difficulty_tier, on purpose.

Your arm receives:

world       the ECS world
victim      whoever the trap got -- may be a monster, not the player
is_player   whether it was
seen        whether the player can see this happen
trap_pos    where the trap is (or was), if you need it

A trap fires for monsters too. victim is whoever moved onto the tile. Write the log line through the seen / is_player pair the way the existing arms do, or the player will read second-person messages about a bat.

A trap fires for whoever is near it too. Shoot a trap, or catch one in a wand’s blast, and detonate_trap bursts it over the 3x3 around its tile: your arm then runs once per creature caught, none of whom is standing on the trap. So read victim’s own Position if you need where they are, take trap_pos as where the trap was, and do not assume the two are the same tile. The burst’s own damage (TRICK_SHOT_* in constants::traps) is dealt before your arm runs, and the trap entity is already despawned by then – an arm must never despawn it itself. spring_trap handles the stepped-on case; the bear trap’s “bites once” despawn lives there, not in the arm. Bursts also chain, so your arm can run while another trap’s burst is still resolving: re-read anything off the world that a burst could have changed, and never hold an Entity across a call that can explode.

Damage traps ignore the armour die but not the armour bonus. If your trap deals damage, subtract total_armor_plus(world, victim) and nothing else – see arrow_effect. Rolling a full opposed defence would make armour far better against traps than the design intends.

If your trap costs the victim turns, hold them: conditions::snare(world, victim, Grant::of::<Asleep>(), turns), or Pinned, or Rooted. Each is an ordinary effect held for Lifetime::Turns, aged down once per turn by effects::tick_effects and lifted when its clock runs out. Asleep forfeits the victim’s turn outright (player_incapacitated, and the AI skips the monster); Pinned only blocks movement – a swing still lands, a step is a bear_trap_thrash; Rooted is Pinned without the teeth. You do not have to implement any of that; you pick which hold and for how long.

The three run on their own clocks, so a victim can be asleep and pinned, and comes out of each when its own turns are up.

Reveal styles

Every trap rolls one of three discovery styles at spawn, with equal odds, and you do not choose it per row:

Sight       shows itself as soon as its tile enters the viewshed
Adjacent    stays hidden until the player is standing next to it
Triggered   invisible until it goes off

nihilurk has no “search” action, so these three are the only ways a trap ever comes to light before it bites. If you want a trap that is always visible or never visible, that is a change to TrapBundle::random, not to a row.

Append TrapEffect variants; never insert or reorder. A saved trap stores its effect as a position in the enum. Inserting a variant in the middle turns every saved trapdoor into something else.

What you never have to do

• Give the trap a label. TrapEffect::label() reads the row.
• Add it to a list of trap kinds. TrapDef::pick walks the table.
• Teach the save file about it, beyond the enum variant.
• Place it. Floor generation decides how many traps and where; the table decides which.

Appendix: quick check

1. Append a variant at the end of TrapEffect in models/src/components.rs.
2. Add the TrapDef row to TRAPS in models/src/traps.rs: weight, min_depth, and snare_turns if it holds.
3. Write the arm in apply_trap_effect; log through seen and is_player, and subtract total_armor_plus only.
4. Write the arm in trap_flourish, or an empty one that says why.
5. Run cargo build, then cargo test --test it content::.
6. Run NIHILURK_SPAWN="<name>" cargo run -p nihilurk.
7. Fix the docs: the TrapEffect line in ../reference/components.md (update-the-docs.md).

See also

tune-rarity-and-depth.md make a trap rare, or deep-only ../reference/content-tables.md the TrapDef fields ../reference/spawn-api.md TrapDef::pick, TrapBundle::from_def

How to add an effect

Audience       Content author reaching past the tables, or an
               engine developer.
Prerequisites  You have added a row (`add-a-monster.md` or
               `add-an-item.md`) and want it to do something no
               existing component covers.
Result         A property that a monster can be born with, a ring
               can lend, a wand of cancellation can strip, and the
               save file remembers.

An effect is a component on the creature, and both the dragon born fire-immune and the player wearing a ring of fire resistance carry the same one. (Why that is the whole design: ../explanation/data-driven-content.md.)

Everything here lives in:

models/src/effects.rs

Which kind do you need?

Marker      A yes/no property. "Fire does nothing to it."
            "It sees invisible things." Read as a query filter.

Modifier    A number that stacks across everything equipped.
            "+2 armour." "+2 on throws."

Cap         A ceiling the dice cannot beat. "At most 1 damage in
            melee." Folded with `min`, not `+`.

Markers are the common case. Take that branch unless your property is literally an integer that adds up, or a limit that overrides one.

There is one cap today (MeleeCap, carried by bows and crossbows) and it is read by one line of resolve_attack. It is written out by hand below the modifiers! rows rather than being one of them, because ceilings fold with min and the generated rows all fold with +. A second cap would be the moment to generalise that the way equipped_total is generalised over Modifier; see melee_cap in models/src/effects.rs.

Adding a marker effect

1. Declare the component in models/src/effects.rs, next to its relatives. It must be a unit struct deriving exactly this set:

   /// Poison does nothing to this creature.
   #[derive(Component, Default, Clone, Copy)]
   pub struct PoisonImmune;
   

   Default is not optional – it is how a Grant attaches the thing without knowing its type.

2. Add a row to EFFECTS, pairing a stable id with the component:

   effects! {
       ...
       "fire_quarrel"   => FireQuarrel,
       "poison_immune"  => PoisonImmune,      // <- your row
   }
   

   The id is what a save file stores. Write it out; never derive it from the type name, and never rename it once saves exist – the same rule a bestiary row lives by. Rows may be reordered and retired freely, because nothing about a row’s position means anything.

   An effect that ends on its own gets the line the player reads when it does, in brackets after the type:

   "asleep" => Asleep ["You shake off the drowsiness and come to."],
   

3. Hand it out from a row. Any of these, or all of them:

   // a species born with it
   MonsterDef::row("basilisk", ...).grants(&[Grant::of::<PoisonImmune>()]),
   
   // a ring that lends it while worn
   RingDef::new(RingEffect::PoisonResistance, "ring of poison resistance")
       .grants(&[Grant::of::<PoisonImmune>()]),
   
   // a launcher that lends it while held
   LauncherDef { name: "sling", color: ...,
                 grants: &[Grant::of::<FireStone>()] },
   

4. Ask about it where it matters. It is an ordinary component, so:

   // in a query
   Query<&Viewshed, With<SeesInvisible>>
   
   // ad hoc
   if world.get::<PoisonImmune>(target).is_some() { return; }
   
   // through the handle, when you only have a Grant
   grant.probe(world, entity)
   

That is the whole of it. Equipping and unequipping, saving and loading, and the wand of cancellation all work immediately, because all three walk EFFECTS rather than a list of special cases.

Never rename an id. The id, not the row’s position, is what a save file stores, so renaming one is renaming the thing on disk: every existing save comes back without that effect. Reordering rows and retiring them are both safe, and there is no ceiling on how many there can be – the u64 bitset that capped the list at 64 is gone.

An id a save names and the build has no row for is dropped, counted, and reported to the player in one line at the end of the load. Losing one property beats losing the run. This is what saving by name buys: a saved position would shift every later effect when a row retired, and nothing could tell, because every index would still be a valid index.

An effect missing from EFFECTS half-works. It will attach, and it will do its job for the rest of the session. It will not be saved, will not come back on load, and cannot be cancelled. This is the quiet failure to look for when an effect works until you reload. models/tests/it/abilities.rs catches it for anything armed by an ability row; nothing catches it for an effect only a mechanic reads.

Making an effect act on its own

Most effects are answers to a question something else asks. Some act by themselves, and ABILITIES in models/src/abilities.rs is all of those: one list, one row per ability, naming the Moment it fires at.

models/src/abilities.rs     ->  ABILITIES

Ability {
    effect: Grant::of::<AggravatesMonsters>(),
    when: Moment::EachTurn(AGGRAVATES_MONSTERS_CHANCE),
    player_only: false,
    action: |w, e, _| crate::items::aggravate_all_monsters(w, e),
    flavour: Some("You yip! The whole floor turns your way."),
}

when is the moment. The two commonest:

• Moment::EachTurn(chance) – while you carry it, something keeps happening: at this probability, on every turn the bearer acts. action runs on the bearer and reports whether it actually did anything; a ring of regeneration wins its coin flip every other turn, and most of those turns there is nothing wrong with the player to mend, so it returns false and stays silent.
• Moment::OnHit { glancing, lethal } – the attacker’s magic doing something to what it just hit. effect is the marker on the attacker, action runs as (attacker, target), and the two flags are the only gating there is: does a glancing scrape count (acid says yes, a charm that needs skin says no), and does the killing blow count (there is no point charming a corpse).

Three rarer moments round out the enum: OnDamaged (the bearer was hurt and lived), OnStruck (a blow landed on the bearer, and the attacker is passed to action – spikemail’s spike_prick) and OnTargeted (the player turned their attention on the bearer, whether or not the blow that follows lands – a gorgon’s gaze). A choice – a dragon breathing fire instead of biting – is not a moment at all: it is a rule in the creature’s rule set (../reference/agents.md). Adding a moment nobody has yet is a Moment variant and one arm in whatever drives it; adding an ability at a moment that already exists is one row here.

flavour is logged only when the bearer is the player and action returned true, so write it in the second person. player_only marks a row as the player’s own trick – a monster that steals or catches the weapon behind it still fights the plain way.

The row names the effect with the same Grant handle everything else uses, so the ability never learns what granted it. A ring grants it today; a cursed blade could grant it tomorrow and the behaviour would follow, untouched.

ability_system drives EachTurn at the tail of the turn schedule (after ai, before visibility_system), which is deliberate: a passive that moves its bearer – teleportitis – lands the jump at the top of the bearer’s next turn, so the player sees where they ended up and acts from there before anything else moves. combat::resolve_attack fires every OnHit row for a hit that dealt damage and has no idea what is in it – which is why the aquator’s corrosion and a scroll of monster confusion’s charm are rows here rather than special cases in that function.

Making an effect fire once, when gear goes on

A Grant is a property held while the gear is worn. An event at the moment of wearing is a different component, and it is not in EFFECTS:

#[derive(Component, Clone, Copy)]
pub struct OnWear(pub fn(&mut World, Entity, Entity));
pub struct OnDoff(pub fn(&mut World, Entity, Entity));

equipment::toggle_equipped fires it with (wearer, item) after the item is worn, named and known, and the function owns everything that follows – including tagging the item Consume if wearing it is what spends it (item_system re-checks for that tag after the toggle and destroys the item instead of stowing it). The ring of adornment is the only thing in the game that uses it. A row attaches it the way it attaches grants, and saveload reads it back off the row.

Adding a numeric modifier

Rarer, and a bigger change, because a number has to be added somewhere specific – there is no generic place a new number belongs.

1. Add a row to the modifiers! table in effects.rs, naming the component and the Loadout field it folds into:

   modifiers! {
       ...
       /// Flat modifier on how far the bearer can see.
       SightBonus => sight_bonus,
   }
   

   That row is the whole declaration. It gives you pub struct SightBonus(pub i32) implementing Modifier, a Loadout.sight_bonus field, and the line of Loadout::absorb that sums it – so the single-pass fold cannot leave one of your modifiers out. The rows are the only place a modifier is named.

2. Attach it from rows the way ArmorBonus is attached – see RingDef::armor_bonus and insert_modifier, which skips a zero so an inert row costs nothing.

3. Read it where it applies:

   equipped_total::<SightBonus>(world, entity)   // one number
   loadout(world, entity).sight_bonus            // already taking the fold
   

   Either sums the component across everything the entity has equipped plus anything it carries itself. Take the first when a caller wants one number and the second when it is already walking the gear for others – combat and the HUD both want the whole Loadout, and a sixth equipped_total call there would be a sixth walk over the same handful of items.

   This is the step no framework can do for you: PowerBonus is read in combat, ThrowBonus in the throw code, and your new one has to be read by whoever owns the number it modifies. A generated field nobody reads is inert, which is a visible nothing rather than a wrong number.

Modifiers are not in EFFECTS; they are saved as the values they are.

An effect nothing can cancel

A wand of cancellation strips every effect except the ones listed in IDENTITY_EFFECTS (models/src/effects.rs). The lurk’s body uses it, and so does every part of a dog. To make your effect one of them, add its stable id to that list. Nothing else changes: revoke_all puts the listed ids back with their ledger entry, so they are saved and still there after a reload.

Use it for what a creature is, not for magic it merely has. A dragon’s FireImmune stays cancellable on purpose, and a cancelled dragon loses it. Make a part uncancellable when taking it away would leave something that is no longer that creature: a dog that can be cancelled into an ordinary helper is not a dog.

Verify

cargo build
cargo test                   # save round-trips: tests/it/saveload.rs
NIHILURK_SPAWN="<a thing that grants it>" cargo run -p nihilurk

If your effect should survive a reload, the test worth copying is in models/tests/it/wands.rs: the one named cancellation_strips_the_magic_but_leaves_the_creature exercises the grant / probe / revoke path end to end.

Appendix: quick check

1. Marker: add a unit struct deriving Component, Default, Clone, Copy in models/src/effects.rs.
2. Add one "stable_id" => Type row to EFFECTS, and never rename the id later.
3. Hand it out with .grants(&[Grant::of::<Type>()]) on a monster, ring or launcher row.
4. Read it with a With<Type> filter, world.get::<Type>(e), or grant.probe(world, e).
5. Acts on its own: add one row to ABILITIES in models/src/abilities.rs, with its Moment.
6. Fires once on wear: attach OnWear from the row.
7. Number: add one row to modifiers!, attach it from rows, and read it with equipped_total.
8. Nothing may cancel it: add its id to IDENTITY_EFFECTS.
9. Run cargo test, spawn something that grants it, save, reload, and check it is still there.
10. Fix the docs: one row in the EFFECTS table in ../reference/content-tables.md (update-the-docs.md).

See also

add-a-monster.md .grants(…) on a bestiary row add-an-item.md .grants(…) on a ring or launcher ../reference/content-tables.md the effect registry as a table ../explanation/the-feel-layer.md giving it a look, and the rules for one work-with-the-ecs.md reaching the entity you want to change ../explanation/data-driven-content.md why effects are components ../explanation/ecs-in-nihilurk.md what a component is allowed to be ../explanation/adr-0006-effects-saved-by-id.md why an id, not a position

How to add a new item category

Audience       Engine developer, or a content author who has
               outgrown the eleven existing categories.
Prerequisites  You have read `add-an-item.md` and none of its nine
               categories fit. You are comfortable with bevy_ecs
               components and with Rust traits.
Result         A tenth kind of item that drops on floors, spawns by
               name, appears in `-content`, and survives a save.

Do this only when the thing you want is genuinely not one of the ten. A torch is a wand of light with a different flavour; a shield is armour. Reach for a new category when the item carries components no existing Def builds, and when it deserves its own share of the drop table.

Worked example below: food, a thing you eat for hit points.

Step 1: define the row

In models/src/catalog.rs, next to the other Def structs:

/// A ration: eaten once, then gone.
pub struct FoodDef {
    pub name: &'static str,
    pub color: Color,
    /// Hit points restored.
    pub nutrition: i32,
}

A row is a description, never behaviour. Keep it to plain data: what it is called, how it draws, and the numbers its components need.

You will also need the component the row attaches, in models/src/components.rs:

/// Eaten for hit points.
#[derive(Component)]
pub struct Food {
    pub nutrition: i32,
}

That component is the thing systems will read. The row only puts it on.

Step 2: implement ItemDef

impl ItemDef for FoodDef {
    fn name(&self) -> &'static str {
        self.name
    }

    fn spawn(&self, world: &mut World, pos: Position) -> Entity {
        world
            .spawn((
                Name { what: self.name.to_string() },
                Renderable { glyph: '%', color: self.color },
                pos,
                Item,
                Food { nutrition: self.nutrition },
                Consume,
            ))
            .id()
    }
}

spawn builds the item exactly as the row describes it, with no random rolls. That is what tests, spawn_named and NIHILURK_SPAWN all want.

If a floor drop should differ from the plain row – an enchantment, a battery charge, a bundle size – override spawn_as_loot as well:

    fn spawn_as_loot(&self, world: &mut World, rng: &mut ChaCha12Rng,
                     pos: Position) -> Entity {
        let e = self.spawn(world, pos);
        // roll whatever this category rolls
        e
    }

Categories with nothing to roll inherit the default, which just calls spawn.

weight() and min_depth() also have defaults (an ordinary weight, and the first floor). Override them only if this category wants per-row rarity – see tune-rarity-and-depth.md.

Step 3: write the table

#[rustfmt::skip]
pub const FOODS: &[FoodDef] = &[
    FoodDef { name: "ration",      color: Color::DarkYellow, nutrition: 8 },
    FoodDef { name: "slime mold",  color: Color::Green,      nutrition: 3 },
];

#[rustfmt::skip] keeps your column alignment. These tables are read as columns; that is worth more than uniform formatting.

Step 4: give it a share of the drop table

In models/src/spawn.rs, add one line to DROPS:

category!("food",         120,      1,     FOODS),

That single line wires up everything: floor drops, spawn_named, the -content listing, and the table tests. The macro erases the table’s element type into three function pointers so the whole thing can stay const; you never write those by hand.

Every other category’s share shrinks in proportion to pay for the new one. No other number needs editing.

Step 5: make it do something

Everything so far is description. If your item needs behaviour, that lives where behaviour lives – item_system in models/src/items.rs dispatches on the component your row attached, handing off to a file under models/src/items/ (potions.rs, scrolls.rs, wands.rs, throwing.rs). Follow how Potion is handled: a component the row put on, read by a system that does not know the catalog exists.

Step 6: teach the save file, if it needs teaching

An item is saved as its row’s id (content) plus a fixed set of component slots in EntitySave (models/src/saveload.rs). Your new Food component is not one of them, so by default a saved ration comes back as a nameless husk that does nothing.

Two ways out, cheapest first:

1. Rebuild it from the row. Extend restore_from_catalog in catalog.rs, which already does exactly this for weapons, ammo and launchers:

   if let Some(def) = FOODS.iter().find(|d| d.name == id) {
       entity.insert((Food { nutrition: def.nutrition }, Consume));
   }
   

   The row is the definition, so looking it up by id is always cheaper than storing what the row already says. Prefer this.

2. Add a field to EntitySave. Only when the value differs per entity – a battery’s remaining charges, a stack’s count. Add the field at the end of the struct, read/write it in save_game and load_game, and bump SAVE_VERSION.

EntitySave field order is the save format. Postcard encodes fields positionally. Append; do not insert or reorder. Any change to a saved struct needs a new SAVE_VERSION: the test the_save_layout_only_changes_with_the_version fails until it has one, then until you regenerate models/tests/golden/save.bin (its message says how). The release is then a minor one, and release/bump.lua refuses a patch.

Step 7: identification, if it is equipment

Only if your category is worn gear whose own quality should be a secret at first – a weapon, suit of armour or launcher with an enchantment plus and a curse it can roll. That means running it through crate::catalog::enchant_equipment at spawn time and letting KnownQuality gate the reveal, same as the three existing equipment categories; copy whichever is closest.

Every other category – including potions, scrolls, wands and rings – is always shown by its true name. There is no appearance system left to hook into; a ration is a ration, and so is a potion.

Verify

cargo build
cargo run -p nihilurk -- -content | grep -A3 '^food'
NIHILURK_SPAWN="ration" cargo run -p nihilurk
cargo test

The table tests pick your category up automatically: every_drop_category_can_actually_produce_something will fail if you gave it a weight of zero or no rows at its own min_depth, and every_loot_category_can_be_drawn_and_has_rows_to_give fails the same way, and also if it has no rows at the deepest floor.

Round-trip a save before you call it done – step 6 is the one people skip:

cargo test --test it saveload::

Appendix: quick check

1. Add the Def struct in models/src/catalog.rs and the component it attaches in models/src/components.rs.
2. Implement ItemDef: name, spawn, and spawn_as_loot, weight or min_depth only if you need them.
3. Write the table as a pub const with #[rustfmt::skip].
4. Add one category!(..) line to DROPS in models/src/spawn.rs.
5. Behaviour: hook the component into item_system and a file under models/src/items/.
6. Save: extend restore_from_catalog, or append a field to EntitySave and bump SAVE_VERSION; never insert one.
7. Worn gear with a hidden quality: run enchant_equipment at spawn and let KnownQuality gate it.
8. Run cargo run -p nihilurk -- -content | grep -A3 '^<category>' and NIHILURK_SPAWN="<name>" cargo run -p nihilurk.
9. Run cargo test, then cargo test --test it saveload::.
10. Fix the docs: update-the-docs.md, “A whole item category”.

See also

add-an-item.md the eleven categories that already exist tune-rarity-and-depth.md picking that weight ../reference/spawn-api.md ItemDef, DropCategory, the category! macro ../explanation/data-driven-content.md why rows carry components

How to add an item

Audience       Content author.
Prerequisites  You know where `models/src/catalog.rs` is. If not,
               do `../tutorial/add-your-first-item.md` first.
Result         A new item that drops on floors and survives a save.
               Equipment (weapons, armour, launchers) hides its
               enchantment plus and curse until worn or identified;
               every other kind is always shown by its true name.

Twelve categories. Six of them are a single row; the deck has one row and twenty cards. Four also need a name to be identified by, and three of those also need somebody to say what the thing does. Find your category below and follow that recipe only.

At a glance

Every table is in models/src/catalog.rs. Every effect enum is in models/src/components.rs. Every mechanic is in models/src/items/, one file per kind: potions.rs, scrolls.rs, wands.rs, throwing.rs (models/src/items.rs itself is just the item_system dispatcher).

Row-only categories

Weapon

WeaponDef::new("war hammer", Color::Grey, 9),

new(name, colour, power_die). The die is what the weapon is worth in a swing: damage rolls 1d[power_die]. Draws as ), worn in the hand slot.

Chain .missile(die) if it is built to be thrown – it then rolls that die on impact, is spent on what it hits, and can never be caught out of the air. Chain .piercing() if a throw should run the whole line instead of stopping at the first body.

WeaponDef::new("javelin", Color::DarkYellow, 5).missile(7).piercing(),

Chain .returning() if the throw should strike the first creature and fly home: into the pack, and back into the hand if the weapon was wielded. Leave off .missile() – a projectile is spent on what it hits.

WeaponDef::new("boomerang", Color::DarkYellow, 6).returning(),

Chain .hits(n) after .returning() and one throw strikes n creatures in all, each for full damage: the first in its way, then the nearest other enemy – one the player can see, or for a monster thrower, any in throwing range with a clear line. The moon blade’s 3: hit, hit, hit, home.

WeaponDef::new("moon blade", Color::Cyan, 3).returning().hits(3),

Any weapon can be thrown. .missile() is the difference between a purpose-built missile and a hurled lump of metal.

Chain .reach(n) for a weapon aimed with its own reticle (v) instead of a walk into the target’s tile – a bardiche’s 2, a whip’s 5. Add .reach_piercing() if the strike should run the whole line rather than stopping at the first body, the melee twin of .piercing().

Chain .grants(&[Grant::of::<SomeMarker>()]) for a trick the weapon lends its wielder while it’s in hand – exactly a ring’s own .grants(), and read by the same places a ring’s effects are: an ABILITIES row keyed on Moment::OnHit for something that fires when a blow lands, or a direct world.get::<SomeMarker>(attacker) probe for something checked elsewhere (the battle axe’s Cleaves, checked once from models::melee_attack). This is also how a weapon-only marker stays invisible to combat.rs and engine/ alike – see crate::effects’s module doc.

Chain .on_wear(OnWear(some_fn)) for a one-shot fired the instant it’s wielded – the staff’s “You’re a wizard now!” – the same mechanism a ring of adornment’s flourish uses. .on_doff(OnDoff(some_fn)) is its mirror, fired when the weapon is deliberately put away again (“You’re no longer that magical.”), and it is worth adding only when what the weapon lends is invisible on the HUD: the player has no other way to notice it leaving. It fires from equipment::toggle_equipped alone, never from force_unequip, so dropping it, being disarmed of it and dying with it say nothing.

WeaponDef::new("bardiche", Color::Grey, 7).reach(2).reach_piercing(),
WeaponDef::new("garrote", Color::DarkGrey, 0).grants(&[Grant::of::<VorpalOnCondition>()]),

Armour

ArmorDef { name: "brigandine", color: Color::Grey, armor_die: 6, grants: &[] },

armor_die is what wearing it adds to the defence roll: 1d[armor_die]. Draws as ], worn on the body. The existing nine run 2 (leather) to 9 (plate).

grants lends marker effects while it is worn, the same as a weapon’s .grants(). Spikemail’s &[Grant::of::<Spiked>()] is read by an ABILITIES row at Moment::OnStruck, the moment a blow lands on the bearer.

Coin

CoinDef { name: "electrum coin", color: Color::DarkYellow,
          effect: PickupEffect::Coin, amount: 2500, weight: 10 },

Coins are the pickup category: never carried, spent where they lie. A row is name, color, a PickupEffect, and one amount the effect reads (points, hit points, afflictions lifted). Adding a kind of coin means a PickupEffect variant and an arm in items/pickups.rs; adding another coin of an existing kind is one row. Draws as $.

Ammunition

AmmoDef { name: "bolt", color: Color::Grey, die: IMPROVISED_THROW_DIE, venom: false,
          launched_die: 5, launched_by: Grant::of::<FireQuarrel>() },

die is what one rolls hurled by hand (ammunition is no better thrown than a mace is: IMPROVISED_THROW_DIE); a wielder carrying the launched_by effect rolls launched_die instead. venom: true saps the victim’s power on every hit that draws blood, as the blowdart does. Stacks up to constants::items::STACK_LIMIT per pack slot, and arrives from the dungeon floor in bundles of constants::loot::AMMO_BUNDLE_MIN..=AMMO_BUNDLE_MAX.

If your ammunition answers to a launcher that does not exist yet, you need a new effect for the pair to meet at – see add-an-effect.md.

Launcher

LauncherDef { name: "sling", color: Color::DarkYellow,
              grants: &[Grant::of::<FireStone>()], melee_cap: 1 },

A launcher has no attack die and no armour die. All it does is put an effect on whoever holds it; ammunition that names the same effect is loosed rather than lobbed. Draws as }.

melee_cap is the most it is worth swung at something, whatever the dice or the enchantment say – 1 for both existing launchers. It is the price of the hand: a launcher fills the slot a sword would have, and nihilurk has no wait action to swap back with.

Neither half knows the other exists. That is why a sling is one row here and one row in AMMO.

Treat

TreatDef { name: "bone", color: Color::White, for_item_users: false },

A treat is thrown at a monster as an offer of loyalty and is never used. for_item_users says which monsters it is for: those with ItemUser (true) or those without (false). Stacks like ammo. Draws as %. What accepting one means is models/src/companion.rs.

Rings

A ring is a modifier item, exactly like a sword. Most of them have no behaviour code anywhere – they stack numbers through the same components combat already folds, and lend marker effects through Grants.

1. Append a variant to RingEffect in models/src/components.rs:

   pub enum RingEffect {
       ...
       MaintainArmor,
       FireResistance,      // <- at the end. See the warning below.
   }
   

2. Add the row in RINGS:

   RingDef::new(RingEffect::FireResistance, "ring of fire resistance")
       .grants(&[Grant::of::<FireImmune>()]),
   

Available chains:

.power_bonus(n)     flat modifier on the wearer's damage roll
.armor_bonus(n)     flat modifier on the wearer's armour roll
.throw_bonus(n)     flat modifier on everything they throw
.grants(&[...])     marker effects lent while worn
.on_wear(...)       a one-shot fired the instant it goes on

A bonus of zero attaches nothing, so an inert ring costs nothing at run time. Giving a ring a body is adding a chain to its existing row.

Reach for .grants(...) before anything else: if the property already exists as a marker some system asks about, you are done. If it does not, add the marker (../how-to/add-an-effect.md) and the one system that reads it – that is how stealth, regeneration, teleportitis and maintain armor were wired, and none of them put a line in catalog.rs beyond the row.

.on_wear(...) is the last resort, for a ring whose effect is an event rather than a property: it takes an OnWear(fn(&mut World, wearer, item)) and fires once, after the ring is worn and identified. The ring of adornment is the only one, and its function lives with the other two ring verbs in models/src/items/rings.rs.

Potions, scrolls and wands

These three are consumables with a mechanic, so they take three edits. The pattern is identical for all three; only the names change.

1. Append a variant to the effect enum in models/src/components.rs – PotionEffect, ScrollEffect or WandEffect.

2. Add the row in POTIONS, SCROLLS or WANDS.

   PotionDef { effect: PotionEffect::Levitation,
               name: "potion of levitation", color: Color::Cyan },
   
   ScrollDef { effect: ScrollEffect::Genocide,
               name: "scroll of genocide" },
   
   WandDef { effect: WandEffect::Digging, name: "wand of digging",
             color: Color::DarkYellow, range: 8 },
   

   Potions draw as !, scrolls as ? (always white), wands as /. A wand’s range feeds the aiming reticle; a wand always spawns with constants::wands::WAND_CHARGES, full.

3. Write the mechanic as one arm of the matching function:

   apply_potion_effect(world, user, effect) -> bool   models/src/items/potions.rs
   apply_scroll_effect(world, user, effect)            models/src/items/scrolls.rs
   apply_wand_effect(world, user, target, effect)      models/src/items/wands.rs
   

   A potion’s mechanic returns whether it visibly did anything.

Step 3 is the one the compiler makes you do. All three of those functions are exhaustive matches over their effect enum, the same as apply_trap_effect is over TrapEffect – no catch-all arm, so step 1’s new variant will not build until step 3 gives it one. The error names the function and the missing variant, so there is no guessing which of the three you forgot.

An explicit arm is still allowed to do nothing on purpose – the scroll of blank paper, and the two potions that are only a taste, sit in do-nothing arms today, each variant named rather than caught by a wildcard (see ../explanation/data-driven-content.md, “Where it does not reach”). The guarantee is only that you chose nothing, not that you forgot to write something.

Runes take the same three edits, with RuneEffect, RUNES and apply_rune_effect(world, user, effect) in models/src/items/runes.rs:

RuneDef { effect: RuneEffect::Ice, name: "rune of ice" },

A rune draws as ', always white. It is a scroll that goes inert when read instead of crumbling, and a staircase wakes it, so the mechanic is “what happens on each invocation” and never “what is left afterwards”. RuneEffect::Blank is the one variant with no row: a wand of cancellation makes it. Only the player invokes a rune.

Wands only: if your wand should not open the aiming reticle – it acts on the zapper or the room, like the wand of light – add it to WandEffect::needs_target in models/src/components.rs.

Append enum variants; never insert or reorder them. The save file encodes a variant as its position in the enum. Adding one at the end is safe for existing saves. Putting one in the middle silently turns every saved potion of healing into something else.

Potions, scrolls, wands and rings are always shown by their true name. There is no cosmetic appearance and no per-effect identification to keep in step with the catalog – add a row and it just works. Only equipment (weapons, armour, launchers) hides anything: its enchantment plus and cursed status, until KnownQuality says otherwise (see ../reference/components.md).

Verify, whichever you added

cargo build
cargo run -p nihilurk -- -content | grep '<your name>'
NIHILURK_SPAWN="<your name>" cargo run -p nihilurk
cargo test --test it content::

The tests check that names are unique, that every row can be built by name, that what spawns keeps its name, and that every drop category can still produce something.

To use the item and see what it does without a terminal of your own, play-through-a-pty.md types the keys for you and prints the screen.

You do not have to register the item, update the loot table, teach the save file about it, or teach combat about it. Why none of that is needed is ../explanation/data-driven-content.md.

Appendix: quick check

1. Find your category in “At a glance”.
2. Weapon, armour, coin, ammo, launcher, treat: add one row to its table in models/src/catalog.rs.
3. Ring: append a RingEffect variant at the end, then add the RingDef::new row.
4. Potion, scroll, wand, rune: append the effect variant at the end, add the row, write the arm in apply_potion_effect, apply_scroll_effect, apply_wand_effect or apply_rune_effect.
5. A wand with no reticle (it acts on the room or the zapper): add it to WandEffect::needs_target.
6. Never insert or reorder an enum variant; a save stores its position.
7. Run cargo run -p nihilurk -- -content | grep '<name>'.
8. Run NIHILURK_SPAWN="<name>" cargo run -p nihilurk, then cargo test --test it content::.
9. Fix the docs: the enum line in ../reference/components.md, and for a wand its table row (update-the-docs.md).

See also

add-an-effect.md a property no component covers yet add-an-item-category.md a whole new kind of item tune-rarity-and-depth.md make it rare, or make it deep ../reference/content-tables.md every field of every table ../explanation/data-driven-content.md why rows carry components

How to cut a release

Audience       The maintainer.
Prerequisites  A clean `master` with green CI, and crates.io
               Trusted Publishing set up once for each of the
               four crates (see "Before the first automated
               release").
Result         A new version on GitHub, with archives for two
               Linux machines, Windows and Apple Silicon Macs,
               and on crates.io, as four crates.
               One command and one push.

A release is release/bump.lua and a tag. The script edits the files, runs the checks and tags the commit. CI does the publishing when the tag is pushed. The push is the one step that cannot be taken back, and the script never does it for you.

Quick commands

lua release/bump.lua patch             bump, test, commit, tag
git push origin master vX.Y.Z          starts the release
gh run watch                           watch CI

Use patch, minor, major or an exact X.Y.Z. Two flags:

--dry-run      show every line that would change, and change nothing
--no-cargo     skip the cargo steps, if you have just run them yourself

The script prints the exact push command when it finishes, with the version filled in.

Which number to bump

The number says what an upgrade costs a player:

patch    0.1.3 to 0.1.4    nothing. Saves and everything else carry over.
minor    0.1.3 to 0.2.0    old saves stop loading.
major    0.2.0 to 1.0.0    everything from the old version is invalid.

So a release that breaks saves is a minor bump, and a release that breaks everything the old version made is a major one.

The script checks one cause. If SAVE_VERSION in models/src/saveload.rs changed since the last tag, it refuses any new version that keeps the same major and minor, so a save break cannot ship as a patch. A changed save layout cannot reach that point without a new SAVE_VERSION: the_save_layout_only_changes_with_the_version fails until it has one (add-an-item-category.md). The other usual cause is a renamed content row, because a save stores row ids (add-a-monster.md). Nothing catches that, so read the diff since the last tag for renames.

What the script does

It refuses, and edits nothing, if the working tree has uncommitted changes, if you are not on master, if the tag already exists, if the new version is not greater than the current one, or if SAVE_VERSION changed since the last tag and the new version keeps the same major and minor. Then it edits:

the four published crates     `version`, and every `path` pin on
                              a dependency line
doc/nihilurk.6                the version and date in the `.TH` line
aur/PKGBUILD                  `pkgver`, and `pkgrel` back to 1
README.md                     the four download links and the
                              version in the line above them

All four crates move to the same number, so there is one version to think about. engine/tests/workspace.rs fails if one crate or one pin falls behind. compat/ is a test rig and is left alone.

Then, unless --no-cargo: cargo update --workspace refreshes Cargo.lock (it touches only the four workspace lines, no dependency moves), cargo test --locked runs the suite, and cargo publish --workspace --dry-run proves all four packages build. If a step fails, the edits stay in the working tree and git checkout . puts them back. When they pass, it commits Release vX.Y.Z and tags it.

release/bump_test.lua runs the script in a throwaway repository. Run it with lua release/bump_test.lua after you change the script.

What CI does

Pushing the tag starts .github/workflows/release.yml:

check The tag has to be v plus the version in engine/Cargo.toml. Then cargo test. build One runner per machine. Builds, unpacks and plays each tarball. publish Creates the GitHub release with the tarballs. crates-io Publishes the four crates, in dependency order. It skips any version crates.io already has, so a failed run can be run again.

publish and crates-io run in parallel once build is green. A failure in check or build stops both, and nothing reaches GitHub or crates.io.

crates-io uses Trusted Publishing: the job trades GitHub’s identity token for a short-lived publish token. No secret is stored in the repository.

Before the first automated release

Do this once. It is the one part CI cannot do for you. For each of nihilurk, nihilurk-models, nihilurk-strings and nihilurk-particle-core, open the crate’s settings on crates.io and add a trusted publisher with:

GitHub user         bae-alves
Repository          nihilurk
Workflow filename   release.yml
Environment         (leave empty)

A crate has to exist before it can have a trusted publisher. All four do.

To check the setup without releasing anything, rehearse it:

gh workflow run release.yml --ref master
gh run watch

The rehearsal job asks crates.io for a publish token and discards it. A pass proves crates.io accepts this repository and release.yml. It does not prove all four crates are configured, because crates.io does not report which crates the token covers: look at each crate’s settings once. Nothing is built or published, and the jobs that need a tag skip themselves.

When it goes wrong

The script refuses Read the message. It names the cause and changed nothing. A cargo step in the script fails Fix the cause, then git checkout . and run it again. check or build fails Nothing was published. Fix it, delete the tag locally and on GitHub, and run the script again: git tag -d vX.Y.Z git push origin :refs/tags/vX.Y.Z crates-io fails part way Re-run the failed job from the Actions tab. It skips what is already published. The tag is on GitHub, no run starts Delete the remote tag and push it again at the same commit. A bad version is live cargo yank --version X.Y.Z nihilurk for each crate. A yank stops new projects from picking it up. It does not delete it.

The manual versions of these steps are in publish-to-crates-io.md and publish-a-github-release.md, for the day CI cannot publish.

Adding another place to publish

Each place is one job in release.yml. Give it needs: build (or needs: publish if it uses the GitHub release), keep its credentials in repository secrets, and gate it on a repository variable such as vars.AUR_ENABLED == 'true' until the account behind it exists. A new job does not change the script, because the script only edits files and tags.

The AUR package is not published by CI yet. The script bumps pkgver, and the repo’s PKGBUILD carries SKIP for the sha. Until an AUR job exists, publishing there is a hand step after the tag: see “Updating the AUR package” in publish-a-github-release.md.

See also

../../release/bump.lua                the script
../../release/bump_test.lua           its test
../../.github/workflows/release.yml   what the tag starts
publish-to-crates-io.md               the manual path to crates.io
publish-a-github-release.md           the manual path to a GitHub release

How to play the game from a script

Audience       Anyone who changed the game and wants to see it work
               in the real terminal, with no terminal in front of
               them: a content author, an engine developer, or
               Claude Code.
Prerequisites  A Linux box with `script` (util-linux), `lua` and a
               Rust toolchain. `spawn-a-thing.md` says what
               `NIHILURK_SPAWN` does.
Result         The screen the game showed after your keys, and the
               cells that sit on a coloured background, printed as
               text.

Tests say a rule holds. They cannot say how it looks, and nobody tests that on purpose (../explanation/adr-0004-no-tests-of-presentation.md). The way to check a look is to play. .claude/skills/play-nihilurk/play.sh plays for you: it starts the game in a pty, types the keys you list, waits, and prints the screen. It builds the game first. The game runs from a scratch directory with -ns -nobones -nshake -nb, so it writes no save or bones. The scratch directory is also its data directory, so it never reads your keymap or writes to your leaderboard and morgue.

.claude/skills/play-nihilurk/play.sh -S "rune of ice,aquator" ' ' @1 '?'

The keys

Each argument is one key, typed as it stands. printf %b runs on it, so '\r', '\e' and '\t' are Enter, Escape and Tab. Four words are not keys:

?       print the screen as it is now
%       list the cells on a coloured background
@SECS   wait that long before the next key
#TEXT   print a note with the screens; sends nothing

The screen prints once more when the keys run out. A key waits -d seconds (0.4 by default) before the next one goes in. The other options are -s SEED, -S LIST (that is NIHILURK_SPAWN), -a "FLAGS" for the game (-a "-b lurk"), -w SECS for the first frame, -z RxC for the terminal size (25x80 by default, the smallest the game draws cleanly), and -k FILE to keep the raw bytes.

A walk-through: read a rune next to an aquator

A seed fixes the floor, so look first, plan the walk from what you see, then replay it.

play.sh -S "rune of ice,aquator" ' ' @1 '?'

The first frame has a --MORE-- that needs a Space. The map shows the rune ' up and to the left of you and the aquator A right of it. Step onto the rune (items are picked up as you walk over them), read it with r and the pack letter, and look:

play.sh -S "rune of ice,aquator" ' ' @1 y @2 ' ' r f @4 '#after the nova' '?' '%'

f is the first spawned item because nihil starts with a to e. A lurk starts empty, so there it is a; press i to be sure.

Reading colour

The screen is text. Colour is how the game marks a monster that cannot fight at full strength, and % prints it as ROW COL GLYPH COLOUR in the names crossterm uses:

== backgrounds ==
4 19 U Cyan

That line is an ur-vile on a cyan square: paralysed. The tints and what each one means are in ../reference/rendering.md. Run the same keys without the step that should cause the tint, and the list is empty: that is your control.

What wastes a run

• --MORE-- eats keys. Send a Space after anything that logs several messages, and wait (@2 to @4) after anything animated. The log paints letter by letter, so an early screen shows half a sentence. Read the effect off HP, the badge row, the pack, the map and %, and use the log as a hint.
• o explores and picks things up, and any key pressed during it stops it. Put @2 after it. It refuses while a hostile is in view.
• You cannot pass a turn. To give monsters time, walk away from them.
• The first step can kill. A dragon one-shots nihil, and a lurk has 6 HP. An orc takes most of nihil’s 12 HP. To test an effect on a monster, spawn an aquator: awake, hostile, 9 HP, weak hits. Use a troll or a quagga when the test needs more. A yeti is immune to cold, and a red demon and a gnome are peaceful, so a spell that needs a hostile target ignores them.
• Aiming: z, the wand’s letter, direction keys to move the cursor, '\r' to fire, x to cancel.

Hold a game open

play.sh replays its keys from the start every time. To play one run a key at a time, start it once with agent/serve.sh and send keys with agent/act.sh:

a=.claude/skills/play-nihilurk/agent
d=$(mktemp -d)
NIHILURK_BIN="$PWD/target/debug/nihilurk" NIHILURK_SPAWN=aquator $a/serve.sh start "$d" -s 1
$a/act.sh -d "$d" ' ' l     # one call per step; the run waits in between
kill "$(cat "$d/pid")"

NIHILURK_BIN is the binary to run, as an absolute path. Without it, start runs the nihilurk on PATH. Game flags go after the directory.

To hand the run to a player outside the machine, serve it from a container on a TCP port instead:

cargo build -p nihilurk --target x86_64-unknown-linux-musl
docker build -t nihilurk-agent -f $a/Dockerfile .claude/skills/play-nihilurk
docker run --rm -d -p 127.0.0.1:7777:7777 \
    --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges --pids-limit 128 \
    -v "$PWD/target/x86_64-unknown-linux-musl/debug/nihilurk:/usr/local/bin/nihilurk:ro" \
    nihilurk-agent -s 1
.claude/skills/play-nihilurk/agent/act.sh ' ' l l

The image holds only the server. The game is a static binary built on the host and mounted in, so it never compiles inside Docker. Arguments after the image name are game flags, and -e NIHILURK_SPAWN=... passes through. act.sh without -d connects to 127.0.0.1:7777. Either way, the server, serve.sh, runs the game in a pty with -ns -nobones -nshake -nb -anim-rate 0.1, with the run’s directory as its data directory. Each line a client sends is one key, in the notation above. Once the game signals that it waits on a key, the server answers with a percept: the 25 screen rows, a ROW COL GLYPH COLOUR line for each tinted cell, then end. Once the game has exited it answers over, and keeps answering every new connection with the last percept and over, until docker stop in the container. Sessions take turns, in the container and on the host: one that arrives mid-session waits for the other to hang up. A run that no session has touched for NIHILURK_IDLE seconds (default 1800, 0 never) is killed and answers over from then on, and a session that sends nothing for that long is hung up on. A line longer than 4096 bytes is cut into keys of that size. A client gets a percept on connect and one per line after that, so it acts only on what it has seen. It can hang up at any point, and the run waits for the next connection. act.sh connects through bash’s /dev/tcp, so any line-based client works, nc included.

The protocol has no login: whoever reaches the port plays the run. Publish the port on 127.0.0.1, as above, unless the player is on a network you trust. The second docker run line keeps the container read-only, with no capabilities and a cap on processes, and the server inside runs as an unprivileged user. serve.sh listen binds 127.0.0.1 unless NIHILURK_BIND says otherwise; the image sets it to 0.0.0.0 so Docker can map the port.

The server sets NIHILURK_READY for the game, which then writes a signal each time it blocks for a key (../reference/cli-and-env.md). Auto-explore, a paralysed turn and particles never signal, so their output reaches a percept only after they have finished, however long they take. A game that never signals, such as a build from before the signal, gets a percept after 250 ms without output instead. The signal changes nothing on screen, so a seed and the same keys give the same percepts.

Its own tests

bash .claude/skills/play-nihilurk/play_test.sh
lua .claude/skills/play-nihilurk/screen_test.lua
bash .claude/skills/play-nihilurk/agent/serve_test.sh

play_test.sh runs the driver against cat, printf and sleep, so it needs no build. screen_test.lua checks the screen reader. agent/serve_test.sh runs the socket server over stdio against stand-ins, so it needs no Docker and no socat. None of them runs in CI or in the pre-commit hook.

See also

spawn-a-thing.md put the thing in front of you add-an-item.md the recipe whose last step is “look at it” ../reference/rendering.md the status tints % reports ../reference/cli-and-env.md the flags and NIHILURK_SPAWN ../explanation/adr-0004-no-tests-of-presentation.md why a look is checked by playing

How to publish a GitHub release

Audience       The maintainer, cutting a release.
Prerequisites  Push access to the repository. The version bumped
               and committed, as in
               `publish-to-crates-io.md`.
Result         A GitHub release with one tarball per machine, each
               with a checksum, built and checked by CI.

This is the manual path. release/bump.lua does the bump and the tag for you: see cut-a-release.md.

Pushing a tag is the whole procedure. .github/workflows/release.yml does the rest, and it cannot be undone from your side once the release is public, so check the version before you tag.

Quick commands

cargo test                            green before you tag
git tag vX.Y.Z                        the number in engine/Cargo.toml
git push origin vX.Y.Z                starts the workflow

Watch it with gh run watch. When the publish job finishes, the release is at https://github.com/bae-alves/nihilurk/releases.

To try the packaging on your own machine before you tag, without CI:

release/test_package.sh x86_64-unknown-linux-musl

It builds all four languages with fat LTO, so it takes a few minutes, then unpacks the tarball and runs it.

What the workflow does

Four jobs. check runs first, then build, then publish and crates-io side by side. Any failure stops the ones after it.

check Fails if the tag is not v plus the version in engine/Cargo.toml, then runs cargo test. build One runner per target. Runs release/test_package.sh, which calls release/package.sh and then plays with the result. Uploads the tarball and its .sha256. publish Collects every tarball and creates the release with generated notes. crates-io Publishes the four crates to crates.io, skipping any version already there. See cut-a-release.md.

The targets:

x86_64-unknown-linux-musl     ubuntu-24.04
aarch64-unknown-linux-musl    ubuntu-24.04-arm
x86_64-pc-windows-msvc        windows-latest
aarch64-apple-darwin          macos-latest

The runner images are named, not ubuntu-latest. GitHub moves that label to Ubuntu 26 on 2026-10-19, which would change the musl-tools the build installs without a commit in this repository. Move to a newer image on purpose, and run release/test_package.sh first.

The workflows use actions/*@v4. They run on a forced Node 24 and print a deprecation note. They are not bumped, because only a tag exercises the release workflow, and a bump there would go untested until the release it breaks.

Windows gets a .zip of .exe files and the other targets a .tar.gz. release/package.sh and release/test_package.sh run in bash on all three systems, and the workflow names shell: bash because Windows would otherwise run a .sh file in PowerShell and report success. Windows has no LANG, so the dispatcher starts English there; nihilurk --lang pt picks another language. A macOS download from a browser is quarantined by Gatekeeper, since the binaries are not signed: xattr -d com.apple.quarantine nihilurk* clears it.

The Linux builds are musl, so each is one static file with no glibc to match. ../explanation/cross-platform-testing.md says why that is a promise and not a preference.

What is in a tarball

nihilurk-<version>-<target>/
    nihilurk          the dispatcher; picks a language from $LANG
    nihilurk-en       the English game
    nihilurk-pt       Portuguese (beta)
    nihilurk-es       Spanish (beta)
    nihilurk-ht       Haitian Creole (beta)
    nihilurk.6        the man page
    MANUAL.md
    LICENSE

The five binaries must stay in one directory. The dispatcher looks for nihilurk-<lang> next to itself and exits if it is not there. A user can put the directory anywhere, or install the files into /usr/local/bin.

What CI shows

Every tarball is unpacked and run by CI on the machine that built it: the dispatcher has to start all four language binaries, and the four have to differ. That proves each binary launches and that the packaging is right. It is not a playtest.

Adding a target is one line in the matrix of release.yml. Windows was played by a person before it went in. The macOS build has not been played yet: CI is all it has.

Updating the AUR package

aur/PKGBUILD is bumped with everything else. release/bump.lua sets pkgver in the release commit, so the PKGBUILD names the tag that commit gets, and aur_check.sh builds that tag with the PKGBUILD as written.

The repo copy carries sha256sums=('SKIP'). A real sha exists only once the tag does, and it would be stale from then on. The copy that goes to the AUR needs the real one, and aur_check.sh does not compare it.

CI does not publish to the AUR yet, so until it does that is a hand step after the tag exists. Work on a copy, and never commit the result:

cp -r aur /tmp/aur-publish && cd /tmp/aur-publish
updpkgsums                     writes the real sha256sums
makepkg --printsrcinfo > .SRCINFO

then push PKGBUILD and .SRCINFO to the AUR repository. Run ./aur_check.sh in the repository first: both trees must be green.

When it goes wrong

check says the tag disagrees Delete the tag, bump the version, commit, tag again: git tag -d vX.Y.Z git push origin :refs/tags/vX.Y.Z One build job fails Read its log. The same command runs on your machine as release/test_package.sh <target>. Fix, delete the tag, tag again. publish fails after the builds pass Re-run the failed job from the Actions tab. The artifacts are kept for the run. The tag is on GitHub, no run starts Happened on 2026-10-01, when the tag went up in the same push that first brought release.yml to GitHub. The cause is not confirmed. gh run list shows nothing. Delete the remote tag and push it again at the same commit: git push origin :refs/tags/vX.Y.Z git push origin vX.Y.Z A bad release is live gh release delete vX.Y.Z --yes, then git push origin :refs/tags/vX.Y.Z. Anyone who already downloaded it keeps it.

See also

publish-to-crates-io.md                    the other half of a release
../../aur_check.sh                         builds the PKGBUILD's pinned tag and this tree
../explanation/cross-platform-testing.md   why the Linux builds are musl
../../release/package.sh                   the build, one target
../../release/test_package.sh              the check on that build
../../.github/workflows/release.yml        the workflow itself

How to publish the documentation site

Audience       The maintainer, and anyone who changes how the site
               looks or what it lists.
Prerequisites  mdBook 0.5.4 (`cargo install mdbook --locked
               --version 0.5.4`) to build it on your machine, and
               Lua. CI needs neither from you.
Result         `MANUAL.md` and `docs/` on GitHub Pages as a site a
               search engine or an AI crawler can read, with a
               sitemap, `robots.txt` and `llms.txt`.

The site is not a second copy of the docs. site/build.lua stages the pages from where they live, and mdBook turns them into HTML. Nothing it makes is committed.

Quick commands

lua site/build.lua                     stage the pages in target/site-book/
mdbook build target/site-book          build the site into target/site-book/book
mdbook serve target/site-book          read it at localhost:3000
lua site/build_test.lua                the script's test

Pushing to master runs .github/workflows/pages.yml when README.md, MANUAL.md, docs/, site/ or the workflow changes.

What the script does

It copies README.md, MANUAL.md and every page under docs/ into target/site-book/src/, keeping their paths. Then:

links         a backticked path that names a page, such as
              `../reference/cli-and-env.md`, becomes a link. A path
              that names nothing stays as written. Code blocks are
              left alone.
SUMMARY.md    the contents list: the landing page, the manual, then
              tutorials, how-to guides, reference, explanation.
              Each entry takes its title from the page's first heading.
sitemap.xml   one line per page.
robots.txt    allows everything and points at the sitemap.
llms.txt      `site/llms.txt`, for AI answer engines.

It refuses a page with no heading, and names it.

The site URL is site-url in site/book.toml, and nowhere else. The script writes it into the sitemap, robots.txt, llms.txt and the structured data in site/theme/head.hbs. A custom domain is a one-line change there.

The facts a crawler reads

site/llms.txt states what nihilurk is, the install line, the languages and the license. Each of those is a fact that README.md or engine/Cargo.toml also holds. When you change one, change both: nothing checks it.

The description in site/book.toml is the one every page shares. mdBook has no description per page.

Before the first deploy

Do this once. In the repository’s Settings, under Pages, set Source to “GitHub Actions”. Then run the workflow from the Actions tab, or push a change under docs/. Check https://bae-alves.github.io/nihilurk/sitemap.xml.

Then tell the search engines. Submit that sitemap in Google Search Console and Bing Webmaster Tools. Both need your account, so no script does it.

When it goes wrong

The script names a page    That page has no heading. Add one.
A build warning about      Prose holds a bare `<word>`, which HTML
an unclosed HTML tag       reads as a tag and hides. Put it in backticks.
The workflow says the      Source is not set to "GitHub Actions" yet.
site is not enabled
mdBook moved on            The version and its checksum are two
                           lines in `pages.yml`. Change both, build
                           it here first, and run `sha256sum` on the
                           tarball.

See also

../../site/build.lua                  the script
../../site/build_test.lua             its test
../../.github/workflows/pages.yml     what a push to master starts
update-the-docs.md                    which pages a change touches
../explanation/documentation-style.md the house style the pages keep

How to publish nihilurk to crates.io

Audience       The maintainer, cutting a release.
Prerequisites  A crates.io account and an API token
               (`cargo login`). A clean working tree, and the
               release committed and tagged. A verified email on
               the account: crates.io refuses an upload without one.
Result         Four crates on crates.io, and `cargo install
               nihilurk` gives a stranger the game.

This is the manual path. A release is lua release/bump.lua and a tag push, and CI publishes: see cut-a-release.md. Use this page when CI cannot.

Publishing is the one step in this repository that cannot be taken back. A version, once uploaded, can be yanked but never deleted, and a crate name is held for good. Everything before the last command is a dry run. Do those first, every time.

Quick commands

cargo test                                   workspace still green
cargo publish --workspace --dry-run          package and build all four
cargo publish --workspace                    the real upload, in order

--workspace sends the crates in dependency order. compat is skipped on its own, because it is publish = false.

crates.io limits how fast a new crate can appear: a burst of about five, then one every ten minutes. A first upload of all four fits in the burst. A fifth new crate would wait.

What goes out

Four crates, in the order cargo sends them:

nihilurk-particle-core   particle-core/   the `no_std` arithmetic
nihilurk-strings         strings/         every sentence, per language
nihilurk-models          models/          the game
nihilurk                 engine/          the binary

The directories keep their short names. Only the package names carry the game’s name, and [lib] name keeps the short library names, so use models::*; still compiles. ../explanation/adr-0002-two-names-per-crate.md has the reasoning.

compat/ does not go out. It pulls in ratatui, which the shipped binary may not depend on, and nobody installs a test rig.

Before the first upload

1. Pick a version no tag has used. Bump every crate that changed, and the version = "..." on each path dependency that points at it:

    engine/Cargo.toml    version, and models = { ..., version = "X.Y.Z", ... }
    models/Cargo.toml    version
   

   engine/tests/workspace.rs fails if a path dependency has no version at all. It cannot tell you the version is stale, and cargo cannot either until the upload has half happened.

2. Check the page crates.io will show. Description, keywords, categories, readme and rust-version are frozen into each version, so a wrong one costs a new number. engine/tests/workspace.rs holds the limits crates.io enforces (five keywords, twenty characters each), and fails on an integration test that reads outside its crate without an exclude line, because that test cannot pass from an unpacked download. The floors differ by crate: nihilurk-particle-core and nihilurk-strings build on 1.85, nihilurk-models and nihilurk need 1.91 (let chains and a const TypeId::of; 1.90 fails). The two small crates stay on 1.85 because edition 2024 sets that floor and they need nothing newer. Raise one if you add code that needs a newer compiler, and build it on that compiler first (cargo +1.85.0 check -p nihilurk-strings).

3. Commit, then tag: git tag v<version>. The GitHub release and the AUR package both build from that tag. Pushing the tag starts the release workflow, so see publish-a-github-release.md first.

4. Run the three commands under Quick commands, in order. A dry run that says aborting upload due to dry run for all four crates is a pass.

After the upload

A stranger installs the English game with:

cargo install nihilurk

and another language by naming its feature:

cargo install nihilurk --no-default-features --features lang-pt

That installs one binary, nihilurk, in one language, into ~/.cargo/bin. A stranger whose shell lacks that directory on PATH gets “command not found”, so the README’s install steps carries the fix; keep it there when you edit the install lines.

The forwarder that picks a language from $LANG (nihilurk-dispatch) is behind the dispatch feature and is not installed, because it execs a nihilurk-<lang> next to itself and an install from crates.io has none. release/package.sh and aur/PKGBUILD ask for it by name. --no-default-features is not optional for a second language: leaving it off builds English and the requested language together, and strings then fails to compile.

Check the install once, in a scratch directory, before you announce anything:

cargo install nihilurk --root /tmp/nih-check
/tmp/nih-check/bin/nihilurk -content | sed -n 1,8p

When it goes wrong

The upload stops after two crates Fix the cause and bump the versions of the crates not yet sent. Send each with cargo publish -p <crate>, in the order under “What goes out”. I have not tested a partial re-run of --workspace, so do not rely on it. A bad version is live cargo yank --version <v> <crate>. It stops new projects from picking the version up. It does not delete it, and it does not undo an install.

See also

publish-a-github-release.md                        the other half of a release
../explanation/adr-0002-two-names-per-crate.md     why the names differ from the directories
../reference/cli-and-env.md                        the flags of the installed binary
../../engine/tests/workspace.rs                    the tests that guard the manifests
../../aur/PKGBUILD                                 the other way a release gets installed

How to run the compatibility pipeline

Audience       Anyone who wants to know whether nihilurk still runs on
               a Pi, a 32-bit netbook, or a Graviton instance --
               and anyone who just made the binary bigger.
Prerequisites  Docker, and `cargo install cross`. QEMU hooks for
               the ARM rows; the script installs them for you.
               Everything else is optional and is skipped with a
               note where it is missing.
Result         One line per machine saying whether nihilurk runs
               there, the size of the binary for each, and which
               crate is responsible for those bytes.

One script:

./compat_test.sh

Read no further if it comes back green.

Quick commands

./compat_test.sh                  everything (~10 min cold)
./compat_test.sh --targets cloud  one machine
./compat_test.sh --no-build       reuse what is already built (needs --keep on the run before)
./compat_test.sh --keep           keep the images and target/cross afterwards
./compat_test.sh --no-headless    skip the no-terminal check (models has no crossterm)
./compat_test.sh --timeout 60     per-row seconds for the run check
./compat_test.sh --help

When a run ends, pass or fail, it frees the disk it took: the docker images it pulled (about 22 GB) and target/cross (about 6 GB). It removes only the images the pipeline names, never prunes, and keeps any image a container is using. So every run is a cold run; use --keep while you iterate.

The three phases on their own:

./compat/cross_build.sh           build for every machine + blame
./compat/run_check.sh             check each machine actually runs it

The report:

target/release/nihilurk-compat            the matrix, as text
target/release/nihilurk-compat report     same thing, explicit
target/release/nihilurk-compat gate       one line, and an exit code

Reports and logs land in target/compat/. The binaries themselves land in target/cross/<triple>/<triple>/release/.

Each run replaces target/compat/results.tsv rather than adding to it, --targets included. So a one-row run reports one row, and the machines it skipped show -. That is deliberate: a report mixing rows checked against two different builds of the game, with nothing on the page saying which was which, is worse than a report with gaps in it.

The machines

compat/matrix.tsv is the list, and it is the only list. One row per machine, tab-separated; adding a machine is adding a line.

cloud      x86_64 musl     native   t3.micro, and the control
graviton   aarch64 musl    qemu     AWS Graviton, an M-series VM
pi-zero    armv7 musl      qemu     Raspberry Pi Zero 2 W
pi2        armv7 musl      qemu     Raspberry Pi 2 B
pi3        aarch64 musl    qemu     Raspberry Pi 3 B
pi4        aarch64 musl    qemu     Raspberry Pi 4 B
cm         aarch64 musl    qemu     Compute Module 4 (1GB Lite)
potato     i686 musl       native   32-bit netbook, ca. 2008

There is no CPU or memory cap on any row. nihilurk has no workload heavy enough to need a stress test – every feel-layer effect is bounded – so the matrix checks a narrower, cheaper claim instead: if it builds, the image has a shell, and the target is std (every linux row here is), nihilurk can run there. cloud and potato run on the host CPU directly; every other linux row runs under a directly-invoked qemu-user-static interpreter, fetched by the pipeline on its own – no binfmt_misc, no --privileged.

Every linux row’s image is checked for a shell before the binary is run – that is not optional, nihilurk cannot start without a real terminal under it – and a row that fails the check fails the pipeline rather than being silently skipped. See “why every linux row must have a shell” in ../explanation/cross-platform-testing.md.

1. Does nihilurk still run everywhere?

1. Run the pipeline:

   ./compat_test.sh
   

2. Read the table. One line per machine:

   machine   target                          exec        binary  verdict
   cloud     x86_64-unknown-linux-musl       native     3.5 MiB  runs
   graviton  aarch64-unknown-linux-musl      qemu       3.1 MiB  runs
   pi-zero   armv7-unknown-linux-musleabihf  qemu       3.2 MiB  runs
   potato    i686-unknown-linux-musl         native     3.2 MiB  runs
   

   The verdict column is the whole story:

   runs          the image has a shell and the binary started cleanly
   no shell      the image has no usable shell -- nihilurk cannot run
                 without one
   does not run  had a shell, but the binary did not start
   -             not attempted (excluded by --targets, or never built)
   

3. runs exits 0. no shell and does not run fail the pipeline, because they mean a machine that is supposed to run nihilurk cannot.

4. What is being checked

nihilurk -content: it prints the game’s content index and exits, without ever touching the terminal’s alternate screen. That is the whole check – if it prints something and exits 0, the row can run nihilurk. There is nothing to grade beyond that: nihilurk asks nothing of a machine that cross-compiling a full Rust toolchain (which cross_build.sh already proved this target can do) does not ask for first.

3. How big is it, and whose fault is that?

Phase 1 prints it per target, for the binary that actually ships – --release, fat LTO, one codegen unit, symbols stripped:

   target     triple                                 game      bytes
   cloud      x86_64-unknown-linux-musl           1.8 MiB    1934384
   potato     i686-unknown-linux-musl             1.8 MiB    1846016

The exact byte count is there because this is a table you diff against the last run, and the 32-bit rows come out about 4% smaller – which rounds to the same “1.8 MiB” and would otherwise be invisible.

Do not read too much into the last few kilobytes. A fat-LTO build is not reproducible to the byte, and the same source rebuilt can move by a page either way. A crate’s share moving, or a target gaining tens of kilobytes, is the signal.

Then it attributes those bytes per crate:

   crate                                   bytes    share
   models                                 477599    28.7%
   bevy_ecs                               343492    20.7%
   engine                                 210844    12.7%
   core                                   159366     9.6%
   std                                     98965     6.0%
   libc + compiler builtins                65823     4.0%
   total in symbols                      1662671

Those are symbol bytes, not file bytes – the difference is section headers, padding, relocations and the constant pool – so the total comes in under the size printed above it. Read the shares.

The full table per machine is in target/compat/blame-<machine>.txt. --no-blame skips the stage; --top 20 lists more crates.

4. Adding a machine

Add a line to compat/matrix.tsv. Seven tab-separated fields:

id        pi5
target    aarch64-unknown-linux-musl
class     linux            has an OS and a shell; nihilurk runs here
platform  linux/arm64      docker --platform for a native row; for a
                           qemu row, only picks the interpreter --
                           see run_check.sh
image     alpine:3.22      what the binary is executed in -- checked
                           for a shell before it is trusted, see
                           "the machines" above
exec      qemu             native | qemu | none
note      Raspberry Pi 5, 64-bit OS

Then, if it is a new triple, add its cross image to compat/Cross.toml:

[target.aarch64-unknown-linux-musl]
image = "ghcr.io/cross-rs/aarch64-unknown-linux-musl:0.2.5"

That is all. cross_build.sh, run_check.sh and the report all read the table.

Two rules the tests enforce, so you will hear about it:

• Every linux row must be a -musl triple. A -gnu binary is bound to the glibc it was linked against, which is the one thing the matrix exists to rule out.

  cargo test -p nihilurk-compat

Troubleshooting

A qemu row skipped saying it could not fetch its interpreter

`run_check.sh` pulls the static qemu-user interpreter it needs
from `tonistiigi/binfmt` the first time a qemu row runs, and
caches it in `target/compat/qemu/`. If that pull fails -- no
network, registry unreachable -- the row is skipped rather than
run against the wrong thing. Check docker can reach the registry:

    docker pull tonistiigi/binfmt

No `--privileged`, no binfmt_misc, and nothing written outside
this pipeline's own output directory.

docker is not answering

    sudo systemctl start docker
    sudo usermod -aG docker $USER      # then log out and back in

cross not found

    cargo install cross

The host's own musl triple will still build with plain cargo:

    cargo build --release --target x86_64-unknown-linux-musl -p nihilurk

no binary at target/cross/<triple>/<triple>/release/nihilurk

Phase 2 was run before phase 1, or for a row phase 1 skipped:

    ./compat/cross_build.sh --targets <machine>

The triple appears twice because each target gets its own cargo
target directory. That is deliberate and it fixes a real failure --
see "Why each target gets its own target directory" in the
explanation page.

<machine> is dynamically linked

The triple is not a `-musl` one. Fix the row; a dynamically linked
binary will not start on a machine with a different libc.

A build dies on weak version GLIBC_2.xx not found

A host artifact leaked into a cross container, or one cross image's
artifact into another's. Each target has its own target directory
precisely to stop that, so this means something was built with
`CARGO_TARGET_DIR` unset or pointing elsewhere:

    rm -rf target/cross && ./compat/cross_build.sh

A row says does not run and the log ends abruptly

The container exited non-zero or the timeout killed it. The report
points at `target/compat/run-<machine>.log`.

The report contradicts what the pipeline just printed live

The matrix loop and `nihilurk-compat report` disagree -- a row the loop
just logged `ok  runs: ...` for shows up as `does not run`, or is
missing from the table entirely. `matrix.tsv` is compiled into
`nihilurk-compat` with `include_str!`, so a `target/release/nihilurk-compat`
built before the last change to it, or to `compat/src/*.rs`, is
reading fresh results with stale code. Both scripts build
`nihilurk-compat` unconditionally rather than only when the binary is
missing, specifically because "it already exists" and "it matches
the current source" are different questions and only `cargo build`
can answer the second one. If you still see this on an older
checkout:

    cargo build --release -p nihilurk-compat

llvm-nm cannot read a <triple> binary

GNU `nm` often refuses a foreign ELF; llvm-nm reads all of them.

    rustup component add llvm-tools

The blame table says “no sized symbols”

It read the stripped binary. The `profiling` build is what carries
the symbols; check the build log for why it did not produce one.

See also

../explanation/cross-platform-testing.md   why it is built this way
../../compat/matrix.tsv                    the machine list itself

Every script takes --help, and each one’s help is the authority on its own flags:

./compat_test.sh --help
./compat/cross_build.sh --help
./compat/run_check.sh --help
target/release/nihilurk-compat --help

How to spawn a thing

Audience       Engine developer, or a content author who wants to
               look at the row they just wrote.
Prerequisites  Rust and a passing familiarity with bevy_ecs.
               `../reference/spawn-api.md` lists the signatures;
               this page is the recipes.
Result         A named monster, item, trap or the relic, in the
               world, on the tile you meant.

One function covers nearly every case:

spawn_named(&mut world, "dragon", Position { x: 10, y: 4 })

It searches every table by name and returns Option<Entity>. Four recipes follow – looking at something now, one in a test, one from game code mid-run, and loot the way the dungeon rolls it. Take the one you are standing in.

Recipe 1: look at it right now

No code. NIHILURK_SPAWN drops names on free tiles around the player on every floor it builds:

cargo run -p nihilurk -- -content              # 1. what are the names?
cargo run -p nihilurk -- -content | grep -i wand
NIHILURK_SPAWN="dragon" cargo run -p nihilurk      # 2. put one in front of me
NIHILURK_SPAWN="bow,arrow,arrow,dart trap" cargo run -p nihilurk

Gear and ammunition take dressing: cursed (or megacursed), +N/-N and xN.

To press keys in the game it starts and read the screen back as text, with no terminal of your own, use play-through-a-pty.md.

NIHILURK_SPAWN="cursed -2 long sword,+3 ring mail,arrow x13" cargo run -p nihilurk

Names are comma-separated and trimmed; a name the tables do not know is skipped silently, so check it against -content rather than trusting an empty floor. Full rules: ../reference/cli-and-env.md.

Recipe 2: one specific thing in a test

1. Build a world. A bare one is enough to spawn into and assert about, and needs no resources at all:

   use bevy_ecs::prelude::*;
   use models::*;
   
   let mut w = World::new();
   let dragon = spawn_named(&mut w, "dragon", Position { x: 5, y: 5 }).unwrap();
   

   That is what models/tests/it/content.rs does for all hundred-odd rows. Use it whenever the thing itself is the subject – its components, its name, its glyph.

2. Or build a real floor, when the thing has to be somewhere – a monster that walks, an item auto-explore has to find, anything that reads Map:

   fn test_world(seed: u64) -> World {
       let mut w = World::new();
       w.insert_resource(GameRng(ChaCha12Rng::seed_from_u64(seed)));
       w.insert_resource(RngSeed(seed));
       w.init_resource::<GameLog>();
       w.insert_resource(PlayerName { what: "TESTER".into() });
       initialize_world(&mut w);   // map, player, starting kit, floor 1
       w
   }
   

   Copy it from models/tests/it/identify.rs, and add the queue your system reads (w.init_resource::<UseQueue>(), ThrowQueue, AttackQueue) if you are about to run one. The player is w.query_filtered::<Entity, With<Player>>().single(&w).

3. Put it where the test needs it. Three places a thing can be, and the second and third are alternatives:

   // on the floor -- it already is, from the Position you passed
   let pos = Position { x: 5, y: 5 };
   let sword = spawn_named(&mut w, "long sword", pos).unwrap();
   
   // in the pack -- strips Position, merges ammo, respects PACK_CAPACITY
   stow(&mut w, player, sword);
   
   // or worn/wielded -- no log line, no turn, no pack slot needed
   assert!(equip_silently(&mut w, player, sword));
   

   initialize_world hands the player a starting kit – ring mail, a mace, a short bow – and that kit is already on. Slot::Body and Slot::Hand hold one thing each, so equip_silently returns false for a second suit of armour until you take the first one off:

   if let Some(worn) = equipped_in(&w, player, Slot::Body) {
       force_unequip(&mut w, worn);
   }
   

   If the kit competes with what you are testing in the pack rather than on the body, empty the pack first – empty_pack in models/tests/it/identify.rs is the pattern.

4. Name it in a literal and let it panic. MonsterDef::named("dragon") and TrapDef::of(TrapEffect::Bear) panic on a miss, which is what you want from a typo in a test. Save lookup for names that came from outside the source.

Recipe 3: one from game code, mid-run

The scroll of create monster (models/src/items/scrolls.rs, create_monster) is the worked example. Four steps, in this order:

1. Find a free tile. Never assume one:

   let spot = free_adjacent_tile(world, origin)      // next to someone
       .or_else(|| random_open_tile(world));         // anywhere on the floor
   let Some((x, y)) = spot else {
       world.resource_mut::<GameLog>().add("...nothing happens.");
       return;
   };
   

   Both read the Map and both can fail. The refusal branch is not optional – a sealed-in player is a legal floor.

   These two are inside models only (crate::helpers and crate::traps, neither re-exported). From a test or from engine/, either pick the tile yourself against Map::blocks or call spawn_list, which does the searching for you.

2. Roll from GameRng, in a scoped block. The live run rolls from GameRng and never from layout_rng/content_rng – those two belong to floor generation, and borrowing one while spawning will not compile anyway:

   let idx = {
       let mut rng = world.resource_mut::<GameRng>();
       rng.0.gen_range(0..BESTIARY.len())
   };   // <- borrow ends here, before the spawn
   

3. Spawn through the right door:

   let pos = Position { x, y };
   spawn_monster(world, &BESTIARY[idx], pos);        // monsters
   spawn_named(world, "long sword", pos);            // items, by name
   world.spawn(TrapBundle::from_def(                 // a trap is a bundle,
       TrapDef::of(TrapEffect::Bear),                //   not an entity
       TrapReveal::Sight,
       pos,
   ));
   

   spawn_monster is the only way a monster should enter the world: it attaches the row’s granted effects and its Invisible marker. TrapBundle::random is the rolled version, but it wants a ChaCha12Rng of its own – floor generation hands it a content_rng. From a live system, name the trap you mean.

4. Say so in the log. Use item_label(world, entity) (helpers, models-internal again) for the name the player is allowed to know – an unidentified suit of armour is “leather armor”, not “+2 leather armor” – and article_for(&name) for the “a”/“an” in front of it.

Recipe 4: loot the way the dungeon rolls it

spawn_named gives you the row. roll_item gives you a drop:

let item = roll_item(world, &mut rng, depth, pos);

Weighted category, weighted row within it, then spawn_as_loot – so it arrives enchanted, charged and bundled, gated to the depth you passed. This is the only place the dungeon decides what loot exists; call it rather than re-rolling quality yourself.

The rng is the caller’s, not GameRng: floor generation passes its own content_rng(seed, depth, changes), which is what keeps a floor’s contents keyed to the seed and the staircase count rather than to the fighting. A test can pass any ChaCha12Rng::seed_from_u64.

To roll one piece of quality onto something you spawned by name:

let sword = spawn_named(world, "long sword", pos).unwrap();
enchant_equipment(world, &mut rng, sword);    // +1..+3, or cursed

What comes out is the bare row

spawn_named and the spawn_* wrappers build the thing exactly as its table row describes it – no dice are rolled. What that means per kind:

That is deliberate: a test that spawns a thing needs it to be the same thing every time. When you want the randomised version, use Recipe 4.

When it does not work

spawn_named returned None. The lookup is a case-sensitive exact match on the row’s name – "Dragon" and "long Sword" find nothing. Check cargo run -p nihilurk -- -content.

It spawned but nothing is drawn. Either it has no Position (being in a Backpack means exactly that: stow removes it, and the renderer draws the pack separately), or the tile is not currently visible – floor items are only drawn on revealed tiles, and a monster gets Hidden until the player’s viewshed reaches it.

It landed in a wall. Nothing in the spawn API validates the tile you hand it; Position is whatever you said. Use free_adjacent_tile, random_open_tile, or spawn_list, which searches outward in rings and skips anything Map::blocks.

equip_silently returned false. Either the item has no Equipped component (it is not gear), or the slot is full – and on a world built by initialize_world the body and hand slots start full. force_unequip the incumbent first (Recipe 2, step 3).

The borrow checker refuses the RNG line. A resource_mut::<GameRng>() guard is still alive at the spawn. Roll inside a block and let it drop (Recipe 3, step 2).

Two things landed on the same tile. Only spawn_list and spawn_requested track occupancy, via the &mut HashSet<(u16, u16)> you pass in. Spawning in a loop yourself means keeping that set yourself.

A seeded test started failing after you added content. Floor layout is a pure function of (seed, depth) and cannot move – but the contents are drawn from a weighted table, so adding a row changes which rows a given roll lands on. Assert on what you spawned by name, not on what a seed happened to produce. models/tests/it/determinism.rs holds the line that matters.

Check yourself

cargo test --test it content::        # every name still spawns and keeps its name
cargo test --test it determinism::    # seeds still mean what they meant
cargo run -p nihilurk -- -content  # what the game knows, live from the tables

Appendix: quick check

1. Look at it now: NIHILURK_SPAWN="<name>" cargo run -p nihilurk, with names from -content.
2. In a test: spawn_named(&mut w, "<name>", Position { x, y }).unwrap() on a bare World.
3. Needs a floor: build the world with initialize_world, as models/tests/it/identify.rs does.
4. In the pack: stow(&mut w, player, item). Worn: force_unequip the incumbent, then equip_silently.
5. From game code: find a free tile, roll from GameRng in a scoped block, then spawn through spawn_monster, spawn_named or TrapBundle::from_def.
6. Many at once: spawn_list, which tracks occupancy.
7. Loot as the dungeon rolls it: roll_item(world, &mut rng, depth, pos).
8. Run cargo test --test it content:: and cargo test --test it determinism::.

See also

../reference/spawn-api.md every signature on this page ../reference/cli-and-env.md NIHILURK_SPAWN and -content in full ../reference/content-tables.md the tables these functions read add-a-monster.md adding the row you want to spawn add-an-item.md the same, for items work-with-the-ecs.md spawning from inside a system play-through-a-pty.md look at it in the real game, from a script

How to tune rarity and depth

Audience       Content author balancing a floor.
Prerequisites  You have added something and now want it to show up
               less, or later, or at all.
Result         You know which of the four dials to turn, and which
               ones you should leave alone.

There are four places rarity is decided, and they answer different questions. Turning the wrong one is the usual mistake.

1. How many things per floor?        engine knob, map/population.rs
2. Which category of item?           DROPS, models/src/spawn.rs
3. Which row within a category?      the row's own weight
4. Is it allowed here at all?        the row's min_depth

How weights work

An entry’s chance is its weight over the sum of the weights it competes against, and it competes only inside one draw: a monster’s weight against other monsters, a DROPS weight against other categories.

The default weight is the baseline (constants::monsters::DEFAULT_SPAWN_WEIGHT for the bestiary). A row at half of it is half as common as its neighbours; one at double it is twice. Nothing has to total anything, so you can add a row without editing another number. Weights are whole numbers, so 1 is the floor: to make a row rarer than 1 you raise the baseline and every explicit weight with it (spirits did exactly this).

Dial 1: how many things per floor

This is not content. It is floor generation, in populate_level in models/src/map/population.rs, and it is the same for every row.

Everything scales off tier – map::difficulty_tier(depth), which steps at the depths in constants::progression::DIFFICULTY_TIER_LAST_DEPTH: tier 0 on the shallowest floors, and the deepest floor a tier of its own. The damage traps scale too, but on their own coarser bands (constants::traps::TRAP_DAMAGE_TIER_LAST_DEPTH). Every name below is in constants::population.

guaranteed    placed before any budget is spent, and never out of
              one: a blue coin on the odd floors and a red one on
              the even. On the last floor of each tier -- the
              depths in DIFFICULTY_TIER_LAST_DEPTH -- one draw from
              `catalog::PROGRESSION_ITEMS` as well.

monsters      MONSTER_SLOTS_BASE + tier slots. The first always
              fills; each later one fills with probability
              MONSTER_FILL_CHANCE_BASE + MONSTER_FILL_CHANCE_PER_TIER
              * tier, capped at MONSTER_FILL_CHANCE_CAP.

lurkers       from floor CORRIDOR_LURKER_MIN_DEPTH, each corridor
              centre has a CORRIDOR_LURKER_CHANCE chance of hiding
              one more.

items         ITEM_SLOTS_BASE + tier attempts. Every attempt that
              finds a free tile drops an item (no fill roll).

hidden item   HIDDEN_ITEM_CHANCE of floors hide one more in plain
              sight -- no glyph until you walk onto it.

traps         TRAP_SLOTS_BASE + tier slots, each filling with
              probability TRAP_FILL_CHANCE_BASE +
              TRAP_FILL_CHANCE_PER_TIER * tier, capped at
              TRAP_FILL_CHANCE_CAP.

Change these when the dungeon feels too empty or too crowded. Do not change them to make one creature rarer – that is dial 3.

Turning any of these cannot move a wall. A floor’s layout is built from layout_rng(seed, depth) and its contents from content_rng(seed, depth, changes) – neither is the shared run stream, so nothing a player does mid-fight can shift a floor. (The contents do re-roll each visit, off the staircase count.) What your weights change is what a given seed produces from the table you edited, which is the whole point of editing it. See ../explanation/data-driven-content.md.

Dial 2: which category of item

models/src/spawn.rs     ->  DROPS

category!("scroll",   <weight>,    1,     SCROLLS),
category!("potion",   <weight>,    1,     POTIONS),
...
                          |        |
                       weight   min_depth

Those weights are Rogue’s own drop odds in tenths of a percent. ../reference/content-tables.md carries the current table, and a test holds it in step with DROPS. They do not have to total anything round, which is only convenient to read.

To double how often rings turn up, double the ring row’s weight. Every other share drops slightly to pay for it, automatically.

To keep a category out of the shallow dungeon, raise its min_depth. A category that cannot appear is simply not in the draw, and the remaining categories divide its share between them in proportion.

The rune row is the example. Its min_depth is above 1, so the shallowest floors draw from every other category and the rune joins the draw below that. The weights table in ../reference/content-tables.md shows the share with the rune in the draw, and says what the shallower floors total. models/tests/it/loot.rs scales a category’s expected share by the floors it is on, so a new category that starts deeper needs no special case there.

Dial 3: which row within a category

Monsters carry the dial on the row:

MonsterDef::row("dragon", ...).weight(3),

Traps carry it as a field:

TrapDef { effect: ..., weight: 3, min_depth: 9, ... },

Items do not have per-row rarity today, on purpose: within a category nihilurk picks evenly, and the design likes it that way. The hook exists if you want it – ItemDef::weight() and ItemDef::min_depth() are trait methods with defaults of 10 and 1, and the picker already honours them. To give one category per-row rarity, add a weight: u32 field to its Def struct and return it:

impl ItemDef for ArmorDef {
    fn name(&self) -> &'static str { self.name }
    fn weight(&self) -> u32 { self.weight }     // <- added
    ...
}

Then every ArmorDef row must carry a weight, which is the cost. Decide whether the category deserves it before you pay it.

Dial 4: is it allowed here at all

min_depth is the shallowest floor a thing may appear on. It is a hard gate, not a weight: below it the row is not in the draw.

Monsters use it as the last column of the row:

//              name         glyph  colour     move   hp pow pb  ar ab  dep
MonsterDef::row("dragon",    'D',   Color::Red, Chase, 8, 12, 2, 10, 2, 10),

The bestiary uses 1, 5 and 10 – the shallow stat band from the start, the middle band from floor 5, the nastiest letters from floor 10. Nothing stops you using 2 or 11.

The dungeon is FINAL_DEPTH floors deep, so a min_depth above that means “never” – on the way in. The climb out is the exception: once the Element of Yoord is in the pack, floor population switches from pick to MonsterDef::pick_any, which drops the gate entirely, so a min_depth of 10 (or 99) is no protection on the ascent.

Every floor still draws from everything it has unlocked. A bat does not stop appearing on floor 9; it competes with the dragon. That is what keeps deep floors feeling like a dungeon rather than a boss rush. If you want something to stop appearing, min_depth is the wrong dial – there isn’t one, and adding one is an engine change.

Verify what you changed

The table tests cover the gating but not your intent, so measure it:

cargo test --test it content::

every_loot_category_can_be_drawn_and_has_rows_to_give asks the table, not a sampler: every category keeps a nonzero weight and has rows at its debut floor and at the deepest. If you weight a category down to nothing, that test tells you.

For a feel, the quickest instrument is a throwaway loop over roll_item or MonsterDef::pick counting names – see models/tests/it/content.rs for the shape.

Appendix: quick check

1. Decide which question you are asking: how many per floor, which category, which row, or allowed here at all.
2. Per floor: edit populate_level in models/src/map/population.rs; this moves every row at once.
3. Category: change its weight in DROPS (models/src/spawn.rs).
4. Row: .weight(n) on a monster, or weight on a trap; twenty is the baseline (monsters and traps; spirits sit at 1, the floor) and items have no per-row weight.
5. Gate: raise min_depth; it is a hard gate, and nothing makes a row stop appearing deeper.
6. Run cargo test --test it content::.
7. Count what a draw gives you with a throwaway loop over roll_item or MonsterDef::pick.
8. Fix the docs: if you changed a DROPS weight, update the weights table in ../reference/content-tables.md and the listing in this page.

See also

../reference/spawn-api.md pick_weighted, roll_item, DROPS ../reference/content-tables.md where weight and min_depth live add-an-item-category.md adding a row to DROPS itself

How to update the docs after you add something

Audience       Anyone who just changed the game and is about to
               open a pull request.
Prerequisites  None.
Result         You know which pages your change made false, and
               you fix them before review.

Most additions need no docs edit. The tables are short, cargo run -p nihilurk -- -content prints them live, and no page lists a monster, a weapon or a trap by name. This page lists the exceptions: the places where a page keeps a hand-written list of something. Find your change below, touch those pages, run the check.

Paths are relative to this page, except MANUAL.md, doc/, strings/ and engine/, which start at the repo root.

Look it up

A secret (the T key, the -pride flags) stays out of MANUAL.md and ../reference/cli-and-env.md. See ../explanation/documentation-style.md.

When the change is a mechanic

If your change alters what a player can do or has to know (polymorph lends powers, a staff changes what spells cost, a trap now fires for monsters), the rule belongs in MANUAL.md in the player’s voice, and in the reference page for the system it touches. ../../gdd.md changes only when the design does, not when the code does.

If your change settles or reverses a design question, write an ADR in the shape of ../explanation/adr-0001-tables-not-raws.md and add it to the list in ../README.md. The history goes there, and nowhere else.

Player-facing text

Every sentence the player reads is a function in strings/src/en.rs. es.rs, pt.rs and ht.rs re-export English until someone translates the function, so a new English function needs no other file. If a language stops building, run lua .githooks/stub_missing_translations.lua. English you write starts unreviewed: the pre-commit hook tags each new en.rs function // TODO: placeholder English; needs a human's pass., and whoever has read it and stands behind it deletes the tag, reworded or not.

The three habits

1. Name the constant, not its value. A number copied into prose goes stale on the first rebalance. The same goes for counts: “nine tables” and “all six traps” were each wrong within a release. Say “every table”.
2. Search for what you renamed. docs_style.sh checks paths and links, not identifiers. After a rename or a removed mechanic, run grep -rn 'old_name' docs MANUAL.md doc.
3. Cite the test. If a claim can be a test, make it one and name it in the page.

Check

./docs_style.sh                    # house style, links, paths
cargo test --test it content::          # the claims the how-tos make about the tables
grep -rn 'old_name' docs MANUAL.md doc   # what your rename left behind

With git config core.hooksPath .githooks on, the pre-commit hook runs ../../.githooks/docs_nudge.lua and names the pages from the table above that your staged change leaves out. It reminds and never refuses. A row you add to the table above needs a rule in ../../.githooks/docs_nudge_rules.lua, or a stated reason no diff can see it; ../../.githooks/docs_nudge_test.lua refuses the commit while the two disagree.

See also

add-an-item.md the recipes this page follows up ../explanation/documentation-style.md the shape and voice of a page ../README.md the index, and the rule that keeps docs true ../reference/constants.md the modules table you add a row to

Working with the ECS

Audience       Engine developers. You are adding a mechanic, not a
               row in a table — you need to reach an entity, change
               it, and get the borrow checker to let you.
Prerequisites  You write Rust. You know what a component and a
               system are. You have read
               `../reference/components.md` at least once.

The snippets are written from inside models, so they say crate::conditions::.... From engine or a test, the same name is models::... (see ../reference/spawn-api.md for what the crate root exports).

Recipes: copy the shape, change the nouns. Why the code is arranged this way is ../explanation/ecs-in-nihilurk.md.

Sixteen of nihilurk’s seventeen schedule steps take &mut World and nothing else. That one fact decides everything below: you are not writing Query<&mut Fighter> and letting bevy sort out the aliasing, you are holding the whole world and borrowing bits of it by hand. The borrow checker is stricter here than it is in a Query-based codebase, and the five patterns in the first section are how every mechanic in the tree gets past it.

Contents

The five borrow patterns              start here
Recipe: add a component
Recipe: add a kind of entity
Recipe: put something in the world
Recipe: deal damage
Recipe: apply a condition
Recipe: read a stat gear contributes to
Recipe: queue an intent from input
Recipe: add a system to the turn
Recipe: decorate without depending on the renderer
Recipe: write a system that really is a Query
Checking your change

The five borrow patterns

1. Copy out, then mutate

world.get::<C>(e) hands back Option<&C>, and that & borrows the whole world. While you hold it you cannot log, roll a die, or touch another component. So take a copy and drop it on the same line:

let Some(pos) = world.get::<Position>(victim).copied() else {
    return;
};
// `world` is free again from here.
crate::shake::kick_shake(world, ShakeKind::Kill);

.copied() for a Copy component, .cloned() or .map(|n| n.what.clone()) for a String, .map(|f| f.hp) when you only want one field. The let ... else is the house guard clause — see ../explanation/code-calisthenics.md.

The same rule in its most common disguise: name things before you log them. This does not compile if you inline item_label, because the log is a resource and the name is a borrow of the world:

let name = item_label(world, entity);                   // borrow ends here
if let Some(mut mob) = world.get_mut::<Mob>(entity) {
    mob.movement_type = MovementType::Confused;
}
world.resource_mut::<GameLog>()
    .add(format!("The {name} {mob_verb}."));

(conditions::stagger.) A Mut<C> from get_mut behaves the same way — its borrow ends at its last use, not at the end of the block, so a write followed by a resource_mut is fine as long as nothing touches the Mut afterwards.

2. Collect, then iterate

world.query::<…>() needs &mut World even to read, and the QueryState it returns borrows the world for as long as you iterate it. Any loop body that mutates must therefore run after the iteration ends. Collect the entity ids first:

let doomed: Vec<Entity> = {
    let mut q = world.query::<(Entity, &Fighter)>();
    q.iter(world)
        .filter(|(_, f)| f.hp <= 0)
        .map(|(e, _)| e)
        .collect()
};

for entity in doomed {
    finish_indirect_kill(world, entity, None);
}

(combat::reaper_system.) Collect ids, not references — the whole point is to stop borrowing. And re-check anything you collected before you use it: by the time the loop reaches the third entity, the first two may have despawned it, teleported it or turned it into something else. traps::detonate_trap does exactly that:

if world.get::<Position>(victim).is_none() {
    continue;   // an earlier victim's trapdoor took this one with it
}

3. mem::take a queue before you drain it

A system that drains a queue resource cannot hold that resource while it resolves, because resolving touches everything. Swap the queue’s contents out for an empty Vec in one move:

pub fn combat_system(world: &mut World) {
    let attacks = std::mem::take(&mut world.resource_mut::<AttackQueue>().attacks);
    for attack in attacks {
        resolve_attack(world, attack.attacker, attack.target);
    }
}

All five queues (AttackQueue, UseQueue, ThrowQueue, SpellQueue, PlayerActionQueue) are drained exactly like this. It also gives you the right semantics for free: an attack queued while the queue is draining lands next turn, not in the middle of this one.

4. entity_mut for a burst of writes

world.entity_mut(e) returns an EntityWorldMut that holds the world until you drop it. Inside it, insert/remove/get/contains are cheap and archetype-aware — so batch structural changes there rather than calling world.entity_mut(e) once per component:

let mut e = world.entity_mut(item);
if e.contains::<PowerDie>() && e.contains::<PowerBonus>() {
    e.insert(PowerBonus(0));
}
e.remove::<Curse>();

(items::wands::cancel_player.) What you cannot do inside that block is call anything taking &mut World — including world.resource_mut(). Gather the facts, close the block, then log.

5. &World can read but not query

A helper that only reads should take &World, so its callers can hold one alongside other borrows. The cost is that world.query() is off the table; you get world.get::<C>(e) and world.iter_entities() and nothing else.

pub fn equipped(world: &World, wearer: Entity) -> impl Iterator<Item = EntityRef<'_>> {
    world
        .iter_entities()
        .filter(move |e| e.get::<Equipped>().is_some_and(|eq| eq.by == Some(wearer)))
}

(equipment::equipped.) Prefer returning an iterator of EntityRef over a Vec<Entity>: the caller gets to read components straight off it with no second lookup and no allocation. Keep a Vec-returning twin (equipped_items) only for callers that go on to mutate.

Recipe: add a component

Before you write one, check you need one. Three things that look like new components are not:

• A property some system will ask about — fire immunity, sees invisible, hits harder. That is an effect: a marker in effects.rs plus a row in the EFFECTS registry, so a table can name it with Grant::of::<C>() and a wand of cancellation can strip it. Follow add-an-effect.md instead.
• A number gear contributes — a weapon’s die, a ring’s plus. That is a Modifier in effects.rs; equipped_total already folds it.
• Which one of a kind a thing is — a fourteenth wand, a sixteenth potion. That is a variant on an existing type key and a row in catalog.rs. See add-an-item.md.

What is left is a genuinely new fact about an entity, and it goes in models/src/components.rs — nouns only, no behaviour:

/// Two sentences: what carrying this means, and who owns it. Name the
/// system that reads it, and — if it is transient — say so here,
/// because that doc comment is the only record of why it is missing
/// from the save.
#[derive(Component)]
pub struct Doomed {
    pub turns: u32,
}

Then, in order:

1. Derive no more than it needs. Component always. Clone, Copy when it is small and gets read out by value. Serialize, Deserialize only if the save stores the type itself rather than its fields — most do not.
2. Decide if it is saved, and write the answer in the doc comment. If yes: a field appended to saveload::EntitySave, plus the save line, the load line and a new SAVE_VERSION. If no, say why — rebuilt every frame (Viewshed::visible_tiles), reset on load (Speed::energy), or re-attached from a catalog row by id (ThrownDamage). A component that is silently neither is a bug waiting for somebody’s save file.
3. Give it a row in ../reference/components.md, in the section it belongs to, with its “Saved?” column filled in.

Rules that are not negotiable:

• No fn that touches the World. If the component needs a verb, the verb lives in the module that owns the domain — conditions.rs for an affliction, equipment.rs for gear. Methods about the type (SpeedKind::faster, Name::article) are fine.
• A saved enum is written by variant position. Append variants; never reorder one, or a saved trapdoor comes back as something else.
• Small. A component with eight fields is usually two components.

Attaching and detaching one

world.entity_mut(e).insert(Doomed { turns: 3 });
world.entity_mut(e).remove::<Doomed>();

Both are structural — they move the entity between archetypes — so they invalidate any query you are in the middle of. That is what pattern 2 (collect, then iterate) is for. From a Query system, defer them through Commands instead:

commands.entity(entity).insert(Hidden);

Recipe: add a kind of entity

“Kind” means a new shape — a thing that is neither a monster, an item, nor a trap. Adding a new monster or a new potion is a table row and nothing else; see add-a-monster.md and add-an-item.md.

A new kind is three pieces, and the third is what keeps it from spreading:

1. A Def row type, with the table beside it. Not in components.rs — next to the content it describes, so the type, the table and the one place it is built are all in one file:

pub struct TrapDef {
    pub effect: TrapEffect,
    pub name: &'static str,
    pub glyph: char,
    /* … the dials its mechanic needs, on the row */
}

pub const TRAPS: &[TrapDef] = &[ /* one line per trap */ ];

2. A Bundle, so the entity is described exactly once. Every spawn site goes through it — level population, a scroll that conjures one, a save being reloaded — and none of them assembles the components by hand:

#[derive(Bundle)]
pub struct TrapBundle {
    pub name: Name,
    pub glyph: Renderable,
    pub position: Position,
    pub trap: Trap,
    pub hidden: Hidden,
}

impl TrapBundle {
    pub fn from_def(def: &TrapDef, reveal: TrapReveal, position: Position) -> Self { … }
}

let e = world.spawn(TrapBundle::from_def(def, reveal, pos)).id();

Components that only some of the kind carry stay off the bundle and go on afterwards, the way spawn_monster adds Invisible for the phantom:

let e = world.spawn(MonsterBundle::from_def(def, pos)).id();
grant_all(world, e, def.grants);
if def.invisible {
    world.entity_mut(e).insert(Invisible);
}

3. A way to reach it by name. Add the table to spawn::spawn_named and to spawn::content_names, and the new kind immediately answers to NIHILURK_SPAWN, to -content, to every test, and to models/tests/it/content.rs’s “every name spawns and keeps its name” check. If it is loot rather than furniture, implement ItemDef and give it a DROPS row instead — add-an-item-category.md is the full recipe.

Then the bookkeeping, in order:

• Saving. Decide what the save stores and what it reads back off the row. Store the row’s name, never its contents (see restore_from_catalog), and add the entity’s own mutable state — a trap’s revealed latch, a wand’s charges.
• Despawning between floors. map::levels::transition_level clears everything with a Position that is not the player and not in a backpack. If your kind should survive a staircase, it needs a reason and an exception; if it should not, you have nothing to do.
• Drawing. A Renderable gets it on screen, but when it draws is a layer in engine/src/view.rs’s render, and the order matters — a later layer covers an earlier one. See ../reference/rendering.md.
• Documenting. A row in ../reference/content-tables.md for the table and one in ../reference/components.md for anything new it carries.

The test that tells you it landed: cargo run -p nihilurk -- -content lists it, and NIHILURK_SPAWN="<name>" puts one in front of you.

Recipe: deal damage

%%{init: {'theme':'base','themeVariables':{
  'primaryColor':'#20242b','primaryTextColor':'#d7dae0',
  'primaryBorderColor':'#5c6370','lineColor':'#8a8f98',
  'fontFamily':'ui-monospace, SFMono-Regular, Menlo, monospace',
  'fontSize':'13px'}}}%%
flowchart LR
  SW(["somebody swung"]):::hero --> RA["combat::resolve_attack"]:::peril
  RA --> R1["opposed rolls<br/>+ gear"] --> R2["chip floor,<br/>melee cap"]
  R2 --> R3["ABILITIES<br/><i>Moment::OnHit rows</i>"]:::magic --> R4["blood, promise,<br/>low-HP warning"]:::peril
  R4 --> R5["log, shake,<br/>score, despawn"]

  NO(["a trap, a bolt,<br/>a blast"]):::magic --> AD["helpers::apply_damage"]:::peril
  AD --> A1["HP off"] --> A2["blood, promise,<br/>low-HP warning"]:::peril
  A2 --> RP["reaper_system<br/><i>at the tail of the turn</i>"]:::peril
  A2 -. "or, if you know the blast centre" .-> FI["finish_indirect_kill"]:::peril
  classDef hero fill:#3a3418,stroke:#d7ba4a,color:#e8dfa8
  classDef peril fill:#3a1f1f,stroke:#c05050,color:#f0c8c8
  classDef magic fill:#2f2038,stroke:#a86fc0,color:#e6cdf0
  classDef cold  fill:#17323a,stroke:#4aa3c0,color:#bfe4f0

There are exactly two ways, and which one you want depends on whether somebody swung.

Something hit something else — use the opposed-roll resolver:

crate::combat::resolve_attack(world, attacker, target);

It rolls both sides, folds in every equipped modifier, fires every Moment::OnHit row in ABILITIES, spills blood, logs the line, kicks the shake, pays the score and despawns the corpse. You do not do any of that yourself. Monsters reach it by pushing onto the AttackQueue (below); the player’s own swing calls it inline from move_player.

Something took damage with no swinger — a trap, a bolt, a blast:

crate::helpers::apply_damage(world, victim, amount);

That subtracts the HP, spills blood, breaks any promise the victim was holding and fires the low-HP warning. It deliberately does not kill: anything left on hp <= 0 is finished by reaper_system at the tail of the turn. If you know where the damage came from and want the corpse flung away from it, finish the casualty yourself instead:

if world.get::<Fighter>(victim).is_some_and(|f| f.hp <= 0) {
    crate::combat::finish_indirect_kill(world, victim, Some(center));
}

(items::wands::elemental_blast.)

Three rules that are easy to get wrong:

• Armour. Melee, missile, magic: resolve_attack rolls the defender’s armour die and plus; a throw or a shot subtracts only the armour plus (helpers::total_armor_plus); a spell or wand subtracts nothing. An arrow or dart trap is a missile; every other damage source is magic. No exceptions. See ../explanation/combat-and-balance.md.
• Elements. If the damage has a flavour, go through items::wands’s damage_with_element, which checks the target’s immunity (Element::immunity()) and logs the shrug. Never match on a species.
• took_damage. Melee applies its own HP change and so has to call helpers::took_damage by hand. If you ever add a third damage path, call it too — it is the one place “what happens because a creature was hurt” lives.

Recipe: apply a condition

Never insert a condition component directly. Call the verb in crate::conditions, which already knows the player takes an affliction differently from a monster:

use crate::conditions::{blind, confuse, paralyse, hasten, snare, shift_entity_speed};

// The player gets `Confused`; a monster gets `MovementType::Confused`.
confuse(
    world,
    victim,
    "The flash leaves you reeling — you are dazzled!",  // the player reads this
    "is dazzled",                                       // "The rat ___."
);

// Pinned for a count of turns. Deliberately silent — the sentence
// belongs to whatever pinned them.
snare(world, victim, Grant::of::<Asleep>(), SLEEP_TURNS);

Every verb returns bool: whether it actually took hold. That answer is load-bearing — a potion thrown at a monster only identifies itself when something plainly happened (items::potions::detonate_potion), so pass it up rather than discarding it.

To add a new condition, in order:

1. A marker component in components.rs, doc-commented with what it costs the player and what it does to a monster instead.
2. A verb in conditions.rs that does the player/monster split once.
3. An arm in conditions::cure_one_condition (a rosé coin and a ring of regeneration both lift “the worst thing wrong with you”, worst first) and in conditions::afflicted.
4. An arm in conditions::clear_player_conditions, unless it is meant to survive a staircase — Plated and Forged are the only two that do, and the staircase settles them instead.
5. A field appended to saveload::EntitySave, plus the save and load lines and a new SAVE_VERSION. A condition a save forgets is a condition that silently lifts on reload.
6. A badge in the HUD’s condition list (engine/src/view.rs).

A condition that lives on a monster usually needs none of this: prefer a MovementType or a Speed shift, which the AI already reads.

Recipe: read a stat gear contributes to

Never walk the pack. One call folds the entity’s own component together with every equipped source of the same modifier:

use crate::effects::{equipped_total, PowerDie, PowerBonus, ArmorDie, ArmorBonus, ThrowBonus};

let power = world.get::<Fighter>(e).map_or(1, |f| f.power)
    + equipped_total::<PowerDie>(world, e);

It does not know what kind of item supplied the number, and neither should you: that is the whole reason a ring of protection needs no code. Combat, the throw roll, the trap damage rule and the HUD all fold through it, which is why the HUD can never drift from the dice.

Want more than one of them? Take the whole loadout in one pass. Each equipped_total walks the wearer’s gear again, so five fields is five walks over the same handful of items:

let worn = crate::effects::loadout(world, entity);
let power = world.get::<Fighter>(e).map_or(1, |f| f.power) + worn.power_die;
let cap = worn.melee_cap;   // ceilings fold with `min`, not `+`

combat::fold_matchup takes one per side; the HUD takes one per frame. There is no cache underneath it — Equipped is still the only record of who wears what.

To ask whether an entity has a property, probe the marker, never the source:

if world.get::<SeesInvisible>(e).is_some() { … }

A ring, a potion and being born that way all leave the same component.

Recipe: put something in the world

Anything the content tables know, by name:

let dragon = crate::spawn_named(world, "dragon", pos);      // Option<Entity>

That is the door a test, a debug command and NIHILURK_SPAWN all use. It builds the thing exactly as its row describes it — no enchantment roll, no ammunition bundle. For the dungeon’s own randomised version, spawn::roll_item(world, rng, depth, pos).

Assembling an entity by hand is for one case only: you are adding a new kind of thing. Then it is a Bundle next to its table, never a pile of insert calls at a call site:

#[derive(Bundle)]
struct MonsterBundle { name: Name, mob: Mob, fighter: Fighter, /* … */ }

let e = world.spawn(MonsterBundle::from_def(def, pos)).id();

See spawn-a-thing.md for the full recipe and add-an-item-category.md for a new table.

Two things about removing:

• world.despawn(e) is final. Anything still holding that Entity — a Backpack, a queued WantsToThrow — now holds a dangling id, so take it out of the pack first (items::scrolls::lift_curses shows the shape).
• An item picked up does not despawn: it loses its Position. An item dropped gets one back. “Is it on the floor?” is With<Item>, With<Position>.

Recipe: queue an intent from input

Input handlers do not resolve anything. They push an intent and return whether a turn was spent; the matching system drains it next time the schedule runs.

world.resource_mut::<AttackQueue>().attacks.push(WantsToAttack {
    attacker: mob,
    target: target_entity,
});

WantsToUse carries slot_idx so a surviving item goes back to the exact pack row it came from, and target for anything aimed. A throw of a stacked item goes through models::draw_one first, which splits one arrow off and leaves the quiver where it was. WantsToCast is an active spell’s own intent — a wand’s twin, minus everything about an item because a spell isn’t one.

Recipe: add a system to the turn

Register it in models/src/schedule.rs with an explicit .after(). There is no implicit ordering and no SystemSet in nihilurk — the schedule is one flat list of seventeen steps, and every edge is deliberate:

schedule.add_systems((
    // …
    combat_system.after(equipment_effects_system),
    reaper_system.after(combat_system),
    // …
));

Then say why the edge exists in ../reference/input-and-turn-loop.md, which prints the whole order. Before you add a step, check whether it belongs at the tail: ability_system and score_turn_system are both there on purpose (a passive that moves you must land at the top of your next turn; a combo cannot be totalled until the dying is over).

Recipe: decorate without depending on the renderer

Gameplay code arms cosmetics and forgets. It must never require them — tests build a bare world with no effect layer at all. So reach for the cosmetic resources through get_resource_mut, not resource_mut:

if let Some(mut fx) = world.get_resource_mut::<Particles>() {
    fx.hit_spark(x, y);
}

The screen shake wraps that for you, so combat code never has to think about it:

crate::shake::kick_shake(world, ShakeKind::Heavy);   // no-op with no Shake resource

Two more rules:

• Cosmetic rolls come off FxRng, never GameRng. A colour drawn from the gameplay stream would mean every firework quietly reshuffled the dice for everything after it. score::random_bright and helpers::spill_blood both show the pattern.
• Gate anything that leaks information on sight. A shake for a blast in a room the player has never entered tells them there is a room there. helpers::player_sees(world, x, y) is the shared check.

Recipe: write a system that really is a Query

One system in nihilurk is Query-based (visibility_system), because it only reads and tags and never despawns. If yours is the same shape, write it that way — narrow filters are self-documenting and bevy checks the aliasing for you:

pub fn visibility_system(
    mut commands: Commands,
    mut viewshed_query: Query<
        (Entity, &mut Viewshed, &Position, Option<&SeesInvisible>, Option<&Blind>),
        With<Player>,
    >,
    mut log: ResMut<GameLog>,
    map: Res<Map>,
) { … }

Three things to copy from it:

• With<Player> is load-bearing, not decoration. Without it a future monster viewshed would reveal the map for the player.
• Ask for Option<&C> rather than a second query when a property is optional — SeesInvisible might come from a ring, a potion or birth, and this system never asks which.
• Structural changes go through Commands, which defers them past the end of the iteration. That is the whole reason this can be a Query system at all.

Fetch nothing you do not read. A tuple that grows past what the body actually uses is the first sign a system is doing two jobs.

Checking your change

cargo test --workspace          # everything
cargo clippy --all-targets      # correctness / suspicious / complexity / perf
cargo fmt --all

grep -rn '} else' models/src engine/src --include='*.rs'

Every hit of that last one should be a let … else or a two-armed expression ternary; anything else is a regression against ../explanation/code-calisthenics.md.

And the one that catches an ECS mistake specifically:

cargo test --test it determinism::

It pins that a seed produces the same walls and the same floor contents it always has. If a change to when something is spawned moves that, you have drawn from the wrong RNG stream — see map::streams::content_rng.

Appendix: quick check

1. Before a new component, check it is not an effect, a modifier, or a row of an existing kind.
2. Component: add it to models/src/components.rs as nouns only, decide and say if it is saved, and add its row to ../reference/components.md.
3. New kind of entity: a Def row type and table, a Bundle, then spawn_named and content_names.
4. Damage: combat::resolve_attack if somebody swung, helpers::apply_damage if not; the reaper finishes the dead.
5. Condition: call the verb in crate::conditions; a new one needs a marker, a verb, two match arms, a save field and a HUD badge.
6. Gear stat: equipped_total::<C>, or loadout for several; probe the marker to ask a yes or no.
7. Spawn: spawn_named for a row, roll_item for a drop; remove an item from the pack before you despawn it.
8. Input: push an intent onto its queue and return; the matching system drains it.
9. System: register it in models/src/schedule.rs with an explicit .after(), and explain the edge in ../reference/input-and-turn-loop.md.
10. Cosmetics: use get_resource_mut, roll from FxRng, and gate anything that leaks on player_sees.
11. Run cargo test --workspace, cargo clippy --all-targets, cargo fmt --all, and cargo test --test it determinism::.

See also

../explanation/ecs-in-nihilurk.md why the world is driven this way ../reference/components.md every component, resource and event ../reference/spawn-api.md the functions that build entities ../reference/input-and-turn-loop.md the schedule, in order add-an-effect.md adding a property rather than a mechanic add-an-item-category.md adding a whole new kind of item spawn-a-thing.md putting one specific thing on one tile ../explanation/code-calisthenics.md the shape this code is held to

Reference: agents

Audience       Anyone changing what a monster or a Helper does with
               its turn. Look things up here; do not read it end to
               end.
Prerequisites  None.
Status         Describes `models/src/agents.rs` and the parts of
               `models/src/ai.rs` that call it. If this page and the
               source disagree, the source is right and this page is
               a bug.

Every mob decides its turn the same way: ai builds a Percept, agents::think hands it to the mob’s RuleSet, and the first Rule that fires names one Action, which ai carries out. Nothing is remembered between turns. Why it is built this way is ../explanation/agents.md.

The turn, in order

models/src/ai.rs   step_one_mob

1. Gates. Dead (0 HP), Asleep, Petrified or out of energy: no turn.
2. Percept. perceive builds it (below).
3. Rule set. rule_set_for(movement_type, helper, ally).
4. Decision. think(&percept, set):
   • off the player’s view: the off-view rule (below), and the rule set is never asked;
   • in view: the first rule that returns Some, or Action::Wait.
5. Action. act carries it out. A Strike is a step onto the foe’s tile, so both pass the same checks (mob_can_enter): on the map, walkable (water only for a swimmer), a legal diagonal, and the room leash when leashed(&percept, set) is true. A step onto a foe queues a blow on AttackQueue; onto anyone else, the mob stands. A pinned mob never steps.

Off the player’s view

A mob on a tile the player cannot see does nothing, with two exceptions:

Both switch to their rule set the moment they stand in view. “The player’s view” is the view with their eyes open: a blinded player is still seen by the room they stand in.

Percept

Sighting is { who: Entity, at: Position, is_player: bool }.

Action

The rules

Each is a const Rule wrapping a plain function of the percept.

A clear line (agents::clear_line) is one no wall breaks; bodies in it do not count.

A spell’s footprint (agents::reaches): Dragon Breath covers items::blast_cells around its target (BLAST_RADIUS, line of sight from the centre), Lux the same at GRENADE_RADIUS, Meteor Strike at GRENADE_RADIUS plus METEOR_STRIKE_CHAIN_SPREAD (the first chain only, roughly); Sting and Thunderbolt cover their target tile; Force Lance covers its line up to the target, stopping at the first wall. A spell whose footprint is not listed there is assumed to reach everyone, so an ally never casts it.

The shortest walk is autoexplore::first_step over tiles the mob can stand on, biased toward the goal. A mob knows the floor it stands on, so it is not limited to tiles the player has seen.

The sets

The room leash: from a Room tile, a leashed mob will not step onto a Passage or a Door. The leash belongs to the tile it stands on, so from a corridor it crosses a door freely.

A CHASER’s turn reads as: pick a spell at random, fire it if it can, else shoot if it can, else go to melee. A wild monster does not care whom its spell catches. A CHASER closes in on the nearest foe, so an ally of the player standing nearer than the player draws it away from them; STRIKE still hits the player first when both are alongside. A charmed monster’s ALLY set is the same turn aimed at the monsters, and it does nothing when none is in view. The HELPER’s is the same turn aimed at the monsters, with the player never in the blast, and a walk back to the player when there is nothing to fight.

Where the pieces live

See also

../explanation/agents.md why a reflex agent, and why the view ../how-to/add-a-rule-set.md a new way to think ../how-to/add-a-rule.md a new reflex ../tutorial/give-a-monster-a-mind.md one set, start to finish

Reference: command line and environment

Audience       Anyone running the game, especially to test content.
Prerequisites  None.
Status         Describes the flags as parsed in
               `engine/src/main.rs`. If this page and the source
               disagree, the source is right and this page is a bug.

cargo run -p nihilurk -- [flags] [name-or-save]

After cargo install nihilurk, run nihilurk [flags] [name-or-save] instead. If the shell cannot find it, ~/.cargo/bin is not on your PATH; the README’s install steps shows how to add it.

Flags

In any order. Every flag has a single-dash form; the shorthand ones (-s, -c, -ns, -nb, -nshake, -mouse, -nobones, -b, -am, -scores) also have a double-dash longhand (--seed, --centered, --no-save, --no-blood, --no-shake, --mouse, --no-bones, --body, --as-monster, --leaderboard), and -endless, -anim-rate, -keymap, -content, -pride and -prideoff also take --. Any other argument that starts with - is refused, and so is a flag whose value is missing or bad (-s -5, -s abc, -anim-rate fast, -b with nothing after it); the message quotes the flag and its value: invalid argument ARG. Please see -help for more information. A player name therefore cannot start with -.

-b <body>

Which of the two written-to-be-played creatures descends. -b nihil is the default and changes nothing.

-b lurk is the other one: quadruped, fanged, clawed, furred, and a magenta @. Lower stats and the only thing it can put on is rings. What it has instead:

• SpeedKind::Quick, half again as fast as Normal and the only creature in the game born at that tempo. Two monster rounds bought per three player turns; shown as QUIK on the status line.
• The estoc’s lunge (Lunges), without the estoc’s double time.
• The rapier’s momentum (BuildsMomentum), built on the creature rather than on a blade it does not have.
• A ring of stealth’s quiet (Stealthy).
• Bide in its spellset.
• Growth. Every creature that dies on the floor is rolled against tuning constant lurk::GROWTH_CHANCE, and a hit puts one point on one of the four numbers on the status line, drawn at random: FEAR THE LURK! Rolled per kill rather than counted toward a tenth one, so there is no counter to pace against and nothing for a save file to remember.

Its tempo is deliberately lumpy: two monster rounds per three player turns means the free turn always lands third, and pacing yourself against that beat is how lurk is played.

-am <species>

The run starts in that species’ body instead of nihil’s or lurk’s. The name must be a bestiary row exactly as -content prints it; anything else stops the game before it starts rather than quietly starting you as nihil. -b and -am are the same choice asked two ways, so passing both is refused too.

What the body changes is what the bestiary row says: the glyph and its colour, the hit points, the attack and armour dice and their bonuses, the tempo (-am wraith is permanently hasted), invisibility (-am phantom), and the innate magic – a dragon is immune to fire and flies, a rattlesnake’s bite is venomous, a slime splits when hurt – into a hostile copy of you, carrying your hit points, which is working as intended. None of that is a special case for the player: the bestiary row is the same one a dragon on floor 10 is built from, and the on-hit abilities are the same table.

A row with gear chances (.equip(...)) starts you with all of it, every roll hit, worn if the body may wear it (ItemUser) and in the pack if not. A bow comes with a full stack of arrows. Only the start of a run does this; a polymorph hands out nothing.

What it does not change is who you are. You keep the @’s side of the fight, your viewshed, your pack, your score and your magic points; ai never gets hold of you.

Four consequences worth knowing before you pick a monster:

• You start with nothing. The ring mail, mace, short bow, quiver and potion are nihil’s kit.
• Only a species that uses items can wear them. That is the bestiary’s own ItemUser mark – the orc, hobgoblin, centaur, medusa, nymph, leprechaun, troll, vampire and ur-vile have hands; a dragon has claws and is told so when it tries.
• A species’ spells land in your spellset, and cost your Ma. A dragon knows Fireball, the same spell a hero coin teaches, cast through the same reticle at the same price out of your own pool. The dragons on floor 10 breathe it too, from a small pool of their own that never refills.
• The log tells you what you were born with. One “You feel…” line per grant the body carries, a spirit’s two random boons included: “You feel venomous.” Tags the HUD already shows are not repeated. Try -am dragon. You start on floor 1 with Fireball in your spell bar and claws that hold no sword.

This will never be a balanced mode of play. A floor-1 kestral and a floor-10 dragon are both one -am away, and nothing gates which one you’re allowed to start as, or scales the dungeon to match your pick. That’s deliberate: -am is a costume, not a difficulty setting, and every row in the bestiary is tuned to be one thing a @ fights, never to be the @ fighting everything else. Play it for the thrills, not for a fair fight.

Bodies and species

Cancellation draws a line between the two, on purpose.

A body cannot be cancelled. It is the creature the run is about, and no wand in the dungeon is a wand of being something else: a lurk stays a lurk, keeps its shape, and keeps the rule about rings.

A species can, apart from any part its row marks as an identity effect (the dog’s five grants, see content-tables.md, “Identity effects”). A player wearing a bestiary row keeps the shape and the dice – those are not effects at all – but the magic is only on loan: a cancelled dragon-bodied player loses fire immunity exactly as a real dragon would, and a cancelled orc-bodied one loses ItemUser, which is to say the wits to work a buckle, and can no longer equip what it was wearing a moment ago. That is the bargain of wearing something else’s magic.

The body is saved with the run and comes back on load – the player’s name is the species, and that is how the save knows. Two argument shapes are refused up front to keep that true, both before the terminal is touched:

nihilurk Dragon             # "Don't name yourself a monster. It's quite demeaning."
nihilurk -am orc mysave     # the save already knows what body it is in
nihilurk -b lurk Bae        # a name is the first argument or it is not a name

A monster’s hit points are its own, so several rows are a one or two-hit death: that is intended, and -s is how you retry it.

-h, -help, and --help print a short guide and exit before the terminal is configured. The full reference is nihilurk(6). The prebuilt tarball and the AUR package install it, so man nihilurk works there; cargo install installs the binary only, so from a clone read it with:

man ./doc/nihilurk.6

The game needs a terminal of at least 80 columns by 25 rows. In a smaller one the message log draws garbled letters. That is a known limit and will not be fixed.

-content never touches the alternate screen, so it pipes:

cargo run -p nihilurk -- -content | grep ring
cargo run -p nihilurk -- -content | less

-scores reads the same way, straight off leaderboard.sav in the data directory (-scores -fast reads leaderboard-fast.sav, -scores -endless reads leaderboard-endless.sav; each mode keeps its own board) (see NIHILURK_DATA below) – a small versioned postcard file, like a save, holding the ten highest scores ever recorded across every run that ended in a win or a death (a quit-and-save doesn’t count; the run isn’t over). Each line it prints is RANK. NAME - OUTCOME - SCORE (WHEN) followed by one ◆ per conduct that run kept (see conducts.md), where OUTCOME is WIN, LOSE (Asc.) (dead on the way back out, carrying the Element), or LOSE (Desc.) (dead on the way down), and WHEN is the UTC date and time the run ended. A version 1 leaderboard, from before conducts, is read and upgraded on the next write. A leaderboard it can’t read, damaged or from another version, is named on stderr and never overwritten: no score is recorded until it is moved away. Two runs ending at once take turns at the file through leaderboard.sav.lock.

A run that ends in a win or a death also leaves a run dump, morgue/NAME-YYYYMMDD-HHMMSS.txt in the data directory (UTC; any character of NAME that is not a letter, a digit, - or _ becomes _). It is plain text for sharing: the outcome, cause, depth and score, the final screen, the pack, every kill by name (most first), for a win the conducts kept, and the message log. The path is printed once the terminal is back. -ns does not stop it – a dump is a record of the run, like the leaderboard, not a save. A dump never overwrites another, and one that can’t be written is skipped without a word.

-s fixes the dungeon’s maps. Every floor’s walls are a pure function of (seed, depth), so floor 7 of seed 1234 is the same maze today, tomorrow, after you reload a save, and after somebody adds a monster to the bestiary. Its contents – monsters, loot, traps – are re-rolled each time you enter the floor (they key off the staircase count as well), so walking back up through floor 7 finds the same corridors freshly stocked. How you play still does not reach into generation: two runs on one seed that take the same staircases see the same everything.

The positional argument

One bare argument, meaning one of two things:

• A save file, if it is the path of a file as typed, or names one in the data directory – as is or with .sav appended, matched case-insensitively. The run is loaded, and saves back to that same file.

• A player name, otherwise. A fresh run starts under that name, saved as <name>.sav in the data directory. A name holds at most 13 characters, no control characters (an escape, a tab, a newline) and is not a Windows device name (con, prn, aux, nul, com1-com9, lpt1-lpt9, in any case); anything else is refused with a message and nothing is written. In file names (the save, recordings/, morgue/) every character that is not a letter, digit, - or _ becomes _, so a b saves as a_b.sav and ../x cannot leave the data directory.

  cargo run -p nihilurk -- nihilurk          # loads nihilurk.sav from the data directory if it is there
  cargo run -p nihilurk -- ./old.sav         # loads that file, wherever it is
  cargo run -p nihilurk -- bae           # otherwise: a new run as bae
  

If the save is clear data – a won run, which is kept rather than deleted – the game asks before spending it.

Language

The language is a build-time choice, not a flag. engine forwards one lang-* feature (en by default, pt, es, ht) to strings, models and view, and the binary carries that language only:

cargo run -p nihilurk --no-default-features --features lang-pt

The installed nihilurk command is nihilurk-dispatch, which reads LC_ALL, LANG or LANGUAGE, and execs the matching nihilurk-<lang> beside it, passing every argument through. --lang <en|pt|es|ht> as the first two arguments overrides that and is stripped before forwarding. Anything it does not recognise gets English.

A cargo install has no dispatcher and no --lang: it holds the one language it was built with. Reinstall with cargo install nihilurk --force --no-default-features --features lang-pt to switch. The prebuilt download holds all four.

Environment variables

NIHILURK_SPAWN

Comma-separated content names, dropped on free tiles around the player the moment a floor is built. The content author’s shortcut: it means you never have to play down to floor 9 to look at a floor-9 monster.

NIHILURK_SPAWN="dragon" cargo run -p nihilurk
NIHILURK_SPAWN="bow,arrow,ring of protection" cargo run -p nihilurk
NIHILURK_SPAWN="dart trap, long sword" cargo run -p nihilurk
NIHILURK_SPAWN="cursed -2 long sword,+3 ring mail,arrow x13" cargo run -p nihilurk

Details:

• Any name from -content works – monsters, items, traps, the Element itself.

• Whitespace around each name is trimmed; empty entries are skipped.

• Gear and ammunition take optional dressing, written around the name in this order: [cursed|megacursed] [+N|-N] name [xN].

  Piece	Example	Effect
  cursed	cursed ring mail	Adds the Curse tag: once worn or wielded it will not come off until a scroll of remove curse.
  megacursed	megacursed ring mail	Adds Curse and MegaCurse: nothing lifts it or destroys it.
  +N/-N	+3 long sword	Adds N to the item’s flat bonus: a weapon’s hit roll, armour’s guard, or a launcher’s throw (the arrows it looses). On a numeric ring (protection, strength, increase damage, sharpshooting) N is the ring’s whole number, so +3 ring of protection is a +3 ring. Same code as the dungeon’s own enchantment roll (catalog::apply_bonus).
  xN	arrow x13	Sets the stack size, clamped to 1..=STACK_LIMIT. x0 gives 1, and anything over the limit gives the limit.

  A curse and a minus are independent: -2 long sword is not cursed, and cursed +2 long sword is. The quality is hidden until worn or identified, as for any gear.

• A modifier the thing cannot use (a plus on a ring that is not a number, a stack on a dragon) is ignored, and the entry still counts as recognised.

• A malformed modifier (+x sword) is not a modifier: it stays part of the name, so the entry is skipped like any unknown name.

• A name the tables do not know is skipped silently. This is a debug knob, not a parser. Check your spelling against -content.

• Things are placed on the nearest free walkable tiles, searching outward in rings from the player. Nothing lands in a wall or on top of anything else.

• It applies to every floor, not just the first. Descend and your dragon is waiting again.

• Items arrive exactly as their row describes them – unenchanted, uncursed, a single arrow rather than a bundle – unless you dress them as above. For the randomised version, find one on the floor.

NIHILURK_LEVEL

Makes every floor one kind of special level instead of rolling for it. Most special levels turn up at their own small chance (constants::map), from SPECIAL_LEVEL_MIN_DEPTH down; this is how you look at one without hunting for a seed that has it.

NIHILURK_LEVEL=island cargo run -p nihilurk

Details:

• Case does not matter. A value that names no level is ignored, and floors roll as usual.
• It applies to every floor, the first and the last included – floors the roll itself never touches.
• A save rebuilds its map from the seed on load, and this is read then too. Load a save with the same value it was written with, or the floor comes back a different shape under everything standing on it.

NIHILURK_MAGICMAP

Forces the animation a scroll of magic mapping plays, instead of rolling one. Useful when you are working on the animation itself.

Anything unrecognised falls back to a random roll.

Key remapping

keymap.txt is one pair per line, two characters with no separator (Brogue’s format): hj makes pressing h act as j. List hj and jh to swap; lookup is a single pass, so pairs never chain. A key with no line acts as itself, so hl alone leaves l live too. An uppercase letter with no line of its own follows its lowercase one, so Shift-run keeps working. Blank lines and lines starting # are skipped. A line of any other length, a space as a key, or a key listed twice is refused with its line number (models::parse_keymap).

The file is read from the data directory, or from the path given to -keymap. A missing auto-loaded file is fine; a missing -keymap file is not. F1 and the sidebar hints show the key that now does each job (word keys such as Tab stay as they are). A command whose own letter is remapped away and that nothing maps to shows its old letter.

NIHILURK_READY

Set and not empty, the game writes an OSC string, ESC ] nihilurk;ready BEL, each time it blocks waiting for a key: the turn loop, the O travel cursor, and the death and victory screens. A script that drives the game through a pty reads it as “the last key has done all it will”: the play agent’s serve.sh sets it and answers a key the moment it sees the signal, instead of waiting for 250 ms without output (engine::ready).

NIHILURK_READY=1 cargo run -p nihilurk

Details:

• It comes after the frame it settles, on the same stream, so a reader that has the signal has the frame.
• Nothing is written before a read that only lets a key skip an animation or stop a walk, or while a key is already waiting to be read: the game is not waiting there.
• A terminal ignores an OSC string it does not know, so the game looks the same with it set. Unset, the game does not write it or look at the input for it.

NIHILURK_DATA

The directory nihilurk keeps its files in: saves, bones-N.sav, leaderboard.sav, leaderboard-fast.sav, leaderboard-endless.sav and the run dumps in morgue/. Set, it wins. Unset or empty, the OS convention decides (models::data_dir):

• A relative XDG_DATA_HOME is ignored, as the XDG spec says.

• With no home to go on at all, it is the current directory.

• The directory is made on the first write, not before.

  NIHILURK_DATA=. cargo run -p nihilurk # keep everything in the checkout, the old way

Recipes

Look at a new monster immediately:

NIHILURK_SPAWN="basilisk" cargo run -p nihilurk

Reproduce a run someone reported:

cargo run -p nihilurk -- -s 1234567 -ns

Walk around an island from turn one:

NIHILURK_LEVEL=island cargo run -p nihilurk

Check a name before you use it:

cargo run -p nihilurk -- -content | grep -i staff

Test a throw build from turn one:

NIHILURK_SPAWN="short bow,arrow,arrow,ring of sharpshooting" cargo run -p nihilurk

See also

spawn-api.md spawn_named, spawn_requested conducts.md the conducts behind the marks on -scores content-tables.md what the names refer to input-and-turn-loop.md where these flags are read (engine/src/main.rs) rendering.md -c, -anim-rate and -nshake in the renderer ../tutorial/add-your-first-item.md these tools in context

Reference: components, resources and events

Audience       Engine developers. Look a type up here; do not read it
               end to end.
Prerequisites  A passing familiarity with `bevy_ecs`: components are
               per-entity data, resources are singletons, events here
               travel by queue.
Status         Describes `models/src/components.rs` as it is in the
               source. If this page and the source disagree, the
               source is right and this page is a bug.

Almost every Component, Resource and Event is declared in models/src/components.rs. That file is nouns only — a component says what a thing is, never what happens as a result. The verbs are the systems: combat.rs, ai.rs, items/, visibility.rs, traps.rs.

The exceptions are the handful of resources that come with real logic attached and live with it instead: Shake (shake.rs), AutoExplore / AutoPickup / LeftBehind (autoexplore.rs), FastMove (fastmove.rs), and the pack screen’s PackIsOpen / PackMode / ItemAction (pack.rs). All of them are re-exported from models, so a call site never has to know which file they came from.

A Bundle — the struct that assembles components for one spawn (MonsterBundle, TrapBundle) — is not here. It lives next to its content table (monsters.rs, traps.rs), because it names that table’s Def row and is the one place an entity of that kind is described. See ../explanation/data-driven-content.md, “Where the pieces live”.

Two shapes recur:

• Marker — no fields. Presence is the fact (Player, Blood, Curse, Confused).
• Type key — one enum naming which one it is (Potion → PotionEffect). The key is identity for identify.rs and the save file; it is never behaviour. The catalog row turns a key into the components that do something; the mechanic is a match on the key.

“Saved?” below means the field survives models/src/saveload.rs. A transient field is rebuilt every frame or every load and deliberately left out of the save. A catalog component is re-attached from the row’s id on load (restore_from_catalog), so it is never written either.

Components — identity, position, appearance

Name::article() returns "a" / "an" for the name.

Components — what the player is

Body (models/src/body.rs, not components.rs — it is the one type this whole page’s “nouns only” file doesn’t hold, because it is read at character-build time, not by a system) is which of three shapes the run’s hero descends in: Nihil (default), Lurk, or Monster(&'static MonsterDef) — a bestiary row worn as a costume, -am <species>. One enum rather than three flags, because a player is exactly one of them.

A monster body is the one body the save writes down: SaveGame::monster_body holds the species id, and load_game puts MonsterBody and StartingBody back from it. It is not read back from Name, which is whatever the player typed. A lurk is reconstructed from the effect ledger, and nihil is what is left.

Body::equip_refusal is the one gate on whether a body can wear something, and Body::innate_tempo is the tempo it returns to when a staircase lifts whatever the floor lent it — both take &World and an Entity rather than reading Renderable’s glyph back out, on purpose: nothing else in the game guesses what a creature is from how it’s drawn.

See ../how-to/add-a-body.md for adding a fourth one.

Components — creatures and combat

| Mimic | marker — a xeroc still in disguise: it reads as an item and every “monster nearby” check skips it. reveal_mimics strips it when the player stands adjacent | xerocs | no | | Spellset | slots: Vec<SpellEffect> — the spells the creature knows, capped at constants::spells::SPELLSET_CAP | the hero | yes | | GhostOfPlayer | marker — the bones ghost of the player’s own past run; combat.rs narrates a fight with it as “you” against yourself | the bones ghost | no |

MovementType — enum, saved by variant order:

Each variant picks the rule set the monster thinks with; agents.md has what each set does.

A Helper thinks with HELPER whatever its variant. A charmed Chase monster (a Faction::Ally without Helper) thinks with ALLY.

Combat: damage = (1d[power] + power_bonus) - (1d[armor] + armor_bonus), both sides rolled independently, nothing ever misses. power is dropped by a poisoned dart trap — one point per depth tier — and healed back toward max_power.

Components — speed and tempo

The player is the clock. Monsters bank energy on each player turn and spend it in ai.rs; the player’s own tempo is run by the engine loop through the PlayerTempo resource.

SpeedKind — enum, saved by variant order (Slow, Normal, Fast, Quick — Quick last on purpose; Normal is #[default]):

Speed::COST — the energy one action costs.

Components — perception and memory

A detection that finds a stashed item strips its Hidden and Invisible too, the way a ring of perception does — Detected only paints tiles the player cannot see, so a stash left hidden would glow from across the floor and vanish on arrival.

revealed_tiles is indexed by crate::map::tile_index.

Detected is an effect held for Lifetime::Floor, and leaving the floor despawns every entity that carries one anyway. It says where, not what is happening there — a detected monster is never announced and never animates.

Components — items on the floor and in the pack

Stack tops back up to STACK_LIMIT on pickup. Backpack holds at most PACK_CAPACITY slots; stow refuses anything past that (“Your pack is full.”) and leaves it on the floor. Both are constants::items.

items::pick_up is the only way anything leaves the floor. The input handler calls it and knows none of what follows: the invisible-stash reveal, Value into the score, a Pickup spent where it lies, or stow. None back means the item is still there.

A Pickup is a different kind of thing from an item you stow, in three ways that all follow from “never carried”:

• A full pack is no obstacle. There is nothing to find room for.
• It is left alone when it would do nothing. items::would_help gates it — a red coin at full health stays on the floor, and autoexplore::known_item_tiles skips it so a walk never beelines for something it will refuse. It keeps until the day it helps.
• It can be shot — and the shooter gets the effect across the room, plus a burst twice a trap’s width. A shot that stops on a creature standing on one counts, and the renderer advertises that with a magenta cell. See content-tables.md, “Trick shots”.

PickupEffect: Coin, Health, Power, Cleanse, Strength, Platinum, Forge — saved by variant order, mechanic in models/src/items/pickups.rs.

Components — item type keys

All five key enums are saved by variant order — append, never reorder. The catalog tables (crate::catalog) are the other thing keyed off these enums.

KnownQuality is per-instance: two rings of protection are two separate rolls of the curse dice, so each needs its own KnownQuality, set the moment it’s worn (equipment::toggle_equipped/equip_silently) or a scroll of identify singles it out. identify::display_name reads it to decide whether to print a weapon/armour/launcher’s +N prefix, a (cursed) suffix, or a (vorpal vs. X) suffix — hidden for anything not yet known. Potions, scrolls, wands and rings carry no such hidden state of their own; they always show their true name.

WandEffect::needs_target() is false only for the wand of light (it floods the room, no reticle).

PotionEffect: Blindness, Confusion, ExtraHealing, FruitJuice, GainStrength, Haste, Healing, MagicDetection, MonsterDetection, Paralysis, Poison, RaiseLevel, RestoreStrength, SeeInvisible, Water, Magic, Adjustment, Polymorph.

ScrollEffect (every arm wired; BlankPaper does nothing on purpose): MonsterConfusion, MagicMapping, HoldMonster, Sleep, EnchantArmor, Identify, ScareMonster, FoodDetection, Teleportation, EnchantWeapon, CreateMonster, RemoveCurse, AggravateMonsters, BlankPaper, VorpalizeWeapon, Amnesia, Charming, Pitfall, Atonement.

WandEffect: Light, Striking, Lightning, Fire, Cold, Polymorph, MagicMissile, HasteMonster, SlowMonster, DrainLife, Nothing, TeleportAway, TeleportTo, Cancellation, Charming, Digging, Swapping.

RingEffect: Protection, Strength, Perception, Adornment, AggravateMonster, Sharpshooting, IncreaseDamage, Regeneration, SlowDigestion, Teleportation, Stealth, MaintainArmor, Polymorph, SustainForm, DualZap, Health.

RuneEffect (every arm wired; Blank does nothing on purpose and has no RUNES row): Blank, Recharging, Displacement, Justice, Chaos, Ice, Protection.

A Rune is a scroll that goes inert when read: reading spends charged instead of destroying the item, and items::recharge_runes wakes every non-blank rune in the pack on a staircase. A trapdoor does not. Only the player invokes one.

Element — not a component

Element (Fire / Cold / Drain) is a plain enum, not a component — it never lives on an entity. It sits in components.rs because both the wand mechanic and the throwing mechanic use it.

Components — throwing and launchers

A missile and a launcher never name each other; they meet at an effect (FireArrow / FireQuarrel). Resolution is items/throwing.rs.

“catalog” = re-attached by row id on load (restore_from_catalog), never written to the save.

Reach weapons (combat::resolve_reach_attack, aimed with v) are the melee counterpart:

Components — player conditions

Plated and Forged are the only conditions a staircase does not lift — the staircase is what settles them (items::settle_promises, and only for LevelChange::Stairs: a trapdoor is falling, not arriving). Any damage at all takes them back, through helpers::took_damage, which is also where the low-HP warning lives: the two things that happen to a creature because it was hurt, in one place, called from both damage paths.

Confused, Blind, Paralyzed and Speed haste/slow are treacherous — they never wear off with time. Only a staircase or a wand of cancellation clears them, all through crate::conditions::clear_player_conditions.

The first three are effects, not components of their own: rows in crate::effects’s EFFECTS, held for Lifetime::Floor, and listed once in conditions::AFFLICTIONS with the words for lifting each. That one table is what afflicted, cure_one_condition and clear_player_conditions all read. The table’s order is worst-first, because a cure takes the first row it finds. Speed haste/slow is not a row and cannot be: a tempo is a value, not a marker something either has or has not.

The verbs that put them on — confuse, blind, paralyse, hasten, shift_entity_speed, snare — live in crate::conditions, one per affliction, and each one already knows the difference between the player and a monster. snare is the exception to the “never wears off” rule above: it is counted in turns from the moment it lands, and it logs nothing, because the sentence belongs to whatever pinned you. A blinded monster has no viewshed to put out, so it gets MovementType::Confused; a paralysed one loses a share of its turns, the same coin flip the player makes.

A creature carries at most three conditions. A fourth is refused, in effects::lend — the one gate every transient effect already passes through, so a trap, a potion and a monster’s touch are all capped by the same line. lend returns false and attaches nothing; the verbs that print a success line (blind, confuse, paralyse, bide, magic ward) check it and stop. What the creature already holds stays, so nothing has to be undone.

What counts is Held::is_condition: transient and named by conditions::is_condition, which reads the lists that already declare conditions — AFFLICTIONS, FLOOR_BOONS, effects::HOLDS, and OTHER_CONDITIONS for the four with no list of their own. Both halves have to hold, and the default is exemption. A ring of regeneration lends Lifetime::WhileEquipped and fails the first half; a potion of magic detection’s Detected mark is transient but is nothing the marked creature feels, and fails the second. Neither may crowd a real condition out.

Refusing is never silent. The player reads “You already have too many conditions.” (strings::too_many_conditions). A monster’s refusal is silent, the same rule tick_effects keeps.

The priority badges

Speed haste/slow, Plated and Forged are priority badges: they are outside the ledger, so they are neither counted against the ceiling nor ever refused for a fourth condition. That is deliberate, not an oversight of the cap.

They earn it by being things the player cannot act correctly without. A tempo changes what every single step costs, and it is a value on Speed rather than a marker something either has or has not — there is nothing to shed. The two coin promises are standing bets that any damage at all cancels (helpers::took_damage) and a staircase settles (items::settle_promises); a promise silently displaced by a fourth condition would be a bet the player is still playing around and can no longer see. So they always show.

The bill for that lands on the line’s width. Three conditions, a tempo, a ring’s STLH, both promises and an auto-walk badge is a badge run long enough to reach the centred DEPTH and paint over it. That is accepted. Nothing panics — Screen::puts no-ops past the frame edge — and a player wearing that much at once did it to themselves, one potion and one coin at a time. Correcting it would mean either dropping a badge the player needs or making the line’s three anchors depend on each other again, and the whole point of splitting the HUD in two was that they do not.

Blindness does not blind the dungeon. crate::ai recomputes the view the player would have (visibility::visible_from(map, pos, false)) when they are Blind, so the monsters in the room still know exactly where they are. Drinking one is never a way to hide.

Components — traps and snares

Defined in components.rs (nouns); the mechanics are traps.rs.

TrapEffect — enum, saved by variant order (Trapdoor, Bear, Sleep, Teleport, Arrow, Dart). Keys the mechanic in apply_trap_effect; the catalog row (TrapDef) is name / glyph / rarity / snare_turns. Arrow and dart damage scale with depth — constants::traps.

TrapReveal — enum, saved by variant order (Sight, Adjacent, Triggered). Rolled equal-odds at spawn; read by visibility.rs.

The three holds — Asleep, Pinned, Rooted — are effects rather than components of their own, held for Lifetime::Turns and aged by effects::tick_effects. Asleep forfeits the turn outright (player_incapacitated); Pinned blocks movement only — a swing still lands, a step is a bloody thrash (bear_trap_thrash). Rooted is Pinned without the teeth: still biting, no thrash damage — a scroll of hold monster’s doing, and the one no trap lays. ai.rs applies the same rules to held monsters. Each runs on its own clock, so a creature can carry more than one.

Petrified is a fourth hold and the odd one out. A medusa’s gaze puts it on, it forfeits the victim’s turn exactly as Asleep does, and it protects: effects::stone_chip caps every hit at constants::combat::CHIP_DAMAGE and never lets one take the victim’s last point, on both damage paths (combat::resolve_attack and helpers::apply_hit), so the blow is reported as a chip rather than as a wound. Its one exception is a war hammer, which lends its wielder ShattersStone and goes through whole. It is deliberately not one of the HOLDS the two teleports let go of: those are things holding a creature in a place, and stone travels with the victim.

Components — score

Every change to it goes through models/src/score.rs, which is the whole scoring table in one screen:

Deaths are paid for without asking whose blade it was: half the ways a monster dies have no attacker entity to ask about. Only a staircase pays — a trapdoor, the Dungeon Lord’s portal and a potion of raise level all move you between floors for free. Treasure pays as it is taken, not at the end of the run: a gold coin’s amount, and the relic’s 25000 the moment it is in hand — and the Value comes off with the payment, so however the relic comes to hand again (it cannot be dropped, but deep water throws it back) it never pays twice.

Kills are not paid one at a time. award_kill only files the corpse under Combo, the turn’s pile; score_turn_system — dead last in the schedule, after everything that can kill — totals it with the combo multiplier, pays it in one go, and empties the pile. A multiplier applied to a number that is still growing is not one anybody can read, and one turn’s killing never combos into the next. score::double settles the pile first, so a run that ends on the same turn as a kill doubles a score that already counts it.

i64, and every write to it saturates. Nothing caps how many rings of adornment a dungeon hands out and every one of them doubles the score, so the arithmetic has to have a ceiling it stops at rather than one it wraps past — a score is always a multiple of a hundred, and a multiple of a hundred that wraps an integer lands on exactly zero.

Every payment lights the ScoreFlash resource, which the HUD shows in the scorekeeper’s place for exactly one frame (armed during the turn, aged at the same tail, dark by the next): +700 in a random bright colour, COMBO! +2400 with the word in the stripes pride::stripes(world) returns, or DOUBLE in the same. A combo also writes one log line — “With style.”, or COMBO_PRIDE_CHANCE of the time “With pride.” All of its rolls are off FxRng, never GameRng: decoration does not get to move the gameplay dice.

Events and their queues

An input handler or the AI pushes an intent onto a queue resource; the matching system drains the queue once per turn.

All five queues are transient (empty at save time).

Resources

UI and input state — all transient, Default on load

Spirits

Peaceful Faction::Spirits mobs (spirits.rs): melee on one triggers an event instead of an attack.

Also here: SpellsMenu (open, selected; the Z menu, the only way to an active spell) and SpellKind (Attack / Skill; a staff’s TurboMagic scales only the first). ExtraMonsterRound(bool) is set by a greatclub’s heavy swing; the turn loop runs one extra monster round after that action and clears it.

The pack screen

PackMode (pack.rs) is a four-column table — title, “nothing to show” line, verb, row filter — with one row per key that opens the pack:

Everything but Browse, Throw and Drop is Use, because “quaff”, “read” and “wear” are all one verb once item_system has the item in hand — the mode only decides what you were offered.

ItemAction::MENU is the fixed Use / Throw / Drop / Info order of the Browse modal (ItemAction::at(idx) indexes it).

pack_rows(world, mode) is the single place the filter is applied, and it returns backpack indices. Both the renderer and the cursor key off that list, so a menu can never highlight or act on a row it isn’t showing, and a row keeps its pack letter in every mode (the potion that is c in the pack is c in the quaff menu, alone on screen or not).

Worn gear still appears on the equip menus — that is how it comes back off.

The screen shake

Shake (shake.rs) is the effect layer’s second half, and the only cosmetic resource that is deliberately not played the way [Particles] is. These call sites arm it, and nothing else may:

The player’s own death arms nothing. Both player-death paths in combat.rs blank the @ and set Ending::player_dead without kicking the map: a death is watched, not felt through the floor. What replaces the shake is time — helpers::death_burst runs the player’s burst at PLAYER_DEATH_STRETCH (3x) the length of a monster’s, which it can afford because nothing is waiting behind it: the run is over and the death screen is next.

The durations and amplitudes are in constants::shake, read as one table by ShakeKind::shape(). A kick only displaces an already-running shake if it is worth more than what is left of it, so a kill mid-blast cannot truncate the blast — and an ordinary hit landed during either cannot truncate anything. Amplitude 2 means the first half throws the map two cells and the rest one; a terminal has no half-cell to decay through.

No kind may be shorter than two of play_shake’s 33 ms frames: it ages the shake before it draws, so anything shorter would retire without ever displacing a frame the player saw. Hit’s 80 ms is that floor. Nothing asserts it, so the constraint lives in ShakeKind::shape’s doc comment, and a kind that breaks it shows up as a shake nobody can see.

A glancing blow is the one hit that draws blood and arms no shake. It gets Particles::clink_spark instead of the landed hit’s hit_spark — same shape, no warm colour, gone quicker — because the chip-damage floor exists so a turned-aside swing isn’t nothing, not so it lands like a real one. A throw or shot the armour turned aside (strike_victim’s “glances off” branch) is the same rule at range, and takes the same spark — harsher, in fact: there is no chip-damage floor out there, so it deals nothing at all.

Melee excludes a lethal blow from the Hit kick by hand; the ranged path excludes it by asking whether the victim is at 0 HP, because helpers::apply_damage leaves a lethal shot for reaper_system to finalise. Either way the kill’s own kick — the sight-gated one — is the only shake a killing hit arms.

The sight gate on elemental_blast, kill_shake and fire_bolt is a real rule, not politeness: a shake for a blast — or a death — in an unexplored room would hand the player information the renderer goes out of its way not to draw. helpers::player_sees is the shared check, the same one the trap messages use.

Melee and the throw path need no such gate, because both log the damage they deal whether or not it was seen — the shake says nothing the message line hasn’t. A bolt is the one damage source that logs nothing per victim, so trace_bolt reports whether any of the HP it took came off a creature on a visible tile (Bolt::bit_something_seen), which is why that answer is computed there rather than in fire_bolt: the walk is the only place that still knows which tile each victim stood on.

Unlike every other animation in the game the shake never blocks input — see rendering.md, “The screen shake”, for why and for how play_shake enforces it.

Run state

GameLog::add() pushes plain text to both history and unread. GameLog::add_colored(message, category) is the same, except the copy that lands in unread — a LogEntry — also carries a LogCategory. history never gets painted, so it stays bare String.