Add, edit, and retire entities¶

An entity is one named thing the game tracks - a character, a place, a faction, an item. This page shows where entities live, how to read an entity block, how to add one, how to record a change without losing what came before, and how to retire an entity and bring it back. It also shows how the tool matches the names your sessions actually write.

Every entity has a name and a type, and the two together are its identity. NPC/Opat Perrin and Lokacja/Thuzal are different entities even if they shared a name.

Where every entity lives¶

All entities live in one generated file at the repository root: nerthus.entities.md, the index. The tool builds it from your hand-authored sources (Postaci/, Świat gry/, Organizacje/) and from what your sessions mention.

You can edit the index by hand, and your edits survive the next rebuild. The file opens with a short Polish header (# Indeks encji Nerthus) that says the file is editable and points back at this page. The rules live here, in one place, rather than being copied into every generated index where they would drift out of step.

The two kinds of section¶

The index is split into ## sections, one per type. They are not all treated the same way:

## Gracze and ## Postacie Graczy are durable. The tool writes them once and never regenerates them. Edit them freely. See Players and characters.
## NPC, ## Grupa, ## Lokacja, and ## Mapa are rebuilt from your sources on every reindex - but the rebuild merges with what is on disk instead of overwriting it. Your hand-added tags and your hand-added blocks stay exactly as you wrote them. The tool only re-derives its own machine tags and appends blocks that are missing.

When two blocks share the same name and the same type, the tool treats them as one entity and joins their histories.

The seven types¶

Type (`@typ`)	What it is	Example
`NPC`	a non-player character	`Opat Perrin`
`Grupa`	a faction, guild, or organization	`Gildia Teologów`
`Lokacja`	a place in the world	`Thuzal`, `Ithan`, `Rezydencja Tussal`
`Mapa`	a Margonem game map that depicts a place	`Rezydencja Tussal`
`Gracz`	a real player	the person behind `Eraster`
`Postać`	a character owned by a player	`Eraster`, `Lord Tussal`
`Przedmiot`	an item, a coin included	`Dzbanek herbaty`

The shape of an entity block¶

Each entity is a third-level heading naming it, followed by a flat list of - @tag: bullets:

### Opat Perrin
- @typ: NPC
- @alias: Perrin
- @lokacja: Ithan (:2026-06)
- @lokacja: Thuzal (2026-07:)
- @grupa: Gildia Teologów (2020-01:)
- @status: Aktywny
- @plik: /Postaci/NPC/Thuzal/Opat Perrin.md

One tag per line, all at the same indent. The list is flat. A tag may repeat - @lokacja appears twice above, because Opat Perrin has lived in two places, and the block keeps both.

The tags you write most often¶

@typ - the entity's type. It wins over the ## section heading the block sits under.
@lokacja - where the entity is, meaning its parent place. On a Mapa block it names the place the map depicts instead. See Locations.
@należy_do - who owns the entity. Most often that is the Gracz who owns a Postać (see Players and characters), but it names the owner of any entity: a Przedmiot names its holder this way, be that a character, an NPC, a group, a player, or a place.
@alias - an alternate name. The tool then recognizes the entity under it too.
@grupa - a faction or guild the entity belongs to.
@status - Aktywny, Nieaktywny, or Usunięty. Retiring, below, is a change to this tag. A fourth value, Niepewny, is one the tool writes itself, on a place it could not match - see Locations.
@plik - the file the entity's sessions are copied into. See Record a session.

Tag names and their values are Polish literals in their canonical form, diacritics included. Write @należy_do and Usunięty, never an ASCII spelling. Spell tag names exactly: a tag the tool does not recognize is reported to you as an error rather than quietly ignored, and your line is never dropped from the file.

Write whatever else you want, as prose¶

Not everything worth writing down is a tag. Anything in a block that is not a - @tag: bullet is yours: write plain text, wherever in the block you want it, and the tool keeps it exactly as you typed it.

### Opat Perrin
- @typ: NPC

Przełożony Gildii Teologów w Thuzal.
Odmawia rozmów o Ogrodzie Tussala - spytaj Lorda Tussala dlaczego.

- @lokacja: Thuzal (2026-07:)
- @status: Aktywny

This is the same arrangement a session has: a body you write for people, and metadata the tool reads. The tool reads none of it, so it makes no claim about the entity and never routes anything - it is a comment for whoever opens the block next. It survives every rebuild, sitting where you left it among the tags around it.

The only thing you owe it is a blank line on each side, which is how the tool tells a comment from a tag list - and you do not really owe it, because the rebuild sets those blank lines itself. It adds them if you left them out and trims them back to one if you put several. Blank lines are the only part of your spacing the tool touches; the line breaks inside your text are yours, so a multi-line note stays multi-line.

Add a new entity¶

There is no form to fill in. You add an entity by writing its block into the index.

Decide the name and the type. Together they are the entity's identity, so settle them before you write.
Check the index for a block that already has that name and that type. Two blocks sharing both merge into one entity, which is rarely what you want. If one exists, edit it instead of adding a second.
Find the ## section that matches the type and add your block at the end of it. ## NPC for an NPC, ## Lokacja for a place, and so on.
Write the heading and at minimum a @typ line.
Add whatever else you already know.

The minimum is two lines:

### Opat Perrin
- @typ: NPC

That is a complete entity. It is named, it is typed, and because it carries no @status at all it counts as Aktywny.

Anything you know at creation time can go in straight away:

### Opat Perrin
- @typ: NPC
- @alias: Perrin
- @lokacja: Ithan
- @grupa: Gildia Teologów

None of those values carries a date, which makes each of them always-active. That is the right way to seed a new block. Dates come later, when something changes.

On the next rebuild the tool merges your block in and adds its own derived tags alongside your lines. From that point the entity is live: a session that mentions Opat Perrin - or Perrin, thanks to the alias - resolves to this block.

When the name is already taken

Block headings must be unique. If a second guild chapter opens under a name the index already carries, qualify the heading with its city and give the block the bare name as an alias:

### Gildia Teologów (Ithan)
- @typ: Grupa
- @alias: Gildia Teologów
- @lokacja: Ithan

Dated values and the timeline¶

Any tag value can carry a (from:to) range, so an entity keeps its history instead of losing it. Opat Perrin's block records both of his homes:

- @lokacja: Ithan (:2026-06)
- @lokacja: Thuzal (2026-07:)

Either bound may be left open. (:2026-06) means "until June 2026", and (2026-07:) means "from July 2026 onward".
A value with no range at all is always active.
Dates are YYYY, YYYY-MM, or YYYY-MM-DD.

"Where is Opat Perrin now?" is a question the tool answers by reading the timeline. The latest still-open value wins, so the answer is Thuzal. You write the dated lines and let the tool work out the current one. Nothing stores a "current" location that you could forget to update.

Edit an entity¶

Which gesture you use depends on what kind of edit it is.

The old line was wrong. Correct it in place. A misspelled alias or a typo in a file path was never true, so there is no history worth keeping.

The old line was true and stopped being true. Close it and append. Do not overwrite - overwriting throws away the record of what used to be so.

To move Opat Perrin from Ithan to Thuzal in July 2026, close the active line's range with the month of the move and add a new line dated from that same month:

- @lokacja: Ithan (:2026-06)
- @lokacja: Thuzal (2026-07:)

You have something new to record. Append a bullet. Adding - @alias: Perrin to a block needs nothing else.

Close-and-append is the one gesture behind every recorded change, retirement included.

Retire an entity¶

When a place burns down, an NPC dies, or an item leaves play, you retire its entity. Retiring is a status change, never a deletion. The block stays in the index with its full history, and the tool simply stops recognizing the entity by name.

Open nerthus.entities.md and find the entity's block.
Close the active @status line - add the retirement month as its end bound.
Append a new - @status: Usunięty line dated from that same month.

If the block has no @status line at all, the entity counts as Aktywny. Just append the Usunięty line.

Retiring the location Ogród Tussala after a fire in June 2026. Before:

### Ogród Tussala
- @typ: Lokacja
- @status: Aktywny (2022-01:)

After:

### Ogród Tussala
- @typ: Lokacja
- @status: Aktywny (2022-01:2026-06)
- @status: Usunięty (2026-06:)

The old status is closed, not erased. Both lines stay, so the timeline records when the entity was active and when it was retired.

What stops¶

The tool no longer resolves the name. A session that mentions Ogród Tussala after June 2026 does not link to the entity.
Listings can filter the entity out by its status.

Retiring an entity does not burn the coin it was holding - that coin stays in circulation until the coin item itself is retired, so retire or transfer it separately (Transfer coin).

What survives¶

The block, every tag, and the full dated history stay in the index.
You can still read what the entity was, where it stood, and what it owned.

Never delete the block

Deleting the block by hand does not retire the entity. If the entity has a source file, the next import writes the block straight back. Closing the status range and appending Usunięty is the one retirement that lasts.

Bring a retired entity back¶

The same gesture in reverse. Close the Usunięty range and append Aktywny:

- @status: Usunięty (2026-06:2026-07)
- @status: Aktywny (2026-07:)

The entity resolves by name again from July 2026. The months it spent retired stay on the record.

Names, declension, and `@alias`¶

The tool reads Polish. Session prose almost never writes a canonical name:

Eraster spotkał się z Tussalem w jego willi w Thuzal.

It matches Tussalem to Lord Tussal on its own. Declension is understood, so you never have to bend your prose into dictionary forms for the tool to follow it.

What it cannot guess is a name that appears nowhere on the block. That is what @alias is for - it teaches the tool a name:

### Opat Perrin
- @typ: NPC
- @alias: Perrin

A session that says Perrin now reaches Opat Perrin, and so do that alias's declined forms, like Perrinie. Reach for @alias when a short form, a nickname, or a title-less name is one people will keep writing. Teaching the tool the name once beats correcting every session forever.

The place you usually notice a missing alias is a PU grant that stops on a name it cannot match - Grant PU walks through that fix.

Players and characters - the Gracz and Postać blocks and the durable roster sections of the index
Locations - the location tree, Mapa against Lokacja, and doors
Record a session - the session header, its metadata, and where session copies land
Transfer coin - coin holdings, transfers, and burning
Grant PU - the PU block and the unmatched-name fix