Questline reference

The mandatory attribute checklist, included from the repository.

Questline attributes — the complete checklist

MANDATORY. Read this note before creating or editing any questline. Every non-optional item below must hold, even when you deliberately go outside the note’s examples, branches or goal patterns. Content and style may deviate; structure, clarity and the previous/next links may not. The content tests enforce the mechanical parts (QuestlineValidationTest), and a failed test means the questline is not ready.

0. Mandatory vs optional

Every trail (questline) and every step has a fixed set of attributes. This note is the reference for authoring and for the journal: what each field means, which are required, and what the UI must show.

0.1 Creating a quest — mandatory procedure

1. Read this note (and docs/questlines.md).
2. Pick a branch and its topic; choose 1–3 parents that already exist.
3. Compute the new depth and set koreanLevel = min(5, depth).
4. Give the new trail a next if it is not on the last level, and a previous if it is not level 1. A trail that stops the tree early is invalid — the tests reject dead ends.
5. Write one goal per step and put every condition into the Korean sentence.
6. Make the clue name the action (place/use/collect/look/travel/fight/talk) and the target.
7. Add the finale and reward; run ./gradlew test.
8. Only then add German flavour text and extras.

1. Identity

2. Position in the tree

Rules:

• No cycles. A trail may have several parents (merges are the interesting nodes).
• A child must be deeper than every parent.
• First level: no previous. Last level: no next. Every other node must have both, otherwise the tree has a dead or floating branch.
• The journal tree draws exactly these edges; it does not invent extra links.

3. Korean level

TOPIK bands over 18 tree levels (gradual, not one TOPIK stage per tree level):

Ladder (data: data/ladder.json, the endings come from quest/grammar/Endings):

1. -아/어요
2. -(으)세요
3. -(으)세요, with the connectives of the level where the goal type has them
4. -아/어야 해요
5. -아/어야 해요
6. -아/어야 해요; -(으)ㄹ 수밖에 없어요 only where a sentence states a forced conclusion

A player reads at most one level above the grammar they have already met (three steps of a level open the next one), so a hard trail can read easier for a new player. The finale ends like any other step. Hints always stay at level 1.

4. Theme / branch topic

• Each branch has one topic that all its trails share (mountain branch → 산, night branch → 밤, coast branch → 바다, home branch → 집, crafting branch → 손, etc.).
• A trail’s steps should all serve that topic; a step that does not fit belongs in another branch.
• The journal detail shows the title and level, and the tree shows the branch structure, so a mismatched topic is immediately visible as a stray node.

5. Steps — the goal (the condition that finishes the step)

Every step (steps[] and finale.step) has:

Goal types and their live status marker (what the tracker shows):

6. Conditions — current and needed markers

Conditions are checked continuously and must all be true for the goal to count:

Rules:

• Every condition must appear in the Korean sentence (generated or authored).
• Conditions are spoken with the same ladder level.
• Night actions are latched at event time, so a clock jump (sleep) does not discard them.
• The status line always answers “why is it not done yet?” or “how far am I?”.

7. Fluff and presentation

8. Finale and reward

9. Validation checklist (enforced by tests)

QuestlineValidationTest now fails on:

• a non-last-level trail without a child (dead end) or a non-first-level trail without a parent

• a missing English title, order, concept list or badge

• an authored clue that does not name the goal’s action

• koreanLevel not equal to min(5, depth)

• unknown concepts/parents, cycles, non-Hangul clues, conditions missing from the Korean text.

• 100 trails, depth 18, every level 1–18 populated, no cycles, no orphan branches.

• koreanLevel == Topik.levelForDepth(depth).

• Every step teaches concepts that exist; every goal item/entity/biome is covered by a taught concept.

• Every condition appears in the Korean clue.

• Finale exists and is level 5.

• First level has no previous; every other level has a next until level 18.

• Authored Korean clues are Hangul-only (digits/punctuation allowed).

• Tree edges match requires.completed exactly.