Kotoba Quest

Vocabulary drills say that an answer is wrong, but rarely why that particular choice is wrong, and looking a word up usually means losing your place. Can a small game explain each wrong choice, let you check the dictionary in the middle of a question and come back to the same question, and keep honest records with no account and no server?

Four question types (reading, writing, word in context and grammar) are graded by rule against a stored choice ID, so shuffling the choices cannot change the answer. Each wrong choice has its own explanation, and each question links to the dictionary entry it tests. The dictionary holds kanji, words and grammar points with example sentences.

A round is saved to IndexedDB as it is played: the questions and their revisions, the choice order, the selection, the grade and the reward. Reloading the page, or opening the dictionary from a question and coming back, resumes the same question. The answer, reward and progress are written in one transaction, and submitting the same answer again returns the stored result without paying the reward twice.

Coins buy hats, a scarf and weapons. A purchase checks the balance, deducts the coins, records ownership and writes a ledger entry in one transaction, and a repeated purchase request is not charged twice. The game, the wardrobe and the profile card all draw the same equipped character. The card is drawn on a canvas as a 4:5 or 9:16 PNG and can be shared or saved, and a JSON backup exports and restores the player's records.

Items answered correctly come back for review after 1, 3 and 7 days; wrong ones come back the next day. A daily attendance reward is kept in a separate ledger and does not count as study. After the first download, a service worker caches the app so that it can run offline. Sound is off until the player turns it on.

The demo has two beginner packs: 14 questions on rest and the body and 15 on days and dates, with 21 dictionary entries and 24 example sentences. Questions marked as approved are the only ones ordinary study may use, and that list is empty, so ordinary study shows a “coming soon” screen and the drafts appear only in a demo mode labelled as unreviewed.

The official build was in its final QA, so I did not touch it. On 8 November 2026 I re-ran its checks on a copy whose source files matched the original by SHA-256: all 106 Vitest tests then passed across 15 files, as did the TypeScript check, the content check (three pinned files: 14 + 15 draft questions, 21 entries, 24 examples) and the audio check (13 selected files). The development branch has since grown to 154 Vitest tests across 19 files; on 10 November 2026 all of them, and the TypeScript check, passed on an export of that branch (hyh4867/kotoba-quest at commit 20bc1e9).

The tests cover rule-based grading by choice ID, wrong-choice explanations staying matched after shuffling, restoring a round after reload and after a dictionary round trip, no double reward on a repeated answer, purchases that never charge twice, attendance kept apart from study, review dates, the card PNG and share fallback, backups and their migrations from older versions, and the offline cache. They run in jsdom with IndexedDB and the service worker mocked. In final QA in headless Chrome (390 and 375 px), the build had no release blockers. It relaunched offline once the app files were cached, and rewards and purchases were never granted twice.

The screenshots come from the frozen release-candidate build (build ID ceb3b15e2a1b3356) running in headless Chrome at phone width. A fictional player, “Player”, played one demo round, answered one question wrong on purpose, opened the linked dictionary entry and returned, then bought and equipped the starter sword and made a 4:5 card.

In that recorded round, the wrong answer きゅうにち for 休日 showed the explanation written for that choice, the dictionary button opened the 休日 entry, and returning restored the same graded question. Seven correct answers out of eight earned 70 XP and 35 coins. The 10-coin sword then appeared on the wardrobe character and on the generated card.

Writing a separate explanation for every wrong choice exposed weak questions. One grammar question was held back from the packs because two of its wrong choices could be ruled out only by judging the context, and replacing them created a new ambiguity.

I set the brief and the rules the game must keep: an explanation for every choice, no draft questions in ordinary study, rewards that cannot be collected twice, and records that stay on the phone. I chose the character and the sound set, and I decide which questions may be released.

AI agents worked in separate roles. Claude designed the screens and the character art and runs the browser QA; Codex implemented the app and its tests; both helped draft and check the questions. The music and sound effects were generated with ElevenLabs during development and ship as files. I reviewed their output and keep responsibility for the claims on this page.

Not a finished course. All 29 questions are unreviewed drafts on two beginner topics. This is not a JLPT textbook or an N5–N1 course, and the “beginner” label is a guide, not an official level.

Grading compares the choice with a stored answer. Game level and XP record play, not Japanese ability, and I have not tested whether the game helps anyone learn. The 1-, 3- and 7-day review intervals are a starting rule, not a tuned schedule.

Installation, iPhone behaviour and real speakers remain unverified, and fixes to update delivery and cache recovery are still recommended. The app cannot start offline before its first download.

Public release needs two more approvals: a human review of the questions, and confirmation of the usage terms for the generated audio. The app is not deployed, so there is no live demo.

The code is private. The release-candidate report records the build ID, a SHA-256 for every file in the static build, and the logs of each check. The dictionary uses JMdict, KANJIDIC2 and KanjiVG data, credited in the app's settings. Every screenshot comes from the demo mode with a fictional player, and the demo labels are left in.