Refine Eibenreith Ink bucket architecture

2026-05-24 11:21:57 +02:00
parent d42540f29d
commit 01c8b1aff6
14 changed files with 1522 additions and 1400 deletions
@@ -2,6 +2,82 @@

 This file documents author-facing Ink tag conventions. The active parser normalizes tags into structured `StoryTag` objects before they reach the UI.

+## Eibenreith Ink Architecture
+
+`WritingWithInk.md` is the official Ink language reference and must not be edited for project conventions. This file is the author-facing project guide.
+
+All Ink source and UI localization files must be UTF-8 and use real German characters directly: `ä`, `ö`, `ü`, `Ä`, `Ö`, `Ü`, `ß`, `„…“`. Do not replace them with `ae`, `oe`, `ue`, `ss`, or ASCII quotation marks as an encoding workaround.
+
+Eibenreith uses a bucket architecture. This is mandatory for authored content, not a suggestion. The active choice surface is collected in this priority order:
+
+1. Moment bucket
+2. Room entry or room look
+3. Room exits
+4. Episode bucket
+5. Game bucket
+
+Every room is declared through `enter_room(location, entry, look, exits, bucket)`. The room entry knot contains the one-time first description. The look knot contains the repeat look action. The exits knot contains traversal choices. The bucket contains complete conditioned weaves for local interactions.
+
+```ink
+=== train_washroom ===
+-> enter_room(loc_train_washroom, -> train_washroom_entry, -> train_washroom_look, -> train_washroom_exits, -> train_washroom_bucket) -> TURN
+```
+
+Bucket content must be written as complete conditioned weaves directly inside the bucket. Do not split ordinary bucket choices into one-line `_choices` knots or pass-through knots. A separate knot is allowed only when the content is genuinely reused or when the exception is explicitly justified, such as the identity papers tunnel in `character_generator.ink`.
+
+```ink
+=== train_washroom_bucket ===
+* {lacks(face_def)} [AUTO: Spiegelbild im Waschraum] #auto
+    -> washroom_mirror_character_generator
+
+* {lacks(washroom_toilet_used)} [__Benutze__: Die Toilette. #key:t]
+    ~ mark(washroom_toilet_used)
+    Du schiebst den Riegel vor und nimmst dir die Zeit, die eine Reise dem Körper selten höflich anbietet.
+    -> TURN
+-> DONE
+```
+
+Use `-> TURN` at the end of a chosen atomic weave when play should continue at the current choice surface. Use `-> DONE` only to close a bucket/provider knot that merely offers choices. Do not call `-> provide_choices` in authored chapter files; it is internal helper implementation.
+
+Choice text is written from Valerie's perspective before the action. It may describe intention, attention, posture, or immediate action. It must not reveal what the branch will discover after the choice.
+
+Good:
+
+```ink
+* [__Versuche__: Die andere Übergangstür. #key:w]
+```
+
+Bad:
+
+```ink
+* [__Prüfe__: Die Tür zu den Wagen zweiter und dritter Klasse. #key:w]
+```
+
+Use Ink's built-in visit tracking for simple “this knot has been seen” facts. Do not create parallel flags such as `seen_train_compartment`. Use `LIST` state only for semantic progress, encounter chains, timetable state, locations, character-generation facts, tutorials, and other authored state that has meaning beyond a knot visit.
+
+## Helper Conventions
+
+Author-facing helper functions live in `data/ink-src/eibenreith/helpers.ink` and are documented in comments there. Important families:
+
+- `route_*`: Valerie route counters such as `route_composure` and `route_sapphic`.
+- `time_*`, `day_*`, `slot_*`, `episode_*`: timetable and episode control.
+- `meal_*`: arrival-day meal plan.
+- `loc_*`, `enter_room`, `present`, `companion_*`: traversal, room setup, and companion presence.
+- `state_*`: ordered high-watermark encounter/progress state.
+- `mark`, `has`, `lacks`: exact checklist facts.
+- `tutorial`: returns true once and marks the tutorial as shown.
+- `rel_*`: relationship counters and two-value relationship-axis queries.
+
+Relationship counters use only the standard value pairs declared in `characters.ink`:
+
+- `agreeable` / `adversarial`
+- `open` / `closed`
+- `bold` / `passive`
+- `reliable` / `unreliable`
+- `insightful` / `dull`
+
+Do not add per-character custom relationship dimensions. If a concept does not fit the shared matrix, express it in prose or in a semantic encounter `LIST`.
+
 ## Implemented Tag Forms

 Use bracket tags for titles, filenames, and longer text:
@@ -90,16 +166,16 @@ Implemented choice metadata:

 The current UI renders all non-auto choices in one visible list. Choices are first grouped by `#action` in the order each new action group appears in the authored choice list. Choices inside each group are randomized. Choices without `#action` form one final unlabelled group shown after all tagged groups. Explicit keys are assigned before automatic keys; choices without explicit keys receive `1` through `0`, then `A` through `Z` in final visible order while skipping explicit keys. `#optional` choices are displayed italic. Grouping columns, `#gated[...]`, and `#sort[...]` are documented authoring conventions or future metadata, not fully implemented UI behavior yet.

-Auto choices are ordinary Ink choices, usually with no visible `[...]` choice text. Ink owns their availability and once-only behavior; the UI owns automatic selection and timing. Supported forms:
+Auto choices are ordinary Ink choices with a developer-facing choice text in `[...]`. The UI does not show that text in normal play, but Inky needs it for local testing and the text makes the source readable. Ink owns availability and once-only behavior; the UI owns automatic selection and timing. Supported forms:

 ```ink
-* {condition} #auto
+* {condition} [AUTO: Ereignisname] #auto
    -> event

-* {condition} #auto(2)
+* {condition} [AUTO: Ereignisname] #auto(2)
    -> event

-* {condition} #auto[tunnel](2)
+* {condition} [AUTO: Ereignisname] #auto[tunnel](2)
    -> event
 ```