Hangul Quest

Learn Korean by playing Minecraft.

Hangul Quest is a client-side Fabric mod for Minecraft 26.3. It turns the world into a language course: a Korean sentence appears in the corner of your screen, you work out what it asks, and the game verifies that you did it. When a word blocks you, the mod explains it in easier Korean and makes you practise it before the quest continues.

There is no chat, no pop-up quiz during a fight, no server component and no network traffic. It works in single-player and on any server, with or without other players.

What is in it

• 422 questlines and 1,661 steps, arranged in a tree 22 levels deep, with 31 kinds of goal. Over 200 trails were rebuilt around small themes (the village, the kitchen, the smithy, the harbour, animals, colours) and recycle words on purpose. The Korean gets harder as you go deeper through six levels, each with one instruction ending: -아/어요, then -(으)세요, then -아/어야 해요. A new construction shows a rule card once.
• A quest log instead of a single tracker: the HUD lists up to four quests with their Korean objective, their conditions and a live count (three regular slots and one for the place you are in). The game fills the slots for you and picks the next quest when you finish one; tick quests in the journal to choose yourself, or switch “Pick quests automatically” off. Only tracked quests advance.
• Windows that wait for you. Hints, rule cards and banners stay until you press the hint key (H), one window per press, and closing one is never a hint.
• A hint that teaches. H restates the task in level-1 Korean and explains the blocking word, then starts a two-question sidequest on it. The original quest waits until you have answered both.
• A journal (K) drawn as a worn notebook: your dictionary, due words, achievements, a quest tree that shows what matters now, a grammar book, stories and the settings.
• Real spaced repetition (FSRS-6), with four-option cards, recall, syllable tiles and typed answers on a built-in Korean keyboard for words you know well.
• Vocabulary from three places: about 1,300 concepts (hand-written ones and one generated entry per rarer object), the game’s own Korean names, and your own words imported from Lute.
• Four interface languages: English, German, Spanish and French. The quest itself is always Korean.
• Checked Korean. Every Korean line passes a linter, and a part of it has been read by two AI reviewers. No line has been approved by a native speaker yet; you can help.
• Content as data. Questlines are JSON files, re-read every two seconds, so you can write your own without touching Java or restarting the game.

How to read this guide

A quest, in one sentence

“Place a campfire on the beach.” — the place is part of the sentence, the mod checks the block and the biome, and the tracker answers “why not yet?” with the live status underneath. That is the whole design: the Korean is the interface.

Status

Version 3.0.0 (release candidates until it is final), for Minecraft 26.3 with Fabric Loader 0.19.5+ and Fabric API 0.162.0+26.3 on Java 25. The interface follows your game language (English, German, Spanish, French); the quest text is Korean, with an optional line in your language. See Compatibility for what is deliberately out of scope.

Installing

What you need

Hangul Quest is a client mod. Install it in your own mods folder, never on a server; it never sends a packet, so a server without it behaves exactly the same.

Before you start: reading Hangul

Hangul Quest assumes you can already read Hangul, the Korean alphabet. It teaches words and grammar, not the alphabet. Most people learn Hangul in a few hours. The first time you join a world a short welcome screen asks whether you can read 고양이가 나무 위에 있어요.; if you cannot yet, it lists free lessons. You can skip it, ask to be reminded once, or switch it off for good, and it never blocks a quest. Open it again any time from the journal’s Info tab (About reading Hangul).

Free ways to learn Hangul:

• How to Study Korean, Unit 0: Learn How to Read Hangul (English)
• KoreanClass101: Learn the Korean Alphabet (Hangul) (English; the lessons are readable without an account, the PDF chart needs a free one)
• Ryan Estrada: Learn to Read Korean in 15 Minutes (English, a short comic)
• Koreanischkurs: Einführung in Hangeul (Deutsch)

Steps

1. Install Fabric. Run the Fabric installer for Minecraft 26.3 and start the game once with the new profile so the folder exists.
2. Download the mod. Take hangulquest-<version>.jar from the releases page. Release candidates (3.0.0-rc.N) are marked as pre-releases and do not show up under “latest”.
3. Download Fabric API for 26.3 from Modrinth or CurseForge.
4. Copy both jars into your mods folder:
   • Windows: %appdata%\.minecraft\mods
   • Linux: ~/.minecraft/mods (or ~/.var/app/com.mojang.Minecraft/.minecraft/mods for the Flatpak)
   • macOS: ~/Library/Application Support/minecraft/mods
5. Start Minecraft with the Fabric profile and enter any world. The first questline starts by itself; K opens the journal, H shows a hint.

Checking the download

Each release page carries a SHA256SUMS file with the hash of every asset:

sha256sum -c SHA256SUMS
# hangulquest-<version>.jar: OK

First five minutes

• The quest log sits in the top-left corner. The game picks up to four quests for you (three regular ones and one that follows where you are); each shows one Korean sentence, a progress bar where the goal counts something, and a status line that says what is still missing (지금 낮 · 밤 필요 — “it is day now, night is needed”). V moves the highlight; H helps with the highlighted quest.
• Press H whenever a word is unknown. You get the same task in easier Korean, an explanation of the word, and a two-question sidequest. Finishing it brings the quest back. When a window is open (a hint, a rule card, a banner), H closes it first; windows stay until you do.
• Press K for the journal. The Quests tab shows the whole tree: what you finished, what is open and what the locked branches are waiting for.
• The interface follows your Minecraft language (English, German, Spanish or French; anything else gets English); Settings → Language switches it explicitly.
• If you want a translation line under each quest, switch on Translations in quests in the same tab. It is off by default: the quest itself is always Korean, so the Korean is what you learn to read.

Updating

Replace the jar in mods with the new one. Progress lives in config/hangulquest/ and survives an update; the mod backs the file up before it migrates a format. If a new version needs a newer Minecraft or Fabric API, the release notes say so.

From 2.x to 3.0: progress is converted when you first start the game. It now lives per Minecraft account in config/hangulquest/profiles/<account>/; your old progress.json is copied there and never changed or deleted. To roll back, put the 2.1.0 jar back and delete config/hangulquest/config.json; the CHANGELOG has the full notes. Copy the config/hangulquest/ folder before updating if you want to be sure.

Uninstalling

Delete the jar. Your progress, settings and imported vocabulary stay in config/hangulquest/ — delete that folder too if you want a clean slate. Nothing was ever written outside it.

Compatibility

• Minecraft 26.3 only. The mod is built against named 26.3 classes; it will not load on 1.21.x or on a future 26.4 without changes.
• Client-side. It works on servers that do not have the mod, in single-player and in LAN worlds. Other players see nothing.
• Other client mods. It draws its own HUD and journal and does not replace vanilla screens, so it coexists with HUD mods; if two trackers overlap, move the quest tracker to another corner in the journal’s options.
• Languages. English, German, Spanish and French interfaces; a text a language lacks is shown in English. Spanish and French cover only part of the quest text so far.
• Voices. Pronunciation audio is an optional separate resource pack (“Hangul Quest Voices”); without it the mod is silent.
• Not in scope: romanisation (Hangul is a prerequisite), speech recognition, and anything that would need the server’s cooperation.

Playing

The quest log

When quests are tracked, the top-left corner shows a quest log: no panel, just shadowed text on the world, two short lines per quest.

Each quest reads:

Counts are inline (1/3) instead of a bar, and there is no background box, so the log stays small even with several quests open.

The status line is generated from the goal, so it always answers the question the sentence raises:

Every condition of a step is spoken inside the sentence itself — 해변에서 모닥불을 놓아요., not just 모닥불을 놓아요. — so the text and the check can never disagree.

What is in the log

The game keeps the log filled for you. It holds up to four quests: three regular ones that fit the start of the game (wood, stone, food) and a fourth, situational slot that follows where you are (a snow trail in the snow, a cave trail underground). When you finish one, the next one follows. A message says when the game has picked quests for you.

You can still curate it. In the journal’s Quests tab, select a trail and tick In log in its detail card: the quest appears in the HUD and starts advancing.

• Quests you tick yourself are never replaced by the game. A quest you take out stays out for 30 minutes of play.
• Only tracked quests advance. An untracked quest keeps its saved step, counter and hints, but nothing about it is checked against the world, so a quest can never complete behind your back while you work on a different one.
• V moves the highlight. The list keeps its order, only the gold title moves, so V walks through every tracked quest and wraps around. Hints (H), the sidequest and the follow-up chain work on the highlighted quest only.
• Finishing the highlighted quest starts or offers its successor. Finishing any other tracked quest shows a banner and leaves the highlight alone.
• Settings → Pick quests automatically switches the game’s choice off; then the log holds only what you tick.

The detail card also has a Focus button for a quest that is in the log but not highlighted.

How many rows the HUD draws is questTrackerRows in config/hangulquest/config.json (1 to 6, default 4).

Windows stay until you close them

Hints, rule cards, culture notes, word cards, banners, the quiz prompt, the next-quest popup and the completion cards no longer disappear on a timer. Each shows its key ([H] 닫기 · close); one press of H closes exactly one window, the top one. If more are waiting, a “+N” badge says how many. Closing a window is never a hint: the press does not mark the step as helped, start a sidequest or change the grading. No window covers the crosshair or the hotbar. If you prefer the old behaviour, switch Settings → Auto-close windows on.

A step

1. Read the sentence.
2. Do it. The mod watches the world locally: blocks you break or place, items you gain or eat, what you look at long enough, the biome, dimension and altitude you are in, right-clicks and interactions.
3. When the check passes, a card appears with the next clue and that quest’s row moves on.

Nothing is ever sent to the server, and nothing can be “cheated” in a way that matters: the mod trusts your client because the only person you could cheat is yourself.

After a step: the finale

Every trail ends with a ritual finale: the same goal-and-condition rules, but always something you can do in any world — light a torch on a mountain at night, ring a bell at dawn, place a campfire on a beach. That is deliberate. No trail ever asks for a structure, a chest, a coordinate or a rare biome, so no trail can be unfinishable because of world generation.

Finishing the finale gives the big card: the trail’s Korean title, the closing line, the translation line if you enabled it, the badge, a fanfare, a level-up sound and fireworks. The badge stays in the journal.

What happens next

• If exactly one follow-up trail is unlocked, it starts by itself.
• If several are, a card offers up to five of them. Press 1–5; if you do nothing, the first one starts after 60 seconds.
• If the next trail is still locked (it wants another parent, or more known words), the mod starts the missing prerequisite instead, so you are never left without a quest.
• Abandoning is allowed and costs nothing. The trail is paused where you left it — step, partial counter, hint state and sidequest — and resumes exactly there when you come back. Progress in the journal shows as 2/4.

The HUD

The vanilla HUD stays as it is. Hangul Quest adds three non-modal elements:

• the quest log (top-left by default),
• the word card when you look at a block or mob that is in your vocabulary,
• windows and celebration cards (hints, rule cards, banners, the quiz prompt), which never capture input.

All of them can be moved or switched off in the journal’s options; F8 hides the quest HUD entirely while you build.

Keys

Playing in a group

The mod is per-player and invisible to everyone else. On a server, each player can run it independently; there is no shared state and no server-side component. If you play with someone who also uses it, you will simply each have your own quest log.

A sensible first session

Do the first branch for ten minutes with the hint key, then turn the hint off for one trail and see how far you get. The vocabulary you keep meeting — stone, wood, torch, bread — is the vocabulary the early tree is built from, and it reappears in later trails on purpose.

Hints and sidequests

The hint is the heart of the mod. It is not a translation: it is the same task said in easier Korean, plus one sentence about the word that is blocking you. And it does not let you continue until you have spent thirty seconds with that word.

H works on the highlighted quest in the log — press V until the quest you want help with is the gold one, then ask.

What H gives you

1. The same goal, at level 1. A late trail might say 돌을 세 개 캐야 해요. — pressing H gives 돌을 캐요. 세 개요. The counters stay, the conditions stay spoken, the grammar drops to the politest form. Hints never leave level 1.
2. The blocking word explained, in Korean. 돌 = 땅에서 나와요. 단단해요. — “comes out of the ground, is hard”. Written with tier-1 vocabulary on purpose, and validated as Hangul-only.
3. A sidequest. Two questions about that word:
   • Korean word + icon → pick the meaning in your language,
   • the meaning + icon → pick the Korean word.

The sidequest

• The original step is frozen while the sidequest runs. You cannot accidentally finish a quest you did not understand.
• A wrong answer does not punish you. It shows the word card, reduces the choices to two and lets you try again.
• Practice — sidequests and ambient word cards — is exposure, not an exam: it never counts against a word’s schedule, so guessing costs nothing.
• Both questions answered and the original step returns with a short Korean confirmation and a 사이드 퀘스트 완료! card.

When you already know the word

The sidequest is skipped and you just get the hint, if the word is:

• mastered in the mod, or
• marked known in Lute (status 99).

You asked for a hint, not a lesson — the mod respects that.

Closing a hint

A hint is a window, and windows stay until you close them. The first press of H shows the hint; once it is open, the next press of H only closes it. That press is not a hint request and changes nothing about the step. If several windows are waiting, each press closes one and a “+N” badge counts the rest.

One hint per step

hintUsed is stored per step. Pressing H again re-shows the hint instead of starting a second sidequest, and it survives a restart. Abandoning a trail clears it, because the trail starts over.

The no-spoiler rule

Quizzes and sidequests never show the item icon before you answer. They draw a neutral ? tile, and the icon only appears on the result card. The ambient word card — the one that appears when you look at something — does show icons, because that card is teaching, not testing.

This matters more than it sounds: with the icon visible, 돌 in a multiple-choice list is a picture puzzle, not a reading exercise.

Translations in quests

By default the quest text is Korean only: tracker, step cards, sidequest, finale. The journal’s Settings tab has Translations in quests, which adds one line under each Korean one in the interface language (English, German, Spanish or French). Turn it on for the first week, then off; the point is to stop needing it.

The danger of overuse: if you leave the translation line on, your eyes will read it first. The mod cannot stop you, but the hint key is the intended crutch, and it is a slower one.

Reading the hint like a teacher

• Try the quest sentence for ten seconds before pressing H. Even a wrong guess primes the word.
• If the hint’s explanation itself contains a word you do not know, look it up in the journal’s dictionary — descriptions are written with early-tree vocabulary, so this should be rare.
• After the sidequest, say the word out loud once. The mod cannot hear you; your brain can.

Next: the journal is where all of this is recorded.

The journal

K opens the journal. It is not a vanilla screen with a book texture: the mod draws a leather cover, a sewn spine, a ribbon, a cream page with ruled lines and a flat ink font, so Hangul stays crisp at small GUI scales.

Eight tabs, switched with the row at the top:

Info

The dashboard. Counters are deliberately plain: discovered (met at least once), mastered (recalled on three study days, with a stable card), due (now), the streak with your best streak, today’s reviews and the number of correct answers. Review starts a review, Open quests jumps to the tree. About reading Hangul reopens the welcome screen.

Words

A full-text list of the vocabulary the mod knows: Korean word, meaning, status, and where the word came from:

• curated: a concept from concepts.json, with a hand-written easy-Korean description,
• vanilla: an item, block, entity or biome name taken from the game’s language files,
• lute: imported from your Lute export.

The mouse wheel scrolls, the search field filters by Korean or by meaning. Words you have not met yet are not shown, so the list is a record of your own journey rather than a dictionary dump.

Study

Due words, one card at a time. The kind of card depends on the word: a four-option choice, a recall you grade yourself, syllable tiles, and for words that are already stable a typed answer on a built-in 두벌식 keyboard (Settings → Typed cards turns that off). Answer honestly: the schedule is FSRS-6, and a wrong answer brings the word back soon.

The review trail (복습의 길) is the same words as a quest: it is generated from today’s due words and changes daily. Use it when a card session feels too abstract.

Achievements

Fifteen achievements across vocabulary, mastery, reviews, streak, animals, blocks, questlines and sidequests. They unlock silently when their condition is met. They are a nudge, not a gate: nothing in the mod requires them.

Grammar and Books

Grammar lists the constructions you have met, one rule card each. Books holds four short stories (they open when you know 98% of their words; a locked one lists the words to learn first; hover a word for its gloss) and the culture notes (온돌, 한옥, 김치, 설날 and more) that also appear once as a card when you first craft or find the matching item.

Quests

The tree. Each node is one trail, coloured by state. It shows only what is useful now: the trails you can start, the ones in your quest log, and, greyed out, the ones waiting directly behind them. Everything further away is hidden, and finished trails are folded into a “완료 · Completed” button. Tick “Show all trails” (here or in Settings) for the whole map.

• done — finished, badge earned,
• active — one of the trails in your quest log (up to four: three regular slots and one situational; the game fills them and picks the next one when you finish, unless you switch the setting off),
• open — unlocked but not started,
• locked (greyed) — shows what it is waiting for (for example “after 돌의 길”, or a number of known words).

The game keeps the quest log filled: three regular quests that fit the start of the game (wood, stone, food) and, when you finish one, the next one right after it. A fourth slot follows where you are: a snow trail in the snow, a cave trail underground. Quests you tick yourself are never replaced; take one out and it stays out for 30 minutes of play. Switch “Pick quests automatically” off in Settings to choose everything yourself.

Selecting a node shows the detail card: Korean title, level, TOPIK band, state, parents, children, progress (2/4), the live status of the current step, a checkbox and a start button.

• In log (checkbox) is the important one: ticked quests are drawn on the HUD and their goals are checked against the world. Unticked quests keep their progress but are paused.
• Start ticks the quest and starts it; Focus highlights a quest that is already in the log.
• State reads ▶ active for the highlighted quest, ▸ in log for the other ticked ones, ○ open for a quest that is unlocked but not in the log, and · locked for a locked branch.

Parent trails are listed before their children, and the list scrolls.

Settings

Underneath, the tab reports what the Lute import did (12 words imported, 3 skipped). The corners, card duration and quiz interval are in config/hangulquest/config.json; see Files and backups.

Villagers

Villagers are the people of your village: they have a personality, a name and a voice, and they remember you.

Talking to a villager

Sneak and right-click a villager (or a wandering trader) with an empty main hand. A plain right-click still trades.

The first conversation is always an introduction: the villager says their name and something about the place. From then on they pick a conversation that fits who they are (their personality), where they live (the region of the village), their job and how well they know you, and never one above your learner level.

A conversation is a short Korean exchange with two to four answers to pick from; some lines come back as questions you answer, so you read and speak. New words are glossed when you hover them, and the lines are counted as exposure for your vocabulary.

Personality

Every villager has one of eight personalities, fixed the moment you meet them, and the personality decides how they speak:

Snooty is the formal register you will hear in a shop or a hotel: perfect for practising -습니다 and -ㅂ니까. Children speak 반말 to you; they keep their personality when they grow up, and then speak like an adult.

Region

The village’s type decides what a villager notices: plains (wheat, bells, bees), desert (heat, sand, water), savanna (dry grass, horses, no rain), snow (cold, ice, soup), taiga (spruce, sweet berries, foxes), jungle (cocoa, bamboo, parrots), swamp (mud, frogs, mushrooms). The Korean you meet is the Korean around you.

Friendship

• A heart for the first talk of each in-game day.
• Two hearts for finishing a request.
• Ten at most. At three, six and ten hearts the villager has something new to say.
• At level 4 or more, a lazy, sporty, peppy or big-sister villager at six hearts may ask whether the two of you should speak 반말; say yes and their later lines come in 반말. Refusing is fine and changes nothing else.

Requests

Requests are small jobs villagers ask for; they are not part of the quest tree.

• An accepted request appears in your quest log with the villager’s name; it only advances while it is tracked there, like any other quest.
• Up to three at a time and one per villager. If the quest log is full, a request you accepted waits untracked in the journal instead of pushing out a quest you chose yourself.
• Refusing costs nothing. You can abandon a request in the journal.
• The reward is two hearts and the words the request practises.

The Villagers page

The journal’s Villagers (주민) tab lists everyone you met, in the order you met them: name, personality, region, profession, hearts, and the open request with track, untrack and abandon. It never reorders itself.

Voices

With the optional Hangul Quest Voices resource pack every line is spoken in the villager’s own voice: eight adult voices, one per personality, and two children’s voices. A villager’s voice never changes. The line plays when it appears; R or the play mark repeats it. The pack is a resource pack, so enable it in Options → Resource Packs.

Vocabulary

Every Korean word the mod can teach comes from one of three places, and all three end up in the same catalog the quest engine draws from.

1. Curated concepts

src/main/resources/assets/hangulquest/data/concepts.json holds about 1,300 concept entries: hand-written ones (blocks, tools, food, animals, biomes, verbs, everyday words) and one generated entry per rarer object. Each one looks like this:

{
  "id": "stone",
  "ko": "돌",
  "category": "BLOCKS",
  "tier": 1,
  "items": ["minecraft:stone"],
  "sentenceKo": "돌을 캐요.",
  "descKo": "땅에서 나와요. 단단해요.",
  "aliases": ["돌"]
}

Curated concepts are the only words with a hand-written description, and they are what the early tree is built from.

2. Vanilla names

The game already ships Korean and German names for every item, block, entity and biome. names.json is generated from those language files with tools/extract_names.py — names only, no assets. It gives the mod thousands of words it can use in quests without a human writing them down.

3. Your Lute vocabulary

If you already learn Korean with Lute, export your terms and drop the file at:

config/hangulquest/vocab/lute-vocab.csv

The format is Lute’s Anki-ready export — five semicolon-separated fields, quoted fields allowed:

term;translation;pronunciation;status;tags
돌;Stein;dol;99;
나무;Baum;namu;4;nature

Rules:

• The file is read-only. The mod never writes to it, never moves it and never talks to Lute.
• Status is re-read at start-up; if you change your status in Lute, export again and restart.
• Words that match a curated concept reuse it, so 돌 does not appear twice.
• Unmapped words get the lute: prefix in the progress file and appear in the dictionary as normal.
• The import is off if the file is missing or if luteImport is disabled in the config.

How words become quests

A step declares the words it teaches: "teach": ["stone", "torch"]. The trail itself lists its concepts, which is what the journal shows under it. A trail unlocks when you have discovered minWordsKnown words — discovered, not mastered, deliberately: a vocabulary gate that requires mastery would stall a player who is happy with reading.

The engine will not accept a step whose goal mentions an object that no taught concept covers. That is what keeps the quest text and the check in sync.

Adding words

1. Add the concept to concepts.json with a Hangul-only descKo.
2. Use it in a questline’s teach and concepts.
3. Run ./gradlew test — the content test checks that every taught concept exists and that every Korean word is Hangul-only.

Next: Review, streak and achievements explains what happens to a word after you have met it.

Review, streak and achievements

A word you met once is not a word you know. Hangul Quest keeps a schedule for every word and quietly turns the words you are about to forget back into cards and quests.

The schedule

Reviews use FSRS-6, an open spaced-repetition algorithm. Every word has a card with a stability (how many days until you are likely to forget it) and a difficulty. When you answer, the card is updated and the next due time is set so that you still remember the word with the probability you chose under Settings → Desired retention (88% by default, between 80% and 95%).

• A four-option answer is graded Good, Hard when it was slow, or Again when it was wrong. Two- and three-option questions, exposures, hints and probes never move the schedule, so guessing costs nothing.
• A step that teaches a due word and is done without help counts as Good; after a hint it counts as Hard.
• A wrong answer comes back within the same session.
• A word is mastered when you recalled it on three different study days and its stability reached 21 days.
• Words from an older version keep their old level for display; their new card starts from it, so an update does not make everything due at once.

What counts as a review

1. Cards in the journal’s Study tab, and the J key: four options, a recall you grade yourself, syllable tiles, and typing for stable words.
2. Quest steps: finishing a step that teaches a word counts as a review of it.
3. The review trail (below), which is the same review in quest form.

Settings → New words per day (5, 10 or 15) limits how many new words a session adds, and a session adds only one new word per group of related words.

The review trail

Once a day the mod builds a trail called 복습의 길, the path of review, out of the words that are due and that map to something you can do in the world. It is seeded by world name and date, so it is the same trail all day and changes tomorrow (the study day turns over at 04:00). It sits outside the main tree and is always available.

Streak

The streak counts days on which you did at least one review or finished a step. The goal is four days a week, and two freezes a month are applied automatically. The Info tab shows the current and the best streak. Opening the journal does not make a day.

Achievements

Fifteen, all unlocked quietly:

The Achievements tab lists them with progress; unlocked ones are stamped with the date.

Why the mod is quiet about numbers

There is no XP bar for Korean, no daily goal you can fail and no notification asking you to come back. The counters exist because they help you see progress, not because the mod wants a habit loop. If you prefer it even quieter, switch off Auto quiz and the HUD cards in the settings and use only K and H.

The review log

Every answer is also appended to a local file, reviews.ndjson, in your profile folder (rotated monthly). It lets the mod rebuild the card states and nothing else. It never leaves your machine; the optional research export is a zip you create yourself and send yourself.

Next: Files and backups, what all of this is stored in.

Files and backups

Everything Hangul Quest knows lives in one folder in your instance:

config/hangulquest/
├── config.json              settings (mirrors the journal's options)
├── progress.json            the file of 2.x, kept untouched as a copy and a way back
├── profiles/
│   └── <account-id>/        one folder per Minecraft account
│       ├── progress.json    words, review cards, streak, achievements, trail state
│       ├── reviews.ndjson   the review log
│       └── backups/         a daily and a weekly copy of progress.json
├── questlines/              one JSON per trail, hot-reloaded
│   ├── _template.json       starting point for your own trail
│   └── … 422 shipped trails
└── vocab/
    └── lute-vocab.csv       your Lute export (optional, read-only)

On a default installation that is .minecraft/config/hangulquest/; with the Flatpak build it is ~/.var/app/com.mojang.Minecraft/.minecraft/config/hangulquest/.

progress.json

Each Minecraft account has its own profiles/<account-id>/progress.json (the schema is version 4). The first time a profile opens, the progress.json of an older version is copied into it and the old file is left alone, so the 2.x file stays a way back. The file holds, in plain JSON:

• every word you have met, its review card (stability, difficulty, due time) and its old level,
• which day keys count for the streak, and your best streak,
• unlocked achievements with their dates,
• the focused trail, its step, partial counters, sidequest state and hints used,
• the quest log (quests.tracked) and every other trail you started (quests.saved), all with their progress, plus completed trails with their badges,
• the last Lute import summary.

It is written atomically (a temporary file is renamed over the old one) and debounced, so a crash mid-write cannot leave a half file.

Two safety nets:

• A format migration copies the old file first: progress.v<N>-backup-<stamp>.json, where N is the version it was written in. Daily and weekly copies are kept in backups/.
• An unreadable file is renamed to progress.json.broken-<stamp> instead of being overwritten, and the mod starts fresh. The broken file is still there if you want to salvage it by hand.

The Reset progress button in the journal’s settings writes progress.json.backup-pre-reset-<stamp> before it wipes anything.

Making your own copy

Progress is not synced between machines; copy the folder yourself if you want to move a journey.

# Linux / macOS — back up before a mod update
cp -r ~/.minecraft/config/hangulquest ~/hangulquest-backup

On Windows the folder is %appdata%\.minecraft\config\hangulquest.

config.json

The full set of settings, with the defaults that matter:

Edit it with the game closed; the journal’s Settings tab writes the same file.

The questline folder

questlines/ is created on first start and filled with every shipped trail, so you can copy one, change it and reload without restarting. See the authoring guide for the format and the hot-reload rules.

What is not written

No log of chat, no player names, no server addresses, no timestamps beyond the day keys that the streak needs. Nothing leaves the machine.

Next: Troubleshooting.

Troubleshooting

The mod does not load

• Is the jar in the right mods folder for the profile you started? Flatpak uses ~/.var/app/com.mojang.Minecraft/.minecraft/mods.
• Does the Fabric profile really run 26.3? Check the version in the launcher’s installation list.
• Is Fabric API present and for 26.3? Without it the entrypoint fails at start-up.
• JDK 25 or newer? The launcher’s log says which Java it used.
• Look at logs/latest.log for hangulquest lines. A missing dependency is reported there first.

No quests appear

• Press K → Settings → is Quests on?
• The first trail starts when you enter a world; if you abandoned everything, the Quests tab lists open roots. Pick one.
• If you are on a server with a very restrictive client mod policy, no quest can finish, because the mod needs the client-side block events. It never asks the server for permission; it just cannot see what the server hides.

A quest step does not complete

The quest log’s status line is the diagnosis: it names the missing condition (지금 낮 · 밤 필요), the counter (1/3) or the dwell percentage. Common causes:

• Counters reset when the step starts. Items you already carry do not count for ACQUIRE_ITEM unless you picked them up after the step began.
• Look goals need you to keep the crosshair on the block or mob; walking away resets the dwell.
• REACH_BIOME with a tag needs the biome family, not a specific biome.
• Time conditions use the world clock: night is night, even underground.

A quest does not advance

Check the journal’s Quests tab: only quests with the In log checkbox ticked are checked against the world. A quest that is listed as ▸ in log but not highlighted still advances; ○ open does not, on purpose: that is how the mod keeps you from completing quests you are not reading. The game also takes quests out of the log when you finish them and may fill the slots again; switch Pick quests automatically off in the settings to choose everything yourself.

My own questline does not show up

• The file must end in .json, must not start with _, and must be inside config/hangulquest/questlines/.
• The id must be unique. To replace a shipped trail you need "override": true; a duplicate id without it is ignored on purpose.
• Broken files are logged and skipped. Check latest.log for [hangulquest] parse warnings — they name the file and the field.
• The journal re-reads the folder every two seconds, so a valid file appears without a restart.

Korean shows as boxes or is unreadable

The mod ships its own font subset. If it fails to load, the log says so and the game falls back to the vanilla Unicode font, which renders Hangul at 6 pixels. Reinstall the jar, and if it persists, report the log line — it names the resource path.

The quiz answers feel random

The quiz picks distractors from words you have already met, so with a small vocabulary the choices look similar. It gets easier as the dictionary grows. You can also turn Auto-Quiz off and practise only in the journal and the sidequests.

A window stays on the screen

That is on purpose: hints, rule cards, banners and the quiz prompt wait until you close them. Press H (or your hint key) once per window; a “+N” badge says how many are waiting. If you would rather have them close by themselves, switch on Auto-close windows in the settings.

Some text is in English although I chose another language

Spanish and French cover the interface completely but only part of the quest text so far, and a text a language lacks is shown in English. You can help: see Contributing.

Progress disappeared after an update

Look in config/hangulquest/profiles/<account-id>/ for progress.v*-backup-*.json (migration), progress.json.broken-* (unreadable file) and backups/ (daily and weekly copies). Rename the backup to progress.json with the game closed to restore it. The progress.json of 2.x in config/hangulquest/ is never changed by 3.0 either. See Files and backups.

I want to start over

Settings → Reset progress, twice. It writes a backup first. For a complete reset, delete config/hangulquest/.

Something else

Open a bug report with the versions, the questline id and the log excerpt. If it is reproducible, say what you did twice — once is often luck.

Privacy

Hangul Quest is built so that the question “what does it send?” has a short answer: nothing.

No network

• No telemetry, no analytics, no crash reporting, no update check.
• No sockets are opened, no HTTP client exists in the jar. You can run it with the network cable pulled.
• Quests are verified from the client’s own view of the world. Nothing is requested from the server and nothing is reported to it.

Links

The welcome screen and the journal’s About reading Hangul page list a few external Hangul lessons. A link opens in your browser only when you click it and confirm Minecraft’s own “open this link?” screen. The mod itself never contacts those sites.

What is stored locally

That is all. There is no account, no identifier, no machine fingerprint.

The review log

The scheduler needs to know what you answered and when, so the mod keeps a log next to your progress. It is a plain text file you can open, copy or delete. Each month’s lines are packed into reviews-YYYY-MM.ndjson.gz in the same folder. The log stays on your computer: nothing in the mod reads it to send it anywhere, and it holds no name, no chat and no coordinates. If progress.json is ever lost, the log can rebuild the review schedule. Deleting it only costs you that safety net and your own history.

Research export

Hangul Quest can help find out what actually makes Korean stick, but only if you choose to take part. Nothing happens by itself. Everything below stays on your computer unless you share a file by hand.

• Held-out probes. About one in twenty words that you know well enough to be asked less often is set aside: it gets no reviews for a while. After 7 and 30 days it is asked once as a plain four-option question, and the answer is written to the review log. This tells us what you remember when nothing helps you. Which words are set aside is worked out from your install’s random key, so it is the same every time.
• Word experiments. Some settings are compared word by word: half of the words use one review setting and half another (for example a desired retention of 85% or 90%). Which setting a word has is worked out from the same random key. The review log notes it in its arm field. If you change the retention yourself in the journal settings, your choice wins.
• Vocabulary check. The journal’s first page has an optional 3-minute Yes/No vocabulary check. It is never required. Words you say you know are scheduled for a quick check in a few days.
• Export research data. The journal settings have a button that writes config/hangulquest/hangulquest-research-<date>.zip. It contains your review log with every word id replaced by a hash made with a random key that is created for that export and then thrown away (so the ids cannot be turned back into words and two exports cannot be matched), and a consent.txt in English and German that says what is inside. There are no player, account, world, server or chat names, no coordinates, no settings and no quest names. The times in it are real. The mod never sends the file; if you want to take part, attach it yourself where the project asks for it. If you do not, delete it.

Logs

The mod logs with the [hangulquest] prefix: which trail started, which file was reloaded, which questline failed to parse. It does not log chat, player names, server addresses or coordinates. If you attach a log to an issue, check it anyway — Minecraft’s own log lines around it do contain your instance path.

Screenshots

The screenshots in this repository and in the guide were taken in a clean test world. If you post a screenshot of a quest and would rather not show your coordinates or your server’s chat, crop them; the mod’s own UI never draws either.

Lute

The import reads a file you exported and does not talk to Lute or to any server. If you disable Lute-Import in the journal, nothing is read at all.

Changes

This page describes 3.0.0. If a future version ever needs the network for anything, it will be opt-in, documented here and in the changelog before it ships.

Authoring guide

Everything below is the canonical guide from the repository, included here so the guide stays a single source of truth.

Questlines — format and workflow

A questline is a small Schnitzeljagd: several clues that build on each other, then a ritual at the end. All of it lives in one JSON file under src/main/resources/assets/hangulquest/data/questlines/.

Before you write one, read the attribute reference. It is mandatory: it lists what every trail must have, and the tests enforce the mechanical half of it.

Quick start

python3 tools/new_questline.py steinpfad2 --words stone,cobblestone --tier 1 \
  --title-ko "돌의 두 번째 길" --title-de "Der zweite Steinpfad"
./gradlew test

The script writes the file and moves its English and German text into the lang files (see below). The mod finds questline files by listing the folder, so there is no index to maintain.

Where the English and German text lives

A shipped questline file holds the Korean text and the structure, and nothing else. The English and German text (titles, clues, hints, the finale line) is in two flat files, one per language, so that a translator, Weblate or Crowdin only ever touches one file:

src/main/resources/assets/hangulquest/lang/content/en_us.json   English, the reference
src/main/resources/assets/hangulquest/lang/content/de_de.json   German

The keys are built from the ids in the questline file:

The finale step is the step id finale: hangulquest.trail.<id>.step.finale.clue. A language file may lack any key; the game then shows the English text, never another language. English is complete (ContentTextTest fails otherwise), German is reported and may have gaps. Arguments, if a text ever needs one, are %s and must match English. A new language is a new lang/content/<code>.json next to the interface file lang/<code>.json.

Adding or changing text. Write English and German inline in the trail file while you work, then run

python3 tools/i18n/extract_content.py

It moves every inline titleEn/titleDe, clue.en/de, hint.en/de, finale.textEn/textDe and every concept gloss into the lang files and removes the fields from the JSON (nothing else in the file changes). python3 tools/i18n/extract_content.py --check fails while shipped files still carry inline text; CI runs it. To change an existing line, edit the lang file directly.

Files of your own. Questline files in config/hangulquest/questlines/ and in resource packs may keep using the inline fields, and they should: they have no lang file. An inline field always wins over a key. A field with inline text (say clue.en) hides the keys for that field in every language, so a rewritten English clue is never shown next to the shipped German one; add clue.de as well to translate it. Without any inline text for a title, clue or hint the key of the same trail and step id is used, which is what a copy of a shipped file wants.

The external folder (no restart)

Trails also live as individual JSON files in config/hangulquest/questlines/, copied out of the jar on first start. The mod re-reads that folder every two seconds:

• a new id appears in the journal immediately,
• a changed file replaces the loaded trail,
• the same id as a shipped trail is ignored unless the file sets "override": true,
• a broken file is logged and skipped, and the shipped version stays active.

The template is _template.json.

Conditions are spoken in the sentence

conditions always end up in the Korean text: TIME (밤에/낮에/새벽에/저녁에), WEATHER, Y_RANGE („땅 아래에서“, „120블록보다 높은 곳에서“; before a place of the goal’s own it modifies it: „높이 90블록 위 침대에서“, from level 3 „…위의 침대에서“), IN_BIOME („해변에서“), IN_DIMENSION („지옥에서“, „엔더에서“), NEAR_ENTITY/NEAR_BLOCK („좀비 근처에서“; NEAR_ENTITY takes an optional count, „주민 두 명 근처에서“, „소 세 마리 근처에서“ with 명 for people and 마리 for animals; NEAR_BLOCK is a proximity check, a block of that kind within the radius, not the block in the crosshair), SKY („밖에서“ on levels 1 to 4, „하늘이 보이는 곳에서“ from level 5; ROOFED says „지붕 아래에서“ of the player, but with a PLACE_BLOCK goal it checks the roof over the placed block and says „지붕 아래에 통을 놓아요“). A step without an authored clue uses the generated sentence, which speaks every condition. An authored clue wins also on a step with conditions: it is shown as written, and a condition phrase it does not contain is put in front of it, so no condition can be missing from the text. A clue that says the condition in its own words does not get the phrase again: 밤에 / 한밤에 / 밤이 for TIME night, 비가 for rain, 물속 for IN_WATER (a forms list per condition, kept to words that cannot mean anything else: 밤 alone is also a chestnut). FACING (direction) says „북쪽을 보고“ in front of the action; it is true while the yaw of the player is within 45 degrees of the direction. Heights and distances in blocks are spelled in Sino-Korean from level 2 („높이 백 블록 위로“, „물에서 이십 블록 수영하세요“; digits only above 100 unless round hundreds); counts with a native counter go up to 99 („스물네 개“). AVOID may forbid an action on a creature („주민을 물리치지 마세요“). REACH_HEIGHT below the ground uses „내려가다“ (descend) instead of climbing.

Anatomy of a file

{
  "schema": 1,
  "id": "steinpfad",
  "titleKo": "돌의 길",
  "topic": "돌",
  "tier": 1,
  "order": 10,
  "koreanLevel": 1,
  "concepts": ["stone", "cobblestone", "coal", "torch"],
  "requires": { "minWordsKnown": 0, "dimension": "minecraft:overworld",
                "completed": ["holzpfad"] },
  "steps": [
    {
      "id": "s1",
      "teach": ["stone"],
      "goal": { "type": "BREAK_BLOCK", "block": "minecraft:stone", "count": 3 },
      "conditions": [],
      "clue": { "ko": "단단하고 회색인 것을 세 개 캐요." },
      "hint": { "ko": "돌을 캐요. 세 개요." }
    }
  ],
  "finale": {
    "step": {
      "id": "finale",
      "teach": ["torch"],
      "goal": { "type": "PLACE_BLOCK", "block": "minecraft:torch", "count": 1 },
      "conditions": [{ "type": "TIME", "phase": "NIGHT" }]
    },
    "textKo": "어두운 곳에서 빛을 만들었어요."
  },
  "reward": { "badge": "steinpfad", "words": ["stone", "torch"] }
}

This is the shipped shape. The matching lang entries are hangulquest.trail.steinpfad.title, ...step.s1.clue, ...step.s1.hint and ...finale. A file of your own adds the translations inline: "titleEn", "titleDe", "clue": { "ko": …, "en": …, "de": … }, the same for hint, and "textEn" and "textDe" next to textKo in the finale.

• clue and hint are optional. Without them the Korean sentence is generated from the goal, with correct particles, counters and time prefixes. Authored sentences are for riddle flavour. Their English and German translations are lang keys (or inline fields in a file of your own).
• grammar is optional: the constructions of grammar.json (or their ladder aliases) the trail is meant to practise, ["L2.seyo", "L2.eseo_activity"]. The loader checks every id and drops the unknown ones with a problem; the list is dumped into steps.json.
• teach names the words the step introduces; they must exist in concepts.json.
• The finale is the last step and is always required.
• requires.minWordsKnown compares against discovered words, so the chain stays playable.
• koreanLevel (1–6) drives the generated grammar and must equal Topik.levelForDepth(depth) (depth <= 3 → 1, <= 6 → 2, <= 9 → 3, <= 12 → 4, <= 15 → 5, deeper → 6). Hints always stay at level 1.
• order sorts the journal and decides which trail starts automatically at world start (lower first; continuations sit above their parents).
• requires.completed lists parent trail ids: the trail unlocks only when all of them are finished. Locked trails say what they are waiting for in the journal.
• Goals and conditions are strict about their fields: an unknown field ({"type":"WEATHER","phase":"CLEAR"}) or a missing required one makes the file unreadable, and the log names the trail and the step (probe/s1 condition WEATHER: unknown field 'phase' ...). The fields of each type are in the schema.

Goal types

Tiers. One word stands for a tool or an armour piece in every material (곡괭이, 도끼, 삽, 괭이, 검; 투구, 갑옷, 바지, 신발), and a goal that asks for one material says it: with 곡괭이 taught, iron_pickaxe reads 철 곡괭이를 만드세요 (quest/goal/Tiers). The goal is exact then: a wooden pickaxe does not finish a step that says 철 곡괭이. The name printed is always the official one (names.json): iron_chestplate reads 철 흉갑 (not “철 갑옷”), the leggings 철 레깅스, the boots 철 부츠, and the leather set 가죽 모자, 가죽 조끼, 가죽 바지, 가죽 장화. The general word keeps the sentence when the goal is any piece of the slot: EQUIP on #minecraft:chest_armor (also head_armor, leg_armor, foot_armor) says 갑옷을 입으세요 and takes every material.

Relations and anchors. The Korean names the relation (문 옆에, 기둥 위에) in every form of the sentence, and the English and German clue must not give it away. A relation goal is graded: finishing the step is a right outcome for the location noun (L1.loc_yeop_e for NEXT_TO, L2.loc_sai_e for BETWEEN, …), and a right block in the wrong relation is a wrong one (at most three per step). BETWEEN has one anchor (두 횃불 사이에) or two different ones: "anchor": "minecraft:chest", "anchor2": "minecraft:furnace" says 상자와 화로 사이에 (와/과 by the final sound; the pair is one task whichever way round it is written). With water or lava as one of the two (모래와 물 사이에 사탕수수를 심어요) a plant counts that stands on the other block with the fluid next to it, on the shore. Blocks with a front can be the anchor of 앞 and 뒤: doors, chests, furnaces, beds, stairs, barrels, workstations, signs, banners, pumpkins, bells; a pillar, a wall or a fence cannot. So can a creature that faces a way (minecraft:villager, an iron golem, a cow, a wolf …: 주민 앞에 횃불을 놓아요; 앞, 뒤, 옆 and 근처 only). 밖 is a deciding form (a block put outside when 안 was asked is a slip), 근처 is not. Fluids are anchors too (minecraft:water is 물, minecraft:lava is 용암: 물 옆에 횃불을 놓아요). A tag (#minecraft:doors, logs, planks, wool, fences, beds, torches, chests, flowers, signs, candles, wool_carpets, windows, saplings, leaves; for EQUIP also head_armor, chest_armor, leg_armor, foot_armor) is spoken with its everyday word (문, 통나무, 판자, 양털, 울타리, 침대, 횃불, 상자, 꽃, 표지판, 초, 양탄자, 창문, 묘목, 나뭇잎): the curated concept whose items and covers are the largest set inside the tag; a tag without such a word is a validator error, never “그것”. The finale line uses the same word as the clue, and a word the step teaches (나무 for the logs) wins in both.

The block of an earlier step. "anchor": "@s2" points at the block that finished step s2 of the same trail, which must be a PLACE_BLOCK, PLACE_REL or PLACE_ON_PATTERN step before this one. The sentence says 아까 놓은 횃불 옆에 (the verb of that step as a past -(으)ㄴ, so the trail needs koreanLevel 5 or higher). Only ON_TOP_OF, UNDER, NEXT_TO and NEAR fit a single spot. The engine remembers where the block stood and saves it with the trail (placed on the saved quest); if the memory is missing, any block of the kind that step placed will do.

Level 3 connectives. Where a task has two natural parts, a trail of level 3 says both with -고: a CRAFT with with ingredients reads 막대기와 석탄을 모으고 횃불을 만드세요, and a PLACE_ON_PATTERN whose structure no earlier step of the trail built reads 돌로 기둥을 쌓고 그 위에 횃불을 놓으세요. Other levels and the hint keep the single clause.

SEQUENCE and AVOID teach -기 전에 / -(으)ㄴ 후에 / -고 나서 and -지 마세요, so the English and German clue must not give the order or the “not” away („Do the two things in the order the Korean says“). SEQUENCE parts, the HOLD_WHILE inner goal and the AVOID action are simple goals (no nesting). Finishing a GIVE (에게), an ordered SEQUENCE (its connective) or an AVOID (-지 마세요) rightly is a right outcome for that construction; doing an ordered sequence out of order is a wrong one.

Verbs a step can teach. A step may teach a verb next to its nouns, or as its first word: the clue then contains a conjugated form of it (올라가요 for 올라가다). When the goal can say that verb it uses it instead of its default: 요리하다 for a food in the furnace (닭고기를 요리해요, the default is 구워요), 타다 for a boat that is sat in (배를 타요), 나오다 for leaving (집에서 나와요). A water biome with the IN_WATER condition reads 바다에서 수영해요, not 물속에서 바다로 가요: the sentence already says the water, so the condition’s phrase is left out.

Conditions (gates)

TIME (DAY/NIGHT/DAWN/DUSK), WEATHER (CLEAR/RAIN/THUNDER), Y_RANGE, NEAR_ENTITY, NEAR_BLOCK, IN_DIMENSION, IN_BIOME, HOLDING („횃불을 들고“), SKY (OPEN/ROOFED), IN_WATER („물속에서“), PLAYER_REL (relation, anchor, optional kind = block/item/entity: „나무 아래에서“; without a kind an entity name wins, so minecraft:chicken is the animal). A goal only counts while every condition holds.

A step may teach the word for any role of its goal or conditions (the object, an anchor, the recipient, the container, the held item, a material). When the first taught word has several referents (물고기 = cod, salmon, tropical fish) and covers an id of the goal, any of them completes the step; a word with one referent never widens the goal. The covers of a concept (concepts.json) count as much as its items: a step that teaches 묘목 accepts any sapling as its goal, not only the oak one, and the sentence says 묘목 for it too. A cover is spoken with the word unless the word only describes ("grammar": "DESCRIPTOR", the colours: 빨간색 양털 stays 빨간색 양털) or the item has a hand-made word of its own and the word only resembles it (눈 does not name the snow block; "accepts" lists ids that a goal takes but the word never names). A word for one flower names that flower only: with 해바라기 taught, “민들레 옆에 해바라기를 심어요”. The covers of a biome concept are biomes: 동굴 covers the lush caves, so a REACH_BIOME on any of them counts and reads 동굴로 들어가요. A step that teaches a word of the biome’s kind still says the biome: 개구리 on a swamp reads 늪으로 가요. The hint of a step with several nouns names every noun the goal has a place for, so it needs no authored hint.

Rules

• Korean fields (clue.ko, hint.ko, textKo, titleKo, topic) are Hangul only — digits and punctuation are fine. The test fails otherwise.
• English and German text is a translation, not the quest: the player sees Korean first. Shipped trails need an English text for the title, every clue and hint and the finale (ContentTextTest); German is optional.
• Exactly one goal per step, the finale included.
• Step ids are unique within a trail.
• concepts is the list of words shown under the trail in the journal.
• Never require a structure, a chest or a specific coordinate. The ritual finale is the guarantee that a trail can always be finished.
• Do not teach a word twice in the same step list unless the repetition is the point.

Validating

./gradlew test                      # content validation plus engine tests
python3 tools/validate_schema.py    # shape only, against docs/questline.schema.json
python3 tools/i18n/extract_content.py --check   # no English/German text left inline in shipped files

QuestlineValidationTest loads every file, checks references, ids, Hangul and the finale, and fails on dead ends, missing parents, wrong Korean levels, unspoken conditions and clues that do not name the action. At runtime the loader skips a broken step with a log warning instead of crashing the game.

The full attribute list — including what the journal must show for each state — is in the attribute reference.

Once a trail is written, the attribute reference is the checklist to run through before opening a pull request, and the quest tree shows where it would fit.

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.

The quest tree

This page is generated from the content itself, so the numbers below are what the mod actually loads. Every trail is one JSON file in src/main/resources/assets/hangulquest/data/questlines/.

A trail’s koreanLevel (1 to 6) follows its depth in the tree and picks the instruction ending of data/ladder.json: level 1 speaks -아/어요, levels 2 and 3 -(으)세요, levels 4 to 6 -아/어야 해요 (level 6 may use -(으)ㄹ 수밖에 없어요 where a sentence states a forced conclusion).

Goals and conditions

Every goal is checked on the client. Counts are per step, finales included.

Levels

Level 1 · TOPIK 1 · 39 trails

Level 2 · TOPIK 1 · 24 trails

Level 3 · TOPIK 1 · 35 trails

Level 4 · TOPIK 2 · 34 trails

Level 5 · TOPIK 2 · 43 trails

Level 6 · TOPIK 2 · 40 trails

Level 7 · TOPIK 3 · 40 trails

Level 8 · TOPIK 3 · 46 trails

Level 9 · TOPIK 3 · 18 trails

Level 10 · TOPIK 4 · 8 trails

Level 11 · TOPIK 4 · 15 trails

Level 12 · TOPIK 4 · 13 trails

Level 13 · TOPIK 5 · 10 trails

Level 14 · TOPIK 5 · 11 trails

Level 15 · TOPIK 5 · 6 trails

Level 16 · TOPIK 6 · 4 trails

Level 17 · TOPIK 6 · 3 trails

Level 18 · TOPIK 6 · 22 trails

Level 19 · TOPIK 6 · 3 trails

Level 20 · TOPIK 6 · 5 trails

Level 21 · TOPIK 6 · 1 trails

Level 22 · TOPIK 6 · 2 trails

Reading the tree

• Roots have no requires.completed. There are several so a new player can start in the branch that matches what they are doing anyway.
• Merges (a trail with two or more parents) are the interesting nodes: they only unlock when every parent is finished, which is what turns a list of questlines into a tree.
• Hints never leave level 1. A late trail speaks literary Korean; pressing H restates the same task in polite Korean, so the ladder never blocks you.
• The ritual finale is the guarantee. Every trail ends with an action you can always perform — a torch at night, a campfire on a beach — never a structure or a coordinate.

Contributing

The full contribution guide lives in the repository: CONTRIBUTING.md.

Short version:

• Questlines need no Java. Write a JSON file, run ./gradlew test, open a pull request. Read the authoring guide and the attribute reference first.
• Code is Java 25 on Gradle 9.7.1 and Loom 1.18. ./gradlew test and ./gradlew build have to pass; CI runs the same on Linux, plus a schema check over every questline file.
• Interface strings are keys named hangulquest.ui.<area>.<name> in lang/en_us.json (the reference); arguments are %s. A key a language lacks falls back to English.
• Quest and word text (trail titles, clues, hints, finale lines, word glosses) is keyed too, in lang/content/en_us.json. The questline JSON holds the Korean only; see the authoring guide.
• Translations (German, Spanish, French so far) are made in the repository, with no outside platform. English is the source and Korean is never translated. A model drafts a language, a second model proofreads it (tools/i18n/translate.py export, import, proofread-export, proofread-import), and every key carries a state: machine, proofread, community-approved or stale (the English changed). translate.py check runs the same rules as CI (placeholders, Hangul, untranslated English, length). To fix a line, use the Translation correction issue form or edit the key in a pull request; the review site has a page per language. To add a language: translate with the pipeline, then translate.py ship --lang <code> lists it in data/languages.json.
• Bugs go to the issue tracker with versions, the questline id and a log excerpt. Security problems go through the private advisory form, never a public issue.
• Be decent. Grammar disagreements are expected; harassment is not.

Good first contributions

• Checking the Spanish and French text, or starting another language (see above).
• Reading the Korean lines on the review site, if you speak Korean.
• More curated concepts: animals, dyes, redstone parts and a few verbs are thin.
• Playing a branch you did not write and reporting the clues that were ambiguous.
• Tests for the validator’s edge cases: cycles, missing parents, a condition that is not spoken.

Building the guide

This site is mdBook. To build it locally you need the mdbook binary and the screenshots in place:

tools/build_book.sh            # copies docs/screenshots, regenerates the tree, builds the book
python3 -m http.server -d docs/book/book 8000

Help review Korean

Every Korean line in the game, from a quest clue to a word card, is checked by a linter and by two AI reviewers. Only a person who speaks Korean can say that a line sounds natural. If you do, you can help without installing anything and without using git.

Open the review site (it is in Korean first, then English).

1. Open a page and read the lines.
2. Press 맞아요 / Looks right when a line is natural.
3. Press 고치기 제안 / Suggest a correction when it is wrong or odd, and write the better line.

Each button opens a prefilled GitHub form; you need a GitHub account. A bot checks the line id, the text and the Korean linter, then a maintainer decides. Approvals count from accounts at least 30 days old, and nobody can approve their own line. A line becomes native approved after two different reviewers approve it, or one trusted reviewer.

Your name goes on the credits page, unless you write anonymous in the form.

Where it stands: the linter checks every line, and two AI reviewers (Claude and Gemini, blind to each other) have read part of them. No line has been approved by a native speaker yet. This site says so, and every line you approve or correct moves that number. Translations (German, Spanish, French) have their own pages on the review site and a Translation correction form.

The full rules for reviewers (and the Korean guide) are in CONTRIBUTING.md.

Credits

Hangul Quest teaches Korean, and its Korean is only as good as the people who check it. Thank you to everyone who reviewed a line, suggested a correction or approved a page.

한글 탐험의 한국어는 검토해 주신 분들 덕분에 좋아졌어요. 모두 고맙습니다.

No reviewer has been credited yet. Be the first: see Help review Korean.

Reviewers can pick the name shown here, or leave it out, in the last field of every review form.

Third-party notices

Hangul Quest is MIT licensed. It bundles one third-party asset and builds on several projects whose licences stay their own. The canonical file is NOTICE.md; this page is the short version.

Font

assets/hangulquest/font/hangul.ttf is a subset of Noto Sans CJK KR (weight 400), generated with tools/make_font.py.

• Copyright 2014–2021 Adobe, with Reserved Font Name “Source”. Noto is a trademark of Google Inc.
• SIL Open Font License 1.1 — https://scripts.sil.org/OFL. Bundling and subsetting are allowed; the font is not sold on its own and the reserved name is not used for the modified subset.

Minecraft and Fabric

Minecraft is a trademark of Mojang Synergies AB. Hangul Quest is not affiliated with, endorsed or sponsored by Mojang Studios or Microsoft, contains no Minecraft code or assets and requires a legitimate copy of the game.

Fabric Loader and Fabric API are Apache-2.0 and are not bundled: the mod declares them as dependencies and the player installs them.

Vanilla names

data/names.json is generated by tools/extract_names.py from the Korean and German language files of the installed game. It contains item, block, entity and biome names only — no models, textures, sounds or other assets. Quest text written on top of those names is original.

Advancements

Some questlines are themed around vanilla advancements; only their names and completion conditions are referenced, and no advancement data is redistributed.

Lute

The vocabulary import parses Lute’s CSV export (MIT). Lute is not bundled and is never written to.

Build tools

Gradle (Apache-2.0), Fabric Loom (Apache-2.0) and JUnit 5 (EPL-2.0) build and test the mod; they are not distributed with it.