Georg/ai.interactive.fiction
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refine Eibenreith Ink bucket architecture

Browse Source
This commit is contained in:
Georg Tomitsch
2026-05-24 11:21:57 +02:00
parent d42540f29d
commit 01c8b1aff6
14 changed files with 1522 additions and 1400 deletions
Download Patch File Download Diff File Expand all files Collapse all files
data/ink-src/eibenreith/eibenreith_game_design_document.md
+166 -70
View File
@@ -216,7 +216,7 @@ Gesetzt:
- offizieller Sekretär / Begleiter, faktisch auch Aufsicht und Sicherheitsmensch,
- zivil gekleidet, aber militärisch/amtlich geprägt,
- kontrollierend, aber nicht platt feindselig,
- Startwerte: `viktor_closed = 1`, `viktor_control = 1`, `viktor_professional_distance = 2`,
- Startwerte: `viktor_closed = 1`,
- mögliche Entwicklung zu Respekt, Sorge, Irritation, Kontrollverlust, Verbündetenrolle.
Noch auszubauen:
@@ -1672,7 +1672,7 @@ Der sichtbare Choice-Text muss daher die soziale Absicht mitführen. Das geschie
Standardform:
```ink
* [__Absichtsverb__: „Gesprochene Zeile.“ #id:... #route:...]
* [__Absichtsverb__: „Gesprochene Zeile.“ #key:... #action:...]
```
Beispiele:
@@ -1931,7 +1931,7 @@ Mögliche Updates:
~ route_inc(route_sapphic)
~ rel_inc(amalia_open)
~ rel_inc(amalia_reliable)
~ rel_inc(amalia_fascination)
~ rel_inc(amalia_open)
```
### 5.4.5 Careless / route_careless
@@ -1968,7 +1968,7 @@ Mögliche Updates:
```ink
~ route_inc(route_careless)
~ rel_inc(viktor_concern)
~ rel_inc(viktor_unreliable)
~ rel_inc(viktor_passive)
```
@@ -2147,21 +2147,21 @@ Er erkennt möglicherweise Valeries Schutzimpuls gegenüber Amalia, aber er vers
### Viktor und Careless
Er wird besorgter und kontrollierender. Careless kann ihn menschlicher machen, aber auch seinen Aufsichtsmodus aktivieren.
Er wird besorgter und kontrollierender. Da es keine per-character Sonderwerte gibt, wird das als Eindruck auf den Standardachsen modelliert: Valerie wirkt riskanter, weniger verlässlich oder stärker beaufsichtigungsbedürftig.
```ink
~ rel_inc(viktor_concern)
~ rel_inc(viktor_control)
~ rel_inc(viktor_unreliable)
~ rel_inc(viktor_closed)
```
### Viktor und Eccentric
Er erlebt Regelbruch als Risiko. Manchmal respektiert er Mut; oft registriert er Kontrollverlust.
Er erlebt Regelbruch als Risiko. Manchmal respektiert er Mut; oft registriert er Widerspruch oder Gefahr.
```ink
~ rel_inc(viktor_adversarial)
~ rel_inc(viktor_loss_of_control)
~ rel_inc(viktor_irritation)
~ rel_inc(viktor_bold)
~ rel_inc(viktor_unreliable)
```
## 5.10 Dialog mit Amalia
@@ -2185,7 +2185,7 @@ Amalia kann sich ernst genommen fühlen, wenn Valerie genau zuhört. Sie kann si
```ink
~ rel_inc(amalia_insightful)
~ rel_inc(amalia_alarm)
~ rel_inc(amalia_closed)
```
### Amalia und Lover
@@ -2193,8 +2193,8 @@ Amalia kann sich ernst genommen fühlen, wenn Valerie genau zuhört. Sie kann si
Nicht als bloßer Flirt behandeln. Bei Amalia kann Lover Wärme, Charme, Bewunderung und gefährliches Funkeln bedeuten. Die Szene muss Altersnähe, Stand, Risiko und soziale Unsichtbarkeit beachten.
```ink
~ rel_inc(amalia_fascination)
~ rel_inc(amalia_desire)
~ rel_inc(amalia_open)
~ rel_inc(amalia_reliable)
```
### Amalia und Sapphic
@@ -2204,7 +2204,7 @@ Kernroute für echte Nähe. Valerie erkennt Amalia als Subjekt und nicht als fam
```ink
~ rel_inc(amalia_open)
~ rel_inc(amalia_reliable)
~ rel_inc(amalia_empowerment)
~ rel_inc(amalia_bold)
```
### Amalia und Careless
@@ -2213,7 +2213,7 @@ Valeries Kontrollverlust kann Amalia zeigen, dass Valerie nicht nur Rolle ist. D
```ink
~ rel_inc(amalia_open)
~ rel_inc(amalia_fascination)
~ rel_inc(amalia_open)
```
### Amalia und Eccentric
@@ -2222,7 +2222,7 @@ Valeries Regelbruch kann Amalia beeindrucken, aber auch erschrecken. Besonders g
```ink
~ rel_inc(amalia_bold)
~ rel_inc(amalia_alarm)
~ rel_inc(amalia_closed)
```
## 5.11 Dialog mit Dorf und Dienerschaft
@@ -2303,24 +2303,32 @@ Nicht jede Choice braucht ein Tastenkürzel. Pflicht- und Standardhandlungen pro
## 5.15 Choice-Metadaten
Für Engine-Filterung sollen Choices Tags erhalten:
Aktiv verwendete Choice-Tags:
```ink
#id:stable_unique_id
#bucket:moment|room|episode|game|travel|exit
#priority:0-100
#route:...
#required
#repeat:once_offered|once_chosen|sticky
#key:x
#letter[x]
#optional
#action:name
#auto
#auto(2)
#auto[keyword]
#auto[keyword](2)
```
Das `#id` bleibt stabil, auch wenn sichtbarer Text überarbeitet wird.
Ä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.
`#auto` markiert eine normale Ink-Choice ohne sichtbaren Choice-Text, die von der UI automatisch gewählt werden darf. 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]`.
`#auto` markiert eine normale Ink-Choice, die von der UI automatisch gewählt werden darf. **Auch Auto-Choices brauchen einen Choice-Text in eckigen Klammern**, damit die Datei in Inky testbar bleibt. Dieser Text richtet sich an Entwickler, nicht an Spieler, und ist kurz, sprechend und ohne normales Choice-Verb. Die UI zeigt ihn im Spiel nicht an.
Beispiel:
```ink
* {lacks(body_def)} [AUTO: Tunnelspiegelung] #auto(3)
...
-> 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]`.
## 5.16 Do / Don't für Dialogchoices
@@ -2578,7 +2586,7 @@ Mögliche Updates:
```ink
~ route_inc(route_detective)
~ rel_inc(amalia_insightful)
~ rel_inc(amalia_alarm)
~ rel_inc(amalia_closed)
```
### Wirkung auf Haus und Dorf
@@ -2684,8 +2692,8 @@ Mögliche Updates:
```ink
~ route_inc(route_lover)
~ rel_inc(amalia_fascination)
~ rel_inc(amalia_desire)
~ rel_inc(amalia_open)
~ rel_inc(amalia_reliable)
```
### Wirkung auf Haus und Dorf
@@ -2794,8 +2802,8 @@ Mögliche Updates:
~ route_inc(route_sapphic)
~ rel_inc(amalia_open)
~ rel_inc(amalia_reliable)
~ rel_inc(amalia_fascination)
~ rel_inc(amalia_empowerment)
~ rel_inc(amalia_open)
~ rel_inc(amalia_bold)
```
### Wirkung auf Haus und Dorf
@@ -2884,14 +2892,14 @@ Careless wirkt besonders in:
### Wirkung auf Viktor
Viktor reagiert auf Careless häufig mit Sorge und Kontrolle. Er kann menschlicher werden, aber auch stärker in seine Aufsichtsrolle fallen.
Viktor reagiert auf Careless häufig mit Sorge und Kontrolle. Er kann menschlicher werden, aber auch stärker in seine Aufsichtsrolle fallen. Mechanisch wird das über die Standardachsen ausgedrückt.
Mögliche Updates:
```ink
~ route_inc(route_careless)
~ rel_inc(viktor_concern)
~ rel_inc(viktor_control)
~ rel_inc(viktor_unreliable)
~ rel_inc(viktor_closed)
```
### Wirkung auf Amalia
@@ -2903,7 +2911,7 @@ Mögliche Updates:
```ink
~ route_inc(route_careless)
~ rel_inc(amalia_open)
~ rel_inc(amalia_fascination)
~ rel_inc(amalia_open)
```
### Wirkung auf Haus und Dorf
@@ -2995,8 +3003,8 @@ Mögliche Updates:
```ink
~ route_inc(route_eccentric)
~ rel_inc(viktor_adversarial)
~ rel_inc(viktor_loss_of_control)
~ rel_inc(viktor_irritation)
~ rel_inc(viktor_bold)
~ rel_inc(viktor_adversarial)
```
### Wirkung auf Amalia
@@ -3008,8 +3016,8 @@ Mögliche Updates:
```ink
~ route_inc(route_eccentric)
~ rel_inc(amalia_bold)
~ rel_inc(amalia_alarm)
~ rel_inc(amalia_fascination)
~ rel_inc(amalia_closed)
~ rel_inc(amalia_open)
```
### Wirkung auf Haus und Dorf
@@ -3261,11 +3269,9 @@ Startwerte:
```ink
VAR viktor_closed = 1
VAR viktor_control = 1
VAR viktor_professional_distance = 2
```
Das bedeutet: Er ist reserviert, kontrollierend und professionell distanziert, aber nicht feindselig.
Das bedeutet: Er ist reserviert, kontrollierend und professionell distanziert, aber nicht feindselig. Kontrolle und berufliche Distanz sind keine eigenen Relationship-Dimensionen. Wenn sie mechanisch relevant werden, gehören sie in Encounter-State-Listen wie `ViktorRelationFrame`, nicht in per-character Sonderwerte.
## 7.4 Die Hohenreith-Familie
@@ -3368,32 +3374,31 @@ Die Beziehungsmatrix bleibt Ink-intern, weil die wichtigen Figuren endlich und a
Ink-Lösung:
- 10 Standardvariablen pro wichtiger Figur,
- projektbezogene Zusatzvariablen nach Bedarf,
- universelle `rel_*`-Hilfsfunktionen mit `ref`.
- keine benannte Achsen-Liste für die fünf Relationship-Paare.
Die Ingold-Funktionen `high(tension)`, `up(tension)`, `down(tension)` und `low(tension)` setzen voraus, dass ein Stat als benannte Blackbox übergeben werden kann. In unserem Ink-Modell ist das nicht die einfachste Form, weil Ink keine echten Objekt-/Dictionary-Referenzen für `viktor.openness` oder `amalia.trust` anbietet. Die authoring-freundlichere Fassung ist deshalb direkt:
```ink
{rel_up(viktor_open, viktor_closed)}
{rel_high(amalia_reliable, amalia_unreliable)}
```
Das benennt keine abstrakten Achsen, sondern nutzt die beiden konkreten Zähler, die der Autor ohnehin im Blick hat. Eine zusätzliche `RelationshipAxis`-Liste wäre erst sinnvoll, wenn wir später bewusst eine stärker black-boxed API wie `rel_up(viktor, openness)` bauen. Dafür müsste Ink aber pro Figur und Achse explizit mappen, was mehr Boilerplate erzeugt als es derzeit spart.
## 8.3 Zusatzwerte
Zusatzwerte sind erlaubt, wenn sie spezifisch erzählerisch gebraucht werden.
Per-character Zusatzdimensionen sind verworfen. Sie sind zu schwer wartbar und unterlaufen die gemeinsame Relationship-Heuristik. Wenn ein Eindruck nicht über `agreeable/adversarial`, `open/closed`, `bold/passive`, `reliable/unreliable` oder `insightful/dull` ausdrückbar ist, gibt es zwei Möglichkeiten:
Amalia:
- Es ist keine persistente Mechanik, sondern Prosa.
- Es ist ein konkreter Fortschritt in einem Encounter und gehört in eine semantische `LIST`.
- desire,
- shame,
- alarm,
- fascination,
- empowerment,
- containment.
Beispiele:
Viktor:
- concern,
- irritation,
- control,
- loss_of_control,
- professional_distance,
- personal_involvement.
Nicht jede Figur braucht Zusatzwerte. Keine Variablen auf Vorrat für unwichtige NPCs.
- Viktors Sorge um Valerie wird meist als `viktor_unreliable`, `viktor_closed` oder in einer passenden Encounter-State-List modelliert.
- Viktors wachsende Nähe wird als `viktor_open` modelliert.
- Kontrollverlust wird nicht als `viktor_bold` gezählt, sondern als `viktor_bold`, `viktor_adversarial` oder als Fortschritt in `ViktorRelationFrame`, wenn es um seine Rolle als Aufsicht geht.
- Amalias Begehren, Scham oder Faszination werden nicht als Sonderzähler geführt. Wenn sie Beziehungseindruck sind, werden sie über Standardachsen ausgedrückt; wenn sie Plotfortschritt sind, gehören sie in Amalia-spezifische Encounter-States.
## 8.4 Anwendung
@@ -3490,7 +3495,9 @@ Aus *Heaven’s Vault* wird das Bucket-Prinzip übernommen:
- Episode Bucket,
- Game Bucket.
Content ist atomisch. Jede Handlung, Beobachtung oder Dialogzeile ist ein kleiner Blob, der irgendwo in einem passenden Bucket liegt und nur über Preconditions entscheidet, ob er im aktuellen Augenblick sinnvoll ist. Wenn ein Atom nicht passt, wird nicht ein neuer Sonderpfad gebaut, sondern seine Preconditions werden präziser gemacht oder seine Priorität angepasst.
Content ist atomisch. Jede Handlung, Beobachtung oder Dialogzeile ist ein vollständiges, lokal lesbares Weave, das direkt in einem passenden Bucket steht und nur über Preconditions entscheidet, ob es im aktuellen Augenblick sinnvoll ist. Wenn ein Atom nicht passt, wird nicht ein neuer Sonderpfad gebaut, sondern seine Preconditions werden präziser gemacht oder seine Priorität angepasst.
Diese Bucket-Architektur ist eine **Vorschrift**, kein Vorschlag. Ein Bucket enthält die vollständigen konditionierten Weaves, die er anbietet. Es ist nicht zulässig, Bucket-Content routinemäßig in einzeilige Mini-Knots, `_choices`-Knoten oder namenlose Durchreichen auszulagern. Ein separates Knot ist nur erlaubt, wenn es wirklich von mehreren Orten wiederverwendet wird oder eine begründete Ausnahme darstellt. Die Ausnahme muss im Dateikommentar oder an der Stelle erkennbar sein. Beispiel einer gültigen Ausnahme ist der `identity_papers_tunnel` in `character_generator.ink`, weil er ein langer, zusammenhängender Charaktergenerator-Tunnel ist, der aus mehreren Startaktionen eingeschoben werden kann.
Content darf aus höheren Ebenen dynamisch aufsteigen, wenn Preconditions erfüllt sind. Genau das ist die Stärke des Systems. Episode- und Game-Buckets dürfen breit sein; sie sollen nicht künstlich nur lokal drei Choices enthalten.
@@ -3505,6 +3512,18 @@ Jede niedrigere Ebene füllt nur den Raum, den die höhere Ebene lässt. Wenn wi
Orte in einem offenen Spiel werden nicht bloß aus Vollständigkeit angeboten. Ein Ort oder eine Episode soll erst ansteuerbar sein, wenn der Spieler einen Grund hat, dorthin zu gehen. Das verhindert tote Wege und hält die Freiheit erzählerisch motiviert.
Episode-Buckets sind der richtige Ort für Ereignisse, die nicht aus einem einzelnen Raum entstehen, aber nur in bestimmten Räumen der Episode plausibel sichtbar werden. Die Ortsliste wird als sichtbare Precondition direkt über dem Weave geschrieben. Beispiel: Der Tunnel-Moment der Zugfahrt ist ein Ereignis der Episode, nicht eines bestimmten Korridors, darf aber nur in Korridoren mit Fenstern und Spiegelung auftauchen.
```ink
=== train_intro_episode_bucket ===
* {lacks(body_def)}
{loc(loc_train_clergy_corridor) || loc(loc_train_washroom_corridor)}
{not (loc(loc_train_clergy_corridor) && lacks(relig_def))} [AUTO: Tunnelspiegelung] #auto(3)
...
-> TURN
-> DONE
```
Trennung:
- Ink entscheidet, was gültig ist.
@@ -3550,17 +3569,22 @@ Choice-Tags müssen vor Auswahl lesbar sein und daher in der Choice-Klammer steh
Beispiel:
```ink
* [__Prüfe__: „...“ #id:amalia_open_followup_01 #bucket:episode #priority:70 #repeat:once_offered #route:detective]
* [__Prüfe__: „...“ #key:x #action:investigation]
```
Minimal:
Aktiv:
- `#key`,
- `#letter`,
- `#optional`,
- `#action`,
- `#auto`.
Nicht als funktionierend voraussetzen:
- `#id`,
- `#bucket`,
- `#priority`.
Optional:
- `#priority`,
- `#required`,
- `#repeat`,
- `#weight`,
@@ -3568,7 +3592,6 @@ Optional:
- `#slot`,
- `#episode`,
- `#group`,
- `#action`,
- `#location`.
## 10.5 Side Effects vermeiden
@@ -3588,6 +3611,34 @@ Richtig:
```ink
* [Choice]
~ rel_inc(amalia_open)
-> TURN
```
## 10.6 Authoring-Endmarker
`-> TURN` ist der verbindliche Endmarker für gewählte atomare Inhalte. Er bedeutet: Diese Spielerhandlung ist abgeschlossen, die aktuelle Choice-Oberfläche wird neu aufgebaut.
`-> DONE` beendet dagegen einen Bucket, einen Entry-/Look-/Exit-Provider oder einen technischen Knoten, der nur Choices bereitstellt.
Regel:
- Jede gewählte atomare Weave endet mit `-> TURN`, wenn danach weiter am aktuellen Ort gespielt werden soll.
- Bucket-Container enden mit `-> DONE`.
- `-> provide_choices` ist nur noch interne Helper-Implementierung in `helpers.ink` und soll in Kapiteldateien nicht mehr verwendet werden.
Standardmuster:
```ink
=== room_bucket ===
* {precondition} [__Untersuche__: Das Objekt. #key:x]
Text der Handlung.
~ state_reach(something_seen)
-> TURN
+ [__Schaue__: Im Raum umher. #key:l]
Wiederholbare Raumwahrnehmung.
-> TURN
-> DONE
```
---
@@ -3684,7 +3735,11 @@ Enthält:
- Location-Helfer,
- Traversal-Helfer,
- State-Helfer,
- Relationship-Helfer.
- Relationship-Helfer,
- `TURN`,
- `provide_choices`,
- `empty_bucket`,
- die aktive Choice-Surface-Logik.
### eibenreith_00_character_relationships.ink
@@ -3696,6 +3751,20 @@ Nur:
Keine Funktionen.
### character_generator.ink
Enthält den `identity_papers_tunnel` und vergleichbare Charaktergenerator-Strukturen.
Diese Datei ist eine begründete Ausnahme von der normalen Bucket-Regel, weil das Personalblatt ein zusammenhängender Tunnel ist, der aus mehreren natürlich surfacenden Startaktionen des Abteils eingeschoben wird. Neue Charakterdefinitionen sollen trotzdem möglichst als Moment-, Room- oder Episode-Weaves in Buckets entstehen. Weitere Ausnahmen brauchen eine klare Begründung im Kommentar.
### buckets.ink
Enthält den Game-Bucket.
Der `game_bucket` ist aktuell leer, aber strukturell wichtig. Spielweite Lore, philosophische oder persönliche Gespräche, globale Progression, Endspiel- und Climax-Content gehören hierher, wenn sie nicht an einen Moment, Raum oder eine Episode gebunden sind.
Die Choice-Surface-Engine (`TURN`, `provide_choices`, `empty_bucket`) liegt in `helpers.ink`, weil sie direkt mit den globalen Bucket-Variablen und Raumhelfern arbeitet. `provide_choices` ist interne Implementierung und wird in Kapiteldateien nicht direkt verwendet.
### Kapiteldateien
Kapiteldateien enthalten:
@@ -3706,6 +3775,14 @@ Kapiteldateien enthalten:
- lokale Struktur,
- State-/Route-/Relationship-Updates.
Kapiteldateien müssen die Bucket-Regel einhalten:
- Raumdefinitionen bestehen aus `entry`, `look`, `exits`, `bucket`.
- Die aktive Oberfläche sammelt in der Reihenfolge Moment, Room, Exits, Episode, Game.
- Buckets enthalten vollständige konditionierte Weaves direkt im Bucket.
- Einzeilige `_choices`-Knoten, Pass-through-Knots und benannte Gathers als Ersatz für lokale Weave-Struktur sind verboten.
- Wiederverwendbare Weaves sind erlaubt, wenn sie wirklich von mehreren Orten aufgerufen werden. Episode-weite Ereignisse mit Raum-Preconditions gehören in den Episode-Bucket.
## 12.2 LIST-Regeln
`LIST`s sind für:
@@ -3822,13 +3899,32 @@ Beispiel:
Verwendete Tagarten:
- `#chapter[...]`
- `#section`
- `#textblock`
- `#music[...]`
- `#image[...]`
- `#sfx[...]`
- `#tts[...]`
- `#tts(...)`
- `#tts[provider](...)`
- `#tts-openai[...]`
- `#alert[...]`
- `#achievement[...]`
- `#error[...]`
- `#score[...]`
- `#gloss[...](...)`
- Choice-Metadaten wie `#id`, `#bucket`, `#priority`, `#route`, `#required`.
- Choice-Metadaten wie `#key`, `#letter`, `#optional`, `#action` und `#auto`.
Aktuell nicht als verbindliche UI-Mechanik verwenden:
- `#bucket`
- `#priority`
- `#route`
- `#required`
- `#gated`
- `#sort`
Diese Tags sind ältere oder zukünftige Authoring-Ideen. Sie dürfen nicht als aktive Filterlogik vorausgesetzt werden, solange Parser, Server und UI sie nicht nachweislich implementieren.
## 13.3 Asset-Tags