Guides / Nomad Cairn

Configuration

Every config section and key with its default, the hologram message lines, per-world overrides and region rules.

config.yml and messages.yml are written to plugins/NomadCairn/ on first startup. Every key has a working default, so an untouched file is a complete configuration. For install steps, see the Cairn page.

Run /cairn reload after editing. A misspelled key is reported as a warning at startup and on reload, naming the full dotted path. A key with a fixed set of valid values, like marker.style, that is set to something not on the list is reported the same way, and only that one setting falls back to its default. The rest of your config still applies.

marker

Marker styles

marker.style is what renders at the death location. There are six styles.

• player-head places a head wearing the player's skin.
• armour-stand places a posed armour stand.
• block-display uses a block display entity carrying the player's skin.
• hologram-only shows just a floating text label with no physical marker. Use it where other markers would look wrong, such as a build server or a minigame lobby, or clash with resource packs.
• headstone builds a small stone monument from ordinary blocks: a stone-brick wall post, a course of chiselled stone bricks and a skeleton skull on top, turned the way the player was facing. It spawns no entity of its own and is legible from a distance. It builds as tall as the room above the grave allows, down to just the skull in a one-block gap. Right-click the skull to open the grave. The stone below it is decoration only.
• corpse lays a life-size mannequin on its back where the player died, wearing their skin, head pointing the way they were facing. It is about two blocks long, so it is turned to whichever compass point has room if the one they died facing is against a wall. It comes with an invisible click target over it, because a lying entity's own hitbox is too small to right-click. It holds nothing in any equipment slot, refuses every interaction and is un-pushable, invulnerable and persistent.

Every style is decoration. The items are in the ledger.

corpse needs Paper 26.2 or newer. On a server without it, corpse still parses, is still selectable and grantable, and is still stored on the grave record. It renders as armour-stand instead, and one INFO line at startup says so.

Player choice and precedence

marker.allow-player-choice decides whether players may pick their own style with /cairn style, subject to holding the matching cairn.style.<style> permission. It is a global setting, not per-world. marker.style stays overridable per world and is what a grave uses whenever no permitted preference applies.

The style is chosen in this order.

1. marker.allow-player-choice: false gives that world's marker.style. Nothing else is consulted. A saved preference is kept on disk, so switching the setting back on restores it.
2. A player with no saved preference gets that world's marker.style.
3. A player whose preference needs a cairn.style.<style> node they no longer hold gets that world's marker.style, silently, and their preference is kept.
4. Otherwise the player's preference applies.

The style is decided once, when the grave is made, and written into the grave record. An existing grave keeps its look through reloads, restarts, sweeper re-renders and permission changes.

The floating label

Every style, hologram-only included, gets the same floating label, built from up to three lines:

Steve's grave (2d 4h)          marker.hologram
5 stack(s), 32 item(s); 356 XP marker.hologram-contents
protected 4m 12s               marker.hologram-protection

• Only the first line is unconditional.
• The contents summary appears when the grave holds something and retrieval.contents-preview-enabled is on for its world.
• The protection line appears only while grave.protection-minutes is still running, and disappears when it lapses. It ticks once a second while a player is near enough for the chunk to be loaded.

All three lines live in messages.yml, and there is no config key for any of them. Blank a line's message and that line is not drawn. Large numbers are shortened, such as 12.3k and 1.2M, and truncated rather than rounded, so the label never claims more than the grave holds. A grave whose items were partly collected switches to marker.hologram-contents-items-only, which has no <stacks> placeholder.

grave

Protection window

A player opens a grave by right-clicking its marker, or by clicking its entry in /cairn. Both use the same rule.

• The owner may always open their own grave.
• Anyone else, within grave.protection-minutes of the death, is refused and told how many minutes are left, unless they hold cairn.loot.other.bypass.
• Anyone else, after that, may open it if they hold cairn.loot.other, which defaults to true.

So protection-minutes: 5 is a five-minute head start to get back to your body. protection-minutes: 0 is a free-for-all from the instant of death. Revoking cairn.loot.other makes graves fully private however long the window is. There is no extra config key for any of those. See Permissions.

The key is per-world overridable, and a grave is judged by its own world's setting, not by the world the looting player is standing in.

While the window is open, the remaining time is a live countdown on the floating label (marker.hologram-protection). It is not the expiry countdown on the label's first line. Protection says who may loot. expiry-minutes says when the grave stops existing. A server can run either without the other.

On expiry

on-expiry decides what happens to a player's items when a grave's timer runs out and nobody claimed it. Neither option drops items into the world. To let other players loot a grave, use protection-minutes and cairn.loot.other instead. That applies while the grave is alive. Expiry is only the end of the clock.

• archive stops showing the marker and forgets the grave record, but the items are not gone. The custody row moves into Cairn's archive, where it keeps the items. No player can reach it by any ordinary gesture, so treat it as recoverable, but recovery needs staff. It is the default because it is the only option that cannot lose a player's inventory while nobody is watching.
• destroy sweeps the grave and the items are gone for good. Choose it on a hardcore or PvP-loot server where grave decay is part of the game. The retained experience goes with the items.

To recover an archived grave, run /cairn restore <player> <id>, where the id is either the custody id or the grave id the archive still remembers. Each grave is logged with its custody id and the exact command as it is archived, and /cairn verify lists every archived row the same way. The restore puts the grave back where the admin is standing, with a fresh full expiry-minutes. The player had no reachable grave for the whole archive period, so they get the whole window.

Retained experience is the exception. The custody engine stores items and not XP. When a grave expires under archive, its retained experience is handed to the world as orbs at the grave's location. That means another player standing there when the timer fires can collect it, and /cairn restore rebuilds an expired grave with no experience on it. If the chunk is unloaded at that moment, the experience is lost and logged at WARNING. Cairn does not force a chunk into memory on a timer to avoid it.

retrieval

Fee models

A fee needs Vault and a registered economy plugin. If either is missing, the fee is skipped and logged once at startup, never on every retrieval, so a missing optional dependency never blocks a player recovering their own items.

• none charges no fee.
• flat charges retrieval.fee.amount as a flat currency amount per retrieval.
• per-distance charges retrieval.fee.amount times the distance in blocks between the player and the grave.

There is no value-based model. model: per-item-value is still accepted rather than failing the load, and is reported at startup the same way an unknown key is.

cairn.fee.exempt and the tier.fee-waiver tier both waive any fee outright, whatever the model.

Contents preview

retrieval.contents-preview-enabled is read for the grave's world, never the viewer's, so a grave carries its rules across a portal. It gates three things: the itemised Contents: list in the /cairn menu, the one-line summary on that menu icon, and the summary line on the floating label above the grave.

To keep the menu preview but not the floating summary, blank marker.hologram-contents and marker.hologram-contents-items-only in messages.yml instead.

storage

Changing storage.folder needs a full server restart, not /cairn reload. The record directory is only read once, at plugin enable, so existing grave records do not follow a new name until the server comes back up.

tier

Tiered limits map onto permission nodes rather than config values, so you can sell them as rank perks. The scheme and a LuckPerms template are in Permissions. These keys configure the plumbing. They are global only, because a tier comes from the player's rank, never from which world they are in.

Raise tier.scan-range only if you plan to grant count, teleport or fee-waiver a tier permission numbered above 64.

A permission granted above its bound is not silently ignored. /cairn reload checks every online player against the freshly loaded bounds and reports anything granted too high to be read, by node name, to the console and as a count to whoever ran the reload.

Grave limit behaviour

tier.count.at-limit has two options, and neither silently discards a grave.

• refuse makes no new grave. The death behaves like vanilla and items drop on the ground.
• expire-oldest expires the player's oldest grave immediately, following grave.on-expiry for its world, to make room. With archive the evicted grave's items stay retrievable by an admin. With destroy they do not.

Grave expiry and XP retention also have tier overrides (cairn.limit.expiry.<N> in minutes, cairn.limit.xp-retention.<N> in percent). The permission suffix is the value granted, so there is no separate config default. A player with none of those permissions gets that world's grave.expiry-minutes and grave.xp-retention-percent.

notices

Whether an admin holding cairn.admin.audit is told about custody trouble without asking: a policy-resolved release, or a capture that failed outright and left nothing durable holding the items. Global only.

An alert goes to every online holder of cairn.admin.audit immediately, and is queued for anyone offline so it is delivered on their next join. Every admin sees every alert once. Retention is bounded so a server with nobody holding cairn.admin.audit does not accumulate one file per loss forever. Raise the value if your admin team is routinely offline longer than a week, or lower it if you would rather old alerts expire.

conservation-watch

The check /cairn verify runs on demand (captured = delivered + held), run without being asked, on a timer and on join. It is report-only: a discrepancy is alerted through notices.admin-alerts-enabled and logged, and nothing is ever repaired, released or voided by this check. Global only.

conservation-watch.enabled and notices.admin-alerts-enabled are both re-read live, so switching either off with /cairn reload takes effect on the very next check.

compass

Whether an ordinary compass a player carries points at their most relevant held grave. Global only.

No item is granted and no inventory slot is touched. A player's target is the nearest of their own graves in the world they are standing in. If none is in that world, it falls back to their most recent grave anywhere.

The target is recomputed on join and then every refresh-minutes, not the instant a grave is retrieved, expires or is archived. A compass can point at a grave that was just collected for up to one refresh interval before it catches up.

notify

Whether a player is told in chat, on login, how many graves are waiting for them. It is the same figure /cairn held would show. Global only.

This is a live read taken on every join. A missed reminder is simply asked again the next time that player logs in.

Per-world overrides

Add a worlds: section keyed by world name. Any key under marker, grave or retrieval can be repeated per world. Only the keys you mention are overridden, and everything else for that world falls back to the global value. storage.folder and the tier.* keys are global only.

worlds:
  world_the_end:
    grave:
      expiry-minutes: 60
      on-expiry: destroy
    retrieval:
      teleport-enabled: false
  creative:
    marker:
      style: hologram-only
  minigame_lobby:
    grave:
      enabled: false

In this example the End gives players one hour to reclaim a grave before it is destroyed, and disables teleporting to End graves. The creative world keeps grave tracking on but shows only a hologram, not a physical marker. The minigame lobby turns Cairn off entirely, so deaths there behave like vanilla Minecraft.

worlds: {} is the shipped default: no overrides, every world uses the global settings.

Regions

Regions are a third override scope under worlds:. They decide what a death inside them does. There are two ways to set that.

With WorldGuard

If WorldGuard is installed, Cairn registers a cairn-death flag:

/rg flag spawn cairn-death no-marker

no-marker is the one to use if you are not sure. /cairn lists every grave a player owns and retrieval has no proximity requirement, so suppressing the marker keeps plugin furniture out of your build without taking anything from the player. keep-inventory needs care: on a PvP arena it hands everyone their kit back on death.

A region with no cairn-death flag says nothing, and a zone below still applies. A child region inherits its parent's flag, so normal is how a region inside one you have already flagged gets the ordinary behaviour back. The flag is a rule about the place, not the player, so region membership does not bypass it.

Without WorldGuard

regions.zones is Cairn's own list. It needs no other plugin and works on Folia.

regions:
  zones:
    - name: spawn
      world: world
      min: [-64, -64, -64]
      max: [64, 320, 64]
      cairn-death: no-marker
    - name: arena
      world: world
      min: [200, 0, 200]
      max: [280, 120, 280]
      cairn-death: drop
      grave:
        protection-minutes: 0

Zones are axis-aligned boxes, inclusive on every face, and corners may be given in either order. They are matched in the order written and the first zone containing the death wins. There is no priority field, so resolve overlaps by moving zones up or down the list.

Unlike a WorldGuard flag, a zone may also override any setting from the marker, grave and retrieval sections. The arena zone above drops its protection window to zero as well as suppressing the grave. That makes the scopes global, then worlds.<name>, then zone.

A zone needs name, world, min and max. A zone missing any of them is skipped with a warning in the startup log. cairn-death is optional, so a zone may exist purely to override settings.

Which source wins

WorldGuard first, then regions.zones, then the world scope, then global. A source only wins where it actually says something: a WorldGuard region with the flag unset does not shadow a zone underneath it, just as an unset key in a worlds: block does not shadow the global value.