93 lines
3.4 KiB
Markdown
93 lines
3.4 KiB
Markdown
# Markup Guidelines
|
|
|
|
This file documents author-facing Ink tag conventions. The active parser normalizes tags into structured `StoryTag` objects before they reach the UI.
|
|
|
|
## Implemented Tag Forms
|
|
|
|
Use bracket tags for titles, filenames, and longer text:
|
|
|
|
```ink
|
|
#chapter[Eibenreith]
|
|
#image[statue.png](square)
|
|
#music[Kaiserpunk Waltz.mp3](crossfade, loop, lead=8)
|
|
#sfx[church-bells.ogg](max=8, fade)
|
|
#score[You reached an ending.]
|
|
#achievement[First Steps]
|
|
#alert[Try examining the room.]
|
|
```
|
|
|
|
Use colon tags for short identifiers, categories, and choice keys:
|
|
|
|
```ink
|
|
#action:movement
|
|
#key:l
|
|
#sort:last
|
|
#gated:noble
|
|
```
|
|
|
|
Bare flags are accepted as tags with no value:
|
|
|
|
```ink
|
|
#optional
|
|
```
|
|
|
|
## Right-Page Glossary Notes
|
|
|
|
Glossary notes are story tags scoped to the paragraph/block they belong to. They affect only the right-page story rendering, never choice text or command history.
|
|
|
|
```ink
|
|
The conductor points toward Eibenreith.
|
|
#gloss[Eibenreith](A fictional alpine town in the Kaiserpunk setting.)
|
|
```
|
|
|
|
The bracket value is the visible term to find. The parenthesized value is the note shown on hover/focus. The renderer marks every matching instance of the term in the same right-page block. The tag is not displayed and is not sent to TTS. Avoid raw Ink control characters in the explanation; `|`, `{`, and `}` must be escaped in Ink as `\|`, `\{`, and `\}` if they are needed literally.
|
|
|
|
## Choice Metadata
|
|
|
|
Choice tags are placed on the Ink choice they belong to:
|
|
|
|
```ink
|
|
* [__Schaue__: Aus dem Fenster.]
|
|
#action:orientation
|
|
#key:l
|
|
```
|
|
|
|
Implemented choice metadata:
|
|
|
|
- `#key:x`: reserves keyboard key `X` for the choice.
|
|
- `#letter[x]`: older equivalent for reserving keyboard key `X`.
|
|
- `#action:group` or `#action[group]`: stores a category/template hint.
|
|
|
|
The current UI renders all choices in one list. Explicit keys are assigned first; choices without explicit keys receive `1` through `0`, then `A` through `Z` in visible order while skipping explicit keys. `#optional` choices are displayed italic. Grouping columns, stable shuffling, `#gated[...]`, and `#sort[...]` are documented authoring conventions or future metadata, not fully implemented UI behavior yet.
|
|
|
|
## Popup And End-State Tags
|
|
|
|
These tags may appear as Ink global tags, paragraph tags, or empty tag-only lines. They are dispatched through the same tag channel as media tags.
|
|
|
|
```ink
|
|
#score[You reached the quiet ending.]
|
|
#error[The story ended unexpectedly.]
|
|
#achievement[First Steps]
|
|
#alert[Try examining objects before using them.]
|
|
```
|
|
|
|
- `#score[...]`: intended ending. When the turn reaches `inputMode: end`, the UI shows a localized ending popup with the tag value as the optional message.
|
|
- `#error[...]`: unrecoverable ending. The UI shows a localized error popup with the tag value as the optional message. The Ink engine emits this automatically if Ink runs out of content without an explicit `#score[...]` or `#error[...]`.
|
|
- `#achievement[...]`: queued localized achievement popup while the game continues.
|
|
- `#alert[...]`: queued localized player hint/tutorial popup while the game continues.
|
|
|
|
## Existing Media And Structure Tags
|
|
|
|
```ink
|
|
#chapter[Title]
|
|
#section
|
|
#textblock
|
|
#image[filename.png](landscape)
|
|
#image[filename.png](portrait pause=2)
|
|
#image[filename.png](square lead=1.5)
|
|
#music[track.mp3](crossfade, loop, lead=4)
|
|
#sfx[file.ogg](max=8 fade fade-duration=2)
|
|
```
|
|
|
|
Asset filenames resolve relative to the configured image, music, and sound folders.
|