Checkpoint ink architecture updates

data/ink-src/eibenreith/eibenreith_game_design_document.md

@@ -126,6 +126,7 @@ Dauerhafte Regeln:
 - Richtige Richtung: Wahre Form, Prüfe, Entwaffne, Verplappere dich, Benenne, Schone, Trotze, Reize, Präzisiere, Zügle dich.
 - Jede Dialogzeile soll sozial gelesen werden: Was tut Valerie mit diesem Satz?
 - Nicht nur relevant, was sie sagt, sondern zu wem sie es sagt.
+- Verbindliche Dialogchoice-Form: `[__%Verb% %Figur%__: „%gesprochene Zeile%“]`, sofern die Choice eine tatsächlich gesprochene Zeile darstellt.
 - Reaktion muss Wirkung zeigen: Nähe, Distanz, Kontrolle, Irritation, Vertrauen, Öffentlichkeit.
 - Valeries gesprochene Zeilen sollen nicht automatisch im Fließtext stehen, wenn der Spieler an dieser Stelle wählen soll.
 
@@ -2312,8 +2313,8 @@ Aktiv verwendete Choice-Tags:
 #action:name
 #auto
 #auto(2)
-#auto[keyword]
-#auto[keyword](2)
+#auto:keyword
+#auto:keyword(2)
 ```
 
 Ältere oder geplante Metadaten wie `#id`, `#bucket`, `#priority`, `#route`, `#required`, `#repeat`, `#weight`, `#slot`, `#episode`, `#group` und `#location` sind derzeit keine verbindliche aktive UI-/Engine-Filterlogik. Sie dürfen nicht als funktionierend vorausgesetzt werden, bis Parser, Server und UI sie nachweislich unterstützen.
@@ -2328,7 +2329,7 @@ Beispiel:
     -> TURN
 ```
 
-Die Ink-Seite zählt keine Auto-Turns und setzt keine Auto-Flags. Ein Zahlenparameter begrenzt die Auslösung auf mindestens diese Anzahl UI-Choice-Turns seit dem letzten passenden Auto-Trigger. Ohne Keyword gilt die Begrenzung global; mit Keyword gilt sie nur für Auto-Trigger desselben Keywords. Beispiel: `#auto[tunnel](2)` wartet zwei Choice-Turns seit dem letzten `tunnel`-Auto, blockiert aber keinen `#auto[religion]`.
+Die Ink-Seite zählt keine Auto-Turns und setzt keine Auto-Flags. Ein Zahlenparameter begrenzt die Auslösung auf mindestens diese Anzahl UI-Choice-Turns seit dem letzten passenden Auto-Trigger. Ohne Keyword gilt die Begrenzung global; mit Keyword gilt sie nur für Auto-Trigger desselben Keywords. Beispiel: `#auto:tunnel(2)` wartet zwei Choice-Turns seit dem letzten `tunnel`-Auto, blockiert aber keinen `#auto:religion`. Auf Choice-Zeilen ist für keyed Auto-Tags die Doppelpunktform verbindlich.
 
 ## 5.16 Do / Don't für Dialogchoices
 
@@ -3367,6 +3368,8 @@ Standardwerte pro wichtiger Figur:
 
 Diese Werte sind nicht paarweise zu einem einzigen Vorzeichenwert reduziert. Ein NPC kann Valerie zugleich offen und verschlossen, zuverlässig und unzuverlässig erlebt haben.
 
+Die Richtung der Matrix ist immer: **Figur liest Valerie**. `viktor_insightful` bedeutet, dass Viktor Valerie als einsichtsvoll, scharf oder wahrnehmungsfähig erlebt. Es bedeutet nicht, dass Viktor selbst einsichtsvoll handelt. Wenn Viktors Verhalten beschrieben werden soll, gehört das in Prosa, einen Encounter-State oder eine konkrete Szene.
+
 ## 8.2 Warum Ink-intern
 
 Die Beziehungsmatrix bleibt Ink-intern, weil die wichtigen Figuren endlich und authored sind. Ein engine-seitiges String-Dictionary wäre flexibler, aber weniger transparent beim Schreiben.
@@ -3482,6 +3485,11 @@ Aus Jon Ingolds *Narrative Sorcery* gilt:
 - Encounters speichern Fortschritt nicht über willkürliche Flags, sondern über klare semantische Zustände.
 - Ink-`LIST`s sind das richtige Werkzeug für geordnete State Chains.
 - State Chains sind High-Water-Marks: Ein späterer Zustand impliziert die früheren Zustände derselben Kette.
+- Sobald ein Tracker einen linearen Vorgang ausdrückt, wird dafür eine eigene `LIST` mit den `state_*`-Helfern verwendet. Das gilt auch für Zwei-Zustand-Vorgänge wie begonnen und vollendet.
+- Der Nullzustand einer Progress-Liste ist die leere Kette. Er wird nicht als eigenes `none`-, `unknown`- oder `unset`-Element in die Liste geschrieben. Bei Bedarf wird er mit `state_unstarted(state)` abgefragt.
+- Eine Kette wird mit `state_reach(first_state)` begonnen. Spätere Handlungen, die eine bereits begonnene Kette erfüllen können, verwenden `state_reach_if_started(later_state)`. So kann eine allgemeine Handlung mehrere aktive Vorgänge bedienen, ohne einen davon rückwirkend zu starten.
+- Wenn ein komplexer Encounter sauberer durch mehrere parallele Progress-Tracker modelliert werden kann, ist diese Variante einer großen Sammelkette vorzuziehen. So funktionieren auch Inkle-artige Knowledge-Bases: getrennte Wissens- und Fortschrittslinien entwickeln sich unabhängig und werden erst im Content gemeinsam abgefragt.
+- `mark`, `has` und `lacks` sind nur für zusammengehörige Gruppen einzelner Facts gedacht, die unabhängig voneinander wahr sein können und keine Reihenfolge implizieren.
 - Diese State Chains sind Autorwerkzeuge, keine sichtbaren Questbäume. Der Spieler soll sie nicht „abarbeiten“, sondern sich frei in einer glaubwürdigen Situation verhalten.
 
 State Trees sollen Bedeutung modellieren, nicht Knotenbesuche. Für einfache Fragen wie „wurde dieser Knot schon gelesen?“ ist Ink-eigener Visit-State zu verwenden. Keine zusätzlichen Flags für bloße Knot-Besuche anlegen.
@@ -3834,8 +3842,66 @@ Konvention:
 ~ route_inc(route_sapphic)
 ~ route_inc_by(route_detective, 2)
 {route_reached(route_composure, 3): ...}
+{route_repeated(detective, 3): ...}
+{route_is_clear(detective, 2): ...}
+{route_beats(composure, eccentric, 2): ...}
 ```
 
+Die einfachen `route_*`-Zähler speichern Valeries wiederholte Ausdrucksmodi. Für autorenseitige Heuristiken gibt es zusätzlich `RouteId`-Werte:
+
+- `composure`
+- `detective`
+- `lover`
+- `sapphic`
+- `careless`
+- `eccentric`
+
+`route_repeated(route_id, amount)` bedeutet, dass diese Route oft genug gewählt wurde, um als Muster gelesen zu werden. `route_is_highest(route_id)` bedeutet, dass diese Route derzeit die höchste ist oder den höchsten Stand teilt. `route_is_clear(route_id, margin)` bedeutet, dass diese Route um mindestens `margin` vor allen anderen liegt. Diese Funktionen sind Heuristiken, keine Erinnerungen an konkrete Entscheidungen.
+
+## 12.5.1 Tracking-Domänen
+
+Die Tracking-Methoden dürfen nicht vermischt werden. Jede Variable oder Bedingung muss klar zu einer dieser Domänen gehören:
+
+- **Route-Heuristiken:** Valeries allgemeiner Ruf, wiederholte soziale Muster und Ending-Färbung. Dafür dienen `route_composure`, `route_detective`, `route_lover`, `route_sapphic`, `route_careless`, `route_eccentric` und die `route_*`-Helfer.
+- **Character Matrix:** Was eine bestimmte Figur über Valerie denkt und wie sie auf Valeries Gegenwart und Handlungen reagiert. `viktor_insightful` bedeutet: Viktor liest Valerie als scharfsinnig. Es bedeutet nicht, dass Viktor scharfsinnig handelt.
+- **Callbacks:** Konkrete frühere Choices oder konkret ausgespielte Inhalte. Diese werden über Ink-eigene Labels an Choices, Gathers, Stitches oder Knots getrackt, zum Beispiel `(asked_viktor_role)` und später `{train_compartment_bucket.asked_viktor_role}`. Für gewöhnliche Callbacks werden keine parallelen `cb_*`-Facts angelegt.
+- **Encounter State Tracker:** Fortschritt in offscreen Plotlines, Wissensketten, Zielketten, NPC-Handlungen oder Beziehungsentwicklung entlang einer Plotline. Sie sind High-Watermark-Ketten: ein späterer Zustand impliziert alle früheren Zustände derselben Liste. Sie dürfen niemals verwendet werden, um zu tracken, ob ein bestimmtes Stück Content gespielt wurde.
+
+Sobald ein Tracker einen linearen Vorgang ausdrückt, wird er als eigene `LIST` mit `state_reach`, `state_reached`, `state_before` und den übrigen `state_*`-Helfern modelliert. Das gilt auch für Zwei-Zustand-Vorgänge wie begonnen und vollendet. Wenn Vollendung den Beginn logisch einschließt, ist es ein Progress-Tracker.
+
+Der Nullzustand einer solchen Kette ist implizit: Aus dieser `LIST` wurde noch kein Wert in `story_state` gesetzt. Dafür wird kein eigener `none`-Wert angelegt. `state_started(state)` prüft, ob irgendein Wert derselben Kette erreicht wurde; `state_unstarted(state)` prüft den leeren Zustand.
+
+`state_reach_if_started(state)` ist für allgemeine Handlungen gedacht, die eine begonnene Kette weiterführen können, aber diese Kette nicht selbst eröffnen dürfen. Beispiel: Händewaschen kann `freshen_up_done` erreichen, wenn `freshen_up_started` bereits gesetzt ist; es darf aber nicht rückwirkend behaupten, Valerie sei mit dieser Absicht gegangen.
+
+Komplexe Encounter sollen bevorzugt in mehrere parallele Progress-Tracker zerlegt werden, wenn das die Autorlogik klarer macht. Eine Wissenslinie, eine soziale Verhandlungsphase und eine praktische Aufgabe dürfen getrennte Listen sein, auch wenn sie im selben Encounter zusammenwirken. Content fragt dann die Kombination dieser Listen ab.
+
+Zusätzlich gibt es unabhängige Facts mit `mark`, `has` und `lacks`. Diese sind nur für zusammengehörige Gruppen einzelner Facts gedacht, die unabhängig voneinander wahr sein können und keine Reihenfolge implizieren, etwa Tutorial gesehen, Mahlzeit am Bahnhof genommen, öffentliche Form gewahrt oder beschädigt. Solche Facts sind keine Callbacks, solange sie nicht ein konkretes abgespieltes Contentstück ersetzen.
+
+Für Choice-Surface-Arbitration gibt es `claim_choice_gate(gate)`. Dieser Helper ist kein Story-State. Er wird am Anfang jedes `provide_choices` zurückgesetzt und gibt innerhalb dieses einen Choice-Aufbaus nur beim ersten gültigen Claim für dasselbe Gate `true` zurück. Er wird verwendet, wenn mehrere Atome gleichzeitig gültig sein können, aber höchstens eines davon auf der Oberfläche erscheinen darf. Der wichtigste Fall sind priorisierte `#auto`-Familien wie Viktors Rückkehrkommentare.
+
+Die Reihenfolge der Atome im Bucket ist dann die Priorität. Auto-Choices werden vom Client getrennt behandelt, nicht randomisiert und wie normale Ink-Choices ausgelöst. Ein gemeinsamer Auto-Key wie `#auto:return(2)` taktet die Familie über mehrere Choice-Turns; `claim_choice_gate(return_auto)` verhindert mehrere Treffer im selben Choice-Aufbau. Der Gate-Claim steht immer als letzte Bedingung hinter den normalen Verfügbarkeitsbedingungen, damit eine falsche Kandidaten-Choice das Gate nicht verbraucht. Auf Choice-Zeilen wird für keyed Auto-Tags die Doppelpunktform verwendet, weil `#auto[return](2)` dort von Ink nicht akzeptiert wird.
+
+Regel: Wenn die spätere Zeile „du hast damals genau X getan“ bedeutet, ist es ein Callback und soll über ein Ink-Label laufen. Wenn sie „du wirkst auf mich inzwischen wie Y“ bedeutet, ist es eine Heuristik. Wenn sie „diese Wissens- oder Plotlinie ist jetzt mindestens so weit“ bedeutet, ist es ein Encounter State. Wenn sie „dieses unabhängige Ergebnis gilt“ bedeutet, ist es ein Fact. Wenn ein Vorgang auch nur begonnen und vollendet kennt, aber Vollendung den Beginn voraussetzt, ist es bereits ein Encounter State.
+
+Nie zulässig:
+
+- Alternative Outcomes in eine einzige `state_reach`-Kette legen.
+- `state_reach` verwenden, um „Content X wurde gespielt“ zu speichern.
+- Route-Werte oder Relationship-Werte verwenden, wenn der Text eine konkrete frühere Wahl braucht.
+- `cb_*`-Facts für normale Ink-Callbacks anlegen.
+
+## 12.5.2 Companion- und Privacy-Helfer
+
+Für Dialoge, die nur ohne Zeugen oder nur mit einer bestimmten Begleitfigur auftauchen sollen:
+
+```ink
+{present(viktor): ...}
+{alone(): ...}
+{alone_with(viktor): ...}
+```
+
+`present(character)` prüft, ob die Figur im aktuellen Raum ist. `alone()` ist wahr, wenn keine getrackte Figur im Raum ist. `alone_with(character)` ist wahr, wenn genau diese Figur anwesend ist. Bei neuen getrackten Figuren muss die Helper-Implementierung erweitert werden, damit `alone()` und `alone_with()` nicht still zu eng bleiben.
+
 ## 12.6 Conditionals
 
 Erweitertes Format:
@@ -3888,11 +3954,17 @@ Regeln:
 - Keine Ereignisse als Choice anbieten, die Valerie nicht kontrollieren kann.
 - Türen, Übergänge und unbekannte Bereiche heißen vor der Entdeckung `Versuche`, `Öffne`, `Geh weiter`, `Sieh nach`, nicht nach ihrem späteren Ziel.
 - Automatische äußere Ereignisse wie Tunnel, Pfiffe, Erschütterungen oder eintretende Figuren werden als Moment-Events ausgespielt oder hinter eine plausible Wahrnehmungshandlung gelegt.
+- Dialogchoices, die eine gesprochene Zeile darstellen, enthalten diese Zeile im Choice-Text. Ist der Adressat nicht eindeutig, steht er im fett gesetzten Handlungsteil vor dem Doppelpunkt.
+- Die verbindliche Form lautet `[__%Verb% %Figur%__: „%gesprochene Zeile%“]`, zum Beispiel `[__Prüfe Viktor__: „Welche Zeile betrifft Sie, Herr Nowak?“]`.
+- Nicht zulässig ist die zusammenfassende Form `[__Frage__: Viktor, weshalb er wirklich mitreist.]`. `Frage`, `Sage`, `Antworte` und `Sprich` sind als neutrale UI-Verben zu schwach und nur in begründeten Ausnahmefällen erlaubt.
+- Die Verben sollen Valeries soziale Bewegung benennen, nicht nur die Mechanik des Sprechens. Gute Richtungen sind `Prüfe`, `Wahre Form`, `Entwaffne`, `Benenne`, `Schone`, `Trotze`, `Reize`, `Zügle dich`, `Erkundige dich bei`, `Fordere`, `Lege offen`.
 
 Beispiel:
 
 - Falsch: `Prüfe: Die Tür zu den Wagen zweiter und dritter Klasse.`
 - Richtig: `Versuche: Die andere Übergangstür.`
+- Falsch: `Frage: Viktor, weshalb er wirklich mitreist.`
+- Richtig: `Prüfe Viktor: „Welche Zeile betrifft Sie, Herr Nowak?“`
 
 ## 13.3 Tags
 
@@ -3957,7 +4029,7 @@ Der Zug ist das erste begehbare Ambiente. Der Weg zum Waschraum ist der zentrale
 - Wagen mit Waschraum,
 - daran anschließend der Speisewagen.
 
-Die Charaktergenerierung nutzt nur dort Progressionslisten, wo es echte semantische Ketten gibt. Unabhängige Pflichtdefinitionen bleiben checklistartige Fakten. Jeder Schritt ist ein einmaliger Moment-Atom, der nur im passenden Bereich und erst nach seinen Voraussetzungen auftaucht. Wiederholbare Traversal-Entscheidungen sorgen dafür, dass der Spieler dieselben Orte mehrfach passieren kann, bis der nächste passende Moment plausibel erscheint. Keine dieser Voraussetzungen soll an jede einzelne Choice geschrieben werden; sie gehört in den jeweiligen Atom-Provider oder Traversal-Provider.
+Die Charaktergenerierung nutzt Progressionslisten für lineare Vorgänge und unabhängige Facts nur für wirklich voneinander unabhängige Definitionen. Jeder Schritt ist ein einmaliger Moment-Atom, der nur im passenden Bereich und erst nach seinen Voraussetzungen auftaucht. Wiederholbare Traversal-Entscheidungen sorgen dafür, dass der Spieler dieselben Orte mehrfach passieren kann, bis der nächste passende Moment plausibel erscheint. Keine dieser Voraussetzungen soll an jede einzelne Choice geschrieben werden; sie gehört in den jeweiligen Atom-Provider oder Traversal-Provider.
 
 Pflichtdefinitionen:
 
@@ -3999,6 +4071,7 @@ Sinnvolle Papierrollen:
 - **Viktors Memorandum:** bleibt zentral. Es enthält Reiseangelegenheiten, Cover-Story, zulässige Sprache, Auftrag der Kabinettskanzlei Seiner Majestät und vermutlich eine nicht gezeigte Handlungsanweisung zum Umgang mit Valerie.
 - **Amtschreiben / Viktors versiegelte Anweisungen:** ein Schreiben der Kabinettskanzlei Seiner Majestät ist sichtbar. Valerie war anwesend, als Viktor das Kuvert mit seinen Anweisungen übergeben wurde, hat es aber nur von außen gesehen.
 - **Hohenreiths Hilfsgesuch / Einladung / Bittschrift:** beste Quelle für den eigentlichen Anlass. Dieses Schreiben wurde an die Kabinettskanzlei Seiner Majestät gerichtet, nicht an Valerie persönlich. Valerie hat es bei der mündlichen Unterweisung gelesen, bei der ihr Viktor vorgestellt wurde. Im Zug ist es in Viktors Mappe sichtbar und kann erneut angefordert werden.
+- **Aktueller Wissensstand im Intro:** Das Hilfsgesuch nennt weder Valerie noch Amalia und spricht auch nicht ausdrücklich von einer Tochter. Es benennt nur Störungen im Haushalt und dessen Umfeld. Intro-Content darf deshalb vor der Einführung in Hohenreith nicht so tun, als wüssten Valerie oder Viktor bereits, dass Amalia der Kern des Auftrags ist. Figuren dürfen die Auslassung bemerken, aber nicht wissen, wen sie betrifft.
 - **Valeries amtliche Erfassung / Reiseformular / Passagierformalität:** bester Auslöser für Stand und Namen. Viktor händigt Valerie den Vordruck aus; der Spieler füllt ihn selbst aus. Es geht nicht um falsche Identität, sondern darum, welche soziale Wahrheit diese Valerie in der Welt hat.
 - **Valeries persönliches Notizbuch / Tagebuch / Visitenkartenetui:** möglich, aber nicht nötig für die Mission. Es kann später Persönlichkeit zeigen, sollte aber nicht die zentrale Akte ersetzen.