rustkeep/CONTEXT.md

Glossar

Kanonische Begriffe für rustkeep. Nur Sprache, keine Implementierung.

Wesen

Held oder Gegner — im Code derselbe Typ. Träger von Attributen, Zustand, Tags, Inventar, Ausrüstung, gewählten Charakteroptionen und den befristeten Modifikatoren, die gerade auf ihm liegen.

Ein Wesen ist dabei nicht in sich abgeschlossen: Eine Aura wohnt beim Träger und wird erst beim Auslesen des Ziels eingesammelt.

Gegner werden in der Registry [[creatures]] definiert — mit Grundwerten, Tags, Fähigkeiten und einer geordneten ai-Liste, deren erster passender und verfügbarer Eintrag gewinnt.

Attribut

Eine benannte, veränderbare Größe an einem Wesen. Der Katalog ist fest und wird von der Engine vorgegeben — er umfasst die Grundwerte (Stärke, Geschicklichkeit, Konstitution, Charisma, Glück, Leben, Ausdauer, Level) und die abgeleiteten Kampfgrößen (Schaden, Rüstung, Trefferchance, Kritische Chance, Kritischer Faktor, Preis-Modifikator, Tragfähigkeit).

Ein Attribut ist kein Inhalt, den ein Mod anlegt: Ein Modifikator auf ein Attribut, das keine Spiellogik ausliest, hätte keine Wirkung. Der Katalog darf wachsen — aber durch die Engine, nicht durch eine TOML-Datei.

Modifikator

Eine Umrechnung eines Attributs, die gilt, solange eine Bedingung erfüllt ist. Er wird nie ausgeführt, sondern beim Auslesen des Attributs aufsummiert. Quellen sind Rasse, Klasse, ausgerüstete Gegenstände und befristete Zustände.

Beispiele: „Zwerg: +2 Konstitution", „Eisenschwert: +5 Schaden", „Segen: +10 % Kritische Chance".

Aktion

Eine einmalige Zustandsänderung. Sie feuert, wirkt, ist vorbei. Quellen sind Angriffe, Verbrauchsgegenstände, Questbelohnungen und Fallen.

Beispiele: „12 Schaden zufügen", „20 Leben heilen", „50 Gold geben", „Gift anwenden".

Eine Aktion kann einen befristeten Modifikator erzeugen — so hängen die beiden Begriffe zusammen, ohne dasselbe zu sein.

Command

Ein Kommando der Oberfläche an das Spiel — „geh nach Norden", „leg das an", „kauf drei Tränke". Nicht dasselbe wie eine Aktion, und der Unterschied ist der Grund für den englischen Namen: Eine Aktion ist Effektvokabular aus einer TOML, ein Command kommt von einem Tastendruck.

Jeder Command kostet einen Zug, auch Handel — es gibt keine Ausnahmeliste. Bildschirme zu öffnen ist dagegen kein Command, sondern reine Oberfläche und fasst den Spielzustand nicht an.

Fähigkeit

Ein benanntes, wiederholt auslösbares Angebot an den Spieler, das Aktionen ausführt. Sie erscheint im Kampfmenü, trägt Symbol und Kosten und kann gesperrt sein.

Die dritte und letzte Wirkungsform neben Modifikator und Aktion, und die Unterscheidung ist wesentlich: Eine Aktion ist eine Wirkung, eine Fähigkeit ist ein Angebot. Fähigkeiten werden von Charakteroptionen und Gegenständen gewährt, nicht im Inventar getragen — sonst könnte ein Magier seine Zaubersprüche verkaufen.

Trigger

Die vierte Wirkungsform: { on = <event>, condition = [...], actions = [...] }. Ein Modifikator rechnet um, eine Aktion wirkt einmal, eine Fähigkeit bietet an — der Trigger sagt wann.

Er darf überall stehen, wo Modifikatoren und Aktionen stehen: an Gegenständen, Affixen, Charakteroptionen und Quests. Im Trigger ist self immer sein Träger, target die andere Seite des Events.

Die Events sind Engine-Vokabular ohne Namensraum und eine feste Liste — wie Attribute und Schadenstypen.

Bedingung

Eine Liste von Prüfungen, die alle zutreffen müssen — die Liste ist implizit UND, jeder Eintrag über not negierbar. Es gibt kein ODER und keine Verschachtelung: Zwei Möglichkeiten werden zu zwei Einträgen, oder der Modder fasst sie über ein gemeinsames Tag zusammen.

Es gibt genau eine Bedingungsgrammatik, und sie gilt an Triggern wie an Modifikatoren.

Quest

Ein Trigger mit einem Zähler: count = N bedeutet, dass das Event N-mal mit erfüllter Bedingung feuern muss, bevor die Aktionen als Belohnung ablaufen. Moddbarer, namespaced Inhalt.

Eine Quest zählt erst mit, nachdem die Aktion start_quest sie angenommen hat.

Gegenstand

Ein Ding im Spiel, einheitlich strukturiert: Kennung, Name, Grundpreis, optionaler Slot, Stapelbarkeit, Verbrauch beim Benutzen, plus Listen von Modifikatoren, Aktionen und Fähigkeiten.

Es gibt keine Item-Typen. Der frühere enum ItemType vermischte drei Konzepte — Helmet war ein Slot, Consumable ein Verhalten, Currency eine Kategorie. Ein Schwert ist ein Gegenstand mit einem Modifikator auf damage, mehr nicht.

Braucht ein Gegenstand etwas, das Modifikator, Aktion oder Fähigkeit nicht ausdrücken können, ist das eine Lücke im Vokabular — sie wird dort geschlossen, nicht mit einem Sonderfeld umgangen.

Affix

Eine benannte Modifikator-Liste mit Anzeigename und Preisfaktor, die an einem einzelnen Exemplar eines Gegenstands hängt — „Flammendes Eisenschwert". Moddbarer, namespaced Inhalt (core:flaming).

Der Affix ist der Grund, warum ein Gegenstand im Spiel nicht dasselbe ist wie sein Katalogeintrag: Die Definition liegt in der Registry, das Exemplar trägt zusätzlich seine Affixe.

Strukturell ist ein Affix dasselbe wie eine Charakteroption — benannte Modifikatorliste plus Metadaten. Der Unterschied ist, woran er hängt.

Slot

Eine benannte Stelle am Charakter, an der genau ein Gegenstand getragen werden kann. Moddbarer, namespaced Inhalt mit Anzeigename und Sortierreihenfolge (core:head, meinmod:umhang). Der Charakterbogen rendert die vorhandenen Slots, statt ein festes Layout zu mauern.

Charakteroption

Eine Wahl beim Charakterbau — eine benannte Liste von Modifikatoren, Fähigkeiten und einmalig ausgeführten Aktionen. Rasse und Klasse sind Charakteroptionen, keine eigenen Konzepte.

Optionen liegen in Kategorien, und die Kategorien sind selbst moddbarer Inhalt mit einem Feld pick = N. Ein Mod kann so eine dritte Wahl („Gottheit") oder eine Mehrfachwahl („zwei Talente") ergänzen, ohne dass die Engine davon weiß.

Zustand

Der veränderliche Istwert eines Wesens — aktuelles Leben, aktuelle Ausdauer, getragene Gegenstände, aktive befristete Modifikatoren. Kein Attribut und nicht von Modifikatoren umrechenbar: Ein Modifikator wirkt auf max_health, eine Aktion ändert den Lebensstand. Die Trennung muss scharf bleiben, sonst heilt ein Ring beim Anlegen.

Schadenstyp

Eine von sieben festen Kennzeichnungen, wie Schaden gemindert wird: fire, ice, poison, shock, holy, slash, blunt. Engine-Vokabular ohne Namensraum. Zu jedem Typ gehört eine Resistenz, und Resistenz ist der einzige Minderungsmechanismus — Rüstung ist Kurzschreibweise für Resistenz gegen slash und blunt, kein eigenes Konzept.

Der Schadenstyp poison ist nicht der Modifikator core:poisoned („Vergiftet"). Der Typ sagt, wie gemindert wird; der Modifikator ist ein Zustand, der über Züge tickt.

Tag

Eine freie, namespaced Kennzeichnung an einem Wesen (core:undead, meinmod:aquatisch). Reiner Inhalt: Die Engine kennt keine Tags, sie vergleicht nur Zeichenketten. Grundlage für Bedingungen wie „+5 Schaden gegen Untote". Gegenpol zum Attribut — der Doppelpunkt zeigt dem Modder, auf welcher Seite er steht.

Zug

Die einzige Zeiteinheit des Spiels. Ein Feld weitergehen ist ein Zug, eine Kampfaktion ist ein Zug. Ein abgewiesenes Command kostet dagegen keinen — gegen eine Wand zu laufen verbraucht keine Zeit. Es gibt keine getrennte Kampfrunden-Uhr: Befristete Modifikatoren ticken auch beim Erkunden, damit „ich warte den Debuff draußen ab" eine Entscheidung mit Kosten bleibt.

Prefab

Ein von Hand gezeichneter Raum als ASCII-Block, moddbarer namespaced Inhalt. Wände, Boden und Türen stehen als Zeichen darin, dazu Plätze für Gegner, Beute, Treppe, Eingang und NPCs.

Ein Gegner-Platz sagt „hier steht ein Gegner", nicht welcher — das entscheidet die Etage. Nur so lässt sich derselbe Raum auf Etage 1 und Etage 5 verwenden. Bei NPCs ist es umgekehrt: Die nennt das Prefab selbst, denn ein Schmied ist auf jeder Etage derselbe Schmied.

Türen sind ausdrücklich markiert, damit der Generator keine Löcher in eine gezeichnete Wand stanzt. Prefabs dürfen gedreht und gespiegelt werden.

Etage

Eine Ebene des Dungeons und zugleich ihr Bauplan: Fläche, Raumzahl, Pflichträume, gewichtete Prefab- und Wesen-Auswahl, Beutetabelle. Ausgewählt wird über Tags, nie über IDs — sonst könnte ein Mod keinen eigenen Eingangsraum beisteuern.

Es existiert immer nur eine Etage; beim Abstieg wird die vorige verworfen, es gibt kein Zurückgehen. Gibt es keine Etage mit der nächsten Nummer, ist der Lauf gewonnen — die Zahl der Etagen steht nirgends im Code.

Initiative

Ein Zahlenwert am Wesen, einmal beim Betreten eines Kampfes aus dexterity plus Wurf gewürfelt. Er bestimmt die Reihenfolge innerhalb eines Zuges; bei Gleichstand handelt der Held zuerst.

Initiative ist bewusst eine Zahl am Wesen und keine Reihenfolgeliste — eine Liste wäre eine zweite Sammlung von Verweisen, die beim Tod eines Gegners ungültig würde.

Speicherstand

Der serialisierte Spielzustand, TOML, genau einer. Er wird beim Betreten einer Etage und beim Beenden automatisch geschrieben; von Hand speichern kann man nicht, und bei Tod wird er gelöscht — der Lauf ist dann vorbei.

Das Etagen-Layout steht als Text darin, nicht als Generator-Seed: Ein Mod-Update würde sonst ein anderes Layout erzeugen und den Helden in eine Wand stellen.

Fehlt beim Laden ein Mod, wird der betroffene Eintrag verworfen und gewarnt — nie der ganze Speicherstand abgelehnt.

Registry

Eine benannte Sammlung moddbarer Definitionen, geschlüsselt nach namespaced ID. Es gibt zehn, und das hier ist die kanonische Liste — sie ist über fünf Tickets gewachsen und stand sonst nirgends vollständig:

Registry	TOML-Tabelle
Gegenstände	[[items]]
Slots	[[slots]]
Charakteroption-Kategorien	[[categories]]
Charakteroptionen	[[options]]
Fähigkeiten	[[abilities]]
Affixe	[[affixes]]
Quests	[[quests]]
Wesen	[[creatures]]
Prefabs	[[prefabs]]
Etagen	[[floors]]

Jede dieser Tabellen darf in jeder beliebigen *.toml eines Mods stehen.

Die Einstellungstabelle [balance] ist keine Registry: ein einzelner Block mit festem Schema, der feldweise verschmilzt, statt als ganzer Eintrag ersetzt zu werden.

Mod

Ein Ordner mit einer manifest.toml und beliebig vielen weiteren TOML-Dateien. Das Manifest gibt dem Mod seinen Namensraum — den Präfix vor dem Doppelpunkt, den der Lader jeder ID darin automatisch voranstellt.

Das Kernspiel ist ein Mod, kein Sonderfall: core liegt als gewöhnlicher Ordner auf der Platte und wird über denselben Lader gelesen wie jeder Fremdmod. Genau das ist der Sinn — was nur für Fremdmods gilt, ist nie getestet.

Effekt

Kein kanonischer Begriff. Wird umgangssprachlich für Modifikator und Aktion benutzt; in Code, TOML und Doku ist stattdessen immer der genaue Begriff zu verwenden. Das Wort überlebt nur noch in „Effekt-Vokabular" als Sammelname für beide zusammen.