Skip to content

Add and edit entities

Nerthus.Core (until cutover). This page describes the frozen system that runs today and is deleted at cutover. Replaced by: not yet written.

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, and how to record a change without losing what came before.

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. Every entry stays in the index; an entry can point at the entity's own file and keep its facts there - see Keep an entity's facts in its own file.

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:

  • ## Postacie Graczy is durable. The tool writes it once and never regenerates it. Edit it freely. See Player 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 eight 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
Region a named group of places Południowa Elancja

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 and maps.
  • @należy_do - who owns the entity. Most often that is the player who owns a Postać (see Player 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. See "Names, declension, and @alias" below.
  • @grupa - a faction or guild the entity belongs to.
  • @region - a named group of places the entity belongs to. See Regions.
  • @drzwi - a passage to another place. See Doors between places.
  • @status - Aktywny, Nieaktywny, or Usunięty. Retiring is a change to this tag, below. A fourth value, Niepewny, is one the tool writes itself: on a place it could not match, and on a person it heard speaking in a session log but has no entry for. See "People the tool heard in the logs" below.
  • @plik - the file the entity's sessions are copied into. See Record a session.
  • @ref - the file that holds the entity's facts, when you keep them there instead of on the entry. See Keep an entity's facts in its own file.

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.

  1. Decide the name and the type. Together they are the entity's identity, so settle them before you write.
  2. 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.
  3. 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.
  4. Write the heading and at minimum a @typ line.
  5. 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, and bring it back

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: close the active @status line and append Usunięty from the same month.

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

A block with no @status line at all counts as Aktywny - just append the Usunięty line. From that month the tool stops resolving the name, and listings can filter the entity out. The block, every tag, and the full dated history stay exactly where they are, so you can still read what the entity was and what it owned.

Bringing it back is the same gesture in reverse:

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

Retiring never cascades: a retired residence does not retire the garden inside it, and a retired group does not retire its members. It also does not burn the coin the entity was holding - move that out first, or it stays in circulation held by a name nobody resolves (Transfer coin).

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.

People the tool heard in the logs

After a session closes, the tool reads its game logs and looks at who spoke. Most speakers are characters and NPCs it already knows. For the rest it adds an entry to ## NPC and marks it for you:

### Burmistrz Filemon Ralgar
- @typ: NPC
- @first_session: 2024-11-01 (auto)
- @forma_sesyjna: Burmistrz Filemon Ralgar (auto)
- @forma_sesyjna: Filemon Ralgar (auto)
- @status: Niepewny (auto)

Niepewny (auto) means the tool is asking. The @forma_sesyjna lines are the exact names it heard, and @first_session is the date of the earliest session that used the log. It does not guess where the person lives, so there is no @lokacja - add one if you want it.

Answer by editing the entry:

If Do this
It is a real person Change @status to Aktywny. The entry is yours from then on
The name is wrong Fix the heading and leave the rest alone
It is not a person at all Change @status to Usunięty. It stays rejected
You already have them Move the @forma_sesyjna lines onto that entry, then delete this one

Do not simply delete an entry you have not answered - the tool will hear the same speaker in the same log next time and add it again. One of the four edits above is what makes it stop.

Only speakers with at least three lines are proposed, so a passer-by with one line never reaches you.

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. A block may carry as many @alias lines as it needs. Reach for one 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.

Adding an alias is never a rename. The heading stays the canonical name and every existing session copy is untouched; you are widening what the tool accepts. When you do rename an entity, change the heading and add the old name as an alias.

Do not add an alias for a one-off typo. Fix the session instead - an alias for a misspelling teaches the tool a mistake and it will match it 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.