Nightmare Configuration

Define the opt-in stacking run modifiers a player can apply on top of a difficulty tier after clearing the game.

A Nightmare is one opt-in toggle that makes a run harsher. Several can be stacked, and they sit on top of whichever difficulty tier the player chooses — a run reads as “Forsaken with Nightmares”, the tier still the noun.

Nightmares are offered on the create-save screen only to a player who has cleared the game, and a save’s choice is fixed when it is created. There is no mid-run step and no floor to record: unlike a difficulty tier, which a player may need to step down from, a Nightmare is a challenge taken on knowingly.

File Location

nightmare-config.yaml, at the root of a mod, declared in the mod manifest:

# <ModName>.yaml
nightmare-config:

Both the client and the server load this file. The client needs it to offer and name the toggles (the create-save screen runs before any server exists); the server resolves a save’s recorded ids into the multipliers the run is played by.

Fields

Each entry under the top-level nightmares: key is one toggle.

Field	Type	Required	Description
`id`	string	yes	Stable identifier, namespaced to the declaring mod. A save records this, so renaming it invalidates that save’s choice (see Ids and saves).
`display-name`	string	yes	What the player reads on the create-save checkbox and in the pause menu’s Difficulty page. Translatable — see Localization.
`description`	string	yes	One line describing what the toggle does.
`effects`	list	yes	The axes this Nightmare turns. At least one; an empty list is a load error.

Effect entries

Field	Type	Required	Description
`kind`	string	yes	Which axis to scale — one of the kinds below.
`multiplier`	float	yes	How hard to turn it. Must be finite and non-negative.

Effect kinds

`kind`	Scales
`health-regen`	The player’s passive health regeneration. `0.0` switches it off.
`healing`	Every heal applied to the player — consumables, heal-over-time effects, the granted combat verbs, and the Lua `heal` binding.
`max-health`	The player’s maximum health.
`mob-speed`	Mob walk, flight, and velocity-cap speed.
`mob-damage`	Incoming damage on the player, on top of the tier’s own multiplier.
`mob-spawn-rate`	The chance a spawn attempt proceeds. The composed result is clamped to `1.0`.
`mob-limit`	Per-type mob count limits.
`oxygen-drain`	Oxygen drain and suffocation.

The four tier-shared kinds (mob-damage, mob-spawn-rate, mob-limit, oxygen-drain) multiply the value the chosen difficulty tier already sets. The other four have no tier equivalent and start from 1.0.

Two levers are deliberately not available: the minimum-damage floor (a clamp that closes flat armor’s zero-cliff, not a danger dial — scale mob-damage instead) and the death-pile model (what dying costs is what a tier means).

How stacking composes

Every effect is a plain multiplier, and a stack composes by multiplication. Two Nightmares that each halve healing leave a quarter of it. Because multiplication commutes, the order a player ticks the boxes in — or the order the save happens to list them in — cannot change the result.

1.0 is the identity, so a run with no Nightmares leaves every value exactly as the tier set it.

The Dormant caveat

Dormant sets incoming damage to 0.0. Since composition is multiplicative, the damage-shaped Nightmares do nothing on that tier — 0.0 × 3.0 is still 0.0. This is correct arithmetic rather than a bug, and the create-save screen says so when a Nightmare is ticked on Dormant. Bear it in mind when tuning: a toggle that cannot bite on the tier a player picked is worse than one that says so.

Ids and saves

A save records the ids of the Nightmares it was created with, not their definitions. Two consequences:

An id that no loaded mod declares is skipped, with a warning, rather than refusing the save. A save that names a Nightmare from a mod that has since been removed still opens; it simply runs easier than it was created to.
Renaming an id invalidates that choice for every existing save that used it, by the rule above. Rename with that in mind.

A mod may only declare ids in its own namespace. id: my_nightmare inside mod MyMod becomes MyMod:my_nightmare; writing id: Creation:something inside MyMod is a load error, so a mod cannot declare a Nightmare that satisfies another mod’s saves.

Load errors

A malformed entry is skipped with an error rather than failing the mod — the cost is one missing toggle, not an instance that will not start. An entry is refused when it:

declares an id in another mod’s namespace,
reuses an id an earlier entry already declared,
names a kind that does not exist,
carries a multiplier that is not finite, or is negative, or
declares an empty effects list.

Example

nightmares:
  - id: sleepless
    display-name: Sleepless
    description: Wounds no longer close on their own.
    effects:
      - kind: health-regen
        multiplier: 0.0

  - id: swarm
    display-name: Swarm
    description: More of them, and they move faster.
    effects:
      - kind: mob-spawn-rate
        multiplier: 1.5
      - kind: mob-limit
        multiplier: 1.5
      - kind: mob-speed
        multiplier: 1.35

A player who ticks both plays a run with no passive regeneration, half again as many mobs, and mobs moving at 1.35× their configured speed — on top of whatever the chosen tier already does.

Last updated Sep 29, 2026