Kingdom Hearts 100% Tracker

An unofficial, fan-made 100% completion tracker for Kingdom Hearts Final Mix and Kingdom Hearts II Final Mix, with save-file import. It's a single-page app (Vite + React 19 + TypeScript 6, React Router v7, Zustand) styled after the KH2 pause menu. One site, with a game switcher in the header.

Live site: https://kh-tracker.vercel.app

Each game tracks three definitions of 100% from one checklist: Jiminy's Journal, Trophies (Platinum excluded from the count) and Everything. Importing a PC save fills in most of the checklist; the file never leaves the browser. In Chrome and Edge the tracker can also watch the save file and re-import it every time the game saves (Config, Auto re-import).

Game	Routes	Save import	Filled in from the save
KH1FM	/kh1/…	KHFM.png / KHFM_WW.png (PC)	216 chests, most event rewards and story events, 24 Trinity/map prizes, Ansem's Reports, puppies, Sora LV, magic, summons, Keyblades, staves, shields, Ultima materials
KH2FM	/kh2/…	KHIIFM.png / KHIIFM_WW.png (PC), PS2 saves, PCSX2 cards	317 chests, 89 rewards, 52 bosses, Ansem Reports, Drive Forms, magic, summons, Keyblades, superbosses

There's also a save diff tool at /tools/save-diff: load a save from before and after an in-game event to see every byte and bit that changed. It's how the remaining unknown flags get mapped.

Unofficial fan tool. Not affiliated with Square Enix or Disney. Item icons, trophy images and world logos are Square Enix and Disney property, shown only to identify items under fair use (see Game images). No game fonts, music or sounds are used.

Local development

Requires Node 22.22+ and npm (React Router 8 needs it; CI uses Node 22 and Vercel Node 24).

npm install
npm run dev

The dev server runs at http://localhost:5173. Other scripts:

Script	What it does
npm run typecheck	tsc --noEmit (strict)
npm run lint	ESLint (typescript-eslint, react-hooks) + Prettier check
npm run format	Prettier write
npm test	Vitest + React Testing Library (+ axe smoke test)
npm run build	Typecheck, then a production build into dist/
npm run preview	Serve dist/ locally

Project layout

src/
  core/      game-agnostic engine: types, rules (trophies), progress, importSave, detect (save probes),
             store factory (Zustand + persist), backup codes, storage, file handles, save watcher, save diff
  games/
    types.ts       GameDefinition: nav, routes, catalog, store, save support, wallet, backups
    context.ts     useGame / useTracker / useProgress / useGameHref
    registry.ts    GAMES, in switcher order
    kh1/           data (locations.json, constants, trophies, journal, synthesis), save, model, routes
    kh2/           data, save, model, routes, migrations (prototype backup codes)
  screens/   screens shared by every game: Status, Worlds, Trophies, Config
  shell/     frame, game switcher, home (Choose a Game), game shell, not-found pages, save diff tool
  ui/        CommandMenu, HandCursor, HelpBar, Gauge, PartyCard, ChecklistRow, Section, Stepper, TrophyCard, …
  styles/    tokens.css (palette, fonts, motion), global.css
reference/   the prototype and designs KH2 was ported from
data/        source copy of the KH2 location data
scripts/     extract_locations.py (KH2), kh1/extract_locations.py (KH1), brand/ (share image and icon sources)
pwa/         service worker template (the build fills in the file list)
public/      favicon, app icons, web app manifest, og.png link preview

Adding a game means adding a games/<id>/ folder that exports a GameDefinition and listing it in the registry. Trophies are never stored: they're evaluated from progress on every change (memoized per progress object). Each game has its own store (kh1fm-tracker, kh2fm-tracker in localStorage), backups and save watcher.

Tests

npm test

Covers both save parsers (hand-built buffers, original-game saves, a PCSX2 card, empty files, slot labels), detection, trophy rules, scoring, import sync/add with manual overrides, backup codes, storage failures, the watcher, the save diff, every KH2 screen's main interactions, the game switcher, and an axe accessibility pass over every route of both games.

Real-save fixtures

Put real PC saves in tests/fixtures/ (gitignored, never committed). The fixture suites skip when a file is missing.

• tests/fixtures/KHIIFM.png: Slot 1, LV 45, 3,779 munny, Critical, saved in TWTNW; chests 272/317, rewards 78/89, story bosses 50/52, reports 13/13, Keyblades 19/24, forms 5/5/2/4/1, magic 3/2/3/3/3/3, summon LV 1, all charms, torn pages 5/5, no Proofs, Final Xemnas not detected.
• tests/fixtures/KHFM.png: Slot 1 LV 100, 23,666 munny, Proud, End of the World (chests 208/216, event rewards 56, story events 95, prizes 18/24, reports 13/13, Keyblades 18/18, puppies 99, magic all LV 3, six summons) and Slot 2 LV 54, 2,479 munny, Proud, Neverland.

Regenerating the location data

KH2 is built from the Archipelago KH2 world:

git clone --depth 1 --filter=blob:none --sparse https://github.com/ArchipelagoMW/Archipelago.git ap
(cd ap && git sparse-checkout set worlds/kh2)
python3 scripts/extract_locations.py ap/worlds/kh2 data/kh2fm-locations.json
cp data/kh2fm-locations.json src/games/kh2/data/locations.json

KH1 is built from the Archipelago KH1 world, the KH-1FM-AP-LUA connector and KH1FM-RANDOMIZER's globals.lua, pinned to the commits the current data came from. The usage line at the top of scripts/kh1/extract_locations.py has the exact clone commands:

python3 scripts/kh1/extract_locations.py ap/worlds/kh1/Locations.py kh1lua/1fmAPConnector.lua     src/games/kh1/data/locations.json "kh1rando/Static Files/scripts/io_packages/globals.lua"

Then run npm test: the data tests check totals and id uniqueness, and the fixture tests check real saves.

Share image and app icons

public/og.png (the 1200×630 link preview) and the PNG app icons are screenshots of scripts/brand/og.html and scripts/brand/icon.html. After editing either, regenerate them on Windows with Edge or Chrome installed:

pwsh scripts/brand/render.ps1

Game images

Icons, trophy images and world logos are self-hosted copies of KHWiki files. KHWiki hosts them under fair use and doesn't license them for reuse; they're Square Enix and Disney property, used here at icon size only to identify items.

• scripts/icons/manifest.json lists which wiki file each item, trophy and world uses.
• npm run icons:fetch downloads anything new into a gitignored cache (one request at a time, with a pause), then writes small WebP copies to public/icons/<game>/ (96px squares, 144x48 bars for Keyblades and staves, rotated level from the diagonal renders, and 80px-tall logos), src/games/<game>/data/icons.json and public/icons/CREDITS.json. Run npm run format afterwards.
• Spells have no wiki icons, so they use glyphs drawn for this project (src/ui/icons/).
• To take the images down, delete public/icons/ and empty the three tables in each icons.json; every screen falls back to text.

How-to-obtain notes

Rows with an (i) button open a short note on where to get the item, plus a link to its KHWiki page. The notes live in src/games/<game>/data/info.json (how is the note, wiki the KHWiki page title). They're written for this project in our own words from each page's infobox for that game (its "get" line, or the shop price), not copied, so they aren't under KHWiki's CC BY-SA text licence. An item with only wiki shows just the link: the Mythril Shield, whose page doesn't say where to find it. Covered: equipment, abilities, collectibles (reports, Torn Pages, Proofs, puzzles, keyholes, materials and synthesis recipes) and challenges (mini-games, Mushroom XIII, Absent Silhouettes, Data Organization, cups, superbosses, Journal, Gummi and feat goals). Spell, form and challenge notes come from the prose of their KHWiki pages, using the Final Mix details where a page notes a difference. Torn Pages share one note per game because the game doesn't number them. The Promise Charm and a few self-explanatory KH1 feats have no note. Each game's Trophies screen links its KHWiki trophy list (trophies in info.json). Level steppers take an infoId to show the same button.

Sync between devices

One 6-character code keeps every game's progress in step across devices (Config > Sync between devices). It isn't private: anyone with the code can read and change that progress.

• Server: api/sync.ts is a Vercel Function; the logic is in server/sync.ts (create a code, read it, save with the revision you last saw). Data lives in Upstash Redis (server/upstashStore.ts), one hash per code, and a small Lua script does the compare-and-write atomically. Limits: 100 KB per code, 60 requests a minute per IP, and codes expire after a year without a save.
• Setup: install the Upstash Redis integration from the Vercel Marketplace on the project. It adds KV_REST_API_URL / KV_REST_API_TOKEN (or the UPSTASH_REDIS_REST_* names), which the store reads. Without them the function answers 503 and the app shows that sync is unavailable.
• Local: npm run dev and npm run preview serve /api/sync from memory (a Vite middleware), and the tests use the same in-memory store, so no credentials are needed. Two origins such as localhost:5173 and device2.localhost:5173 act as two devices against one dev server.
• Client: src/sync/engine.ts. Per game it compares fingerprints of the last synced data, this device and the server: only one side changed means apply or upload; both changed means ask (Config, with a banner on every page). Different games changing on two devices merge automatically. Games added in later versions are stored by id and passed through untouched by older versions. Only playthroughs, the active playthrough and the profile sync; save watching, NEW! tags and the latest-changes card stay per device. SyncAgent pulls on start, on focus, when back online and every 5 minutes, and uploads 3 seconds after a change.

Continuous integration

.github/workflows/ci.yml runs lint, typecheck, tests and a production build on every pull request and every push to main. The real-save fixture suites skip there because the saves aren't in the repo.

.github/dependabot.yml opens dependency PRs monthly: one grouped PR for npm minor and patch bumps, separate PRs for major versions, and one for GitHub Actions.

Deploying (Vercel)

The live site is the Vercel project kh-tracker, linked to this repository: every push to main deploys to production at https://kh-tracker.vercel.app, and other branches get preview URLs.

vercel.json sets the build command (npm run build), the output directory (dist) and an SPA rewrite so deep links like /kh2/worlds/tt work on a hard refresh.

• Git integration: push the repo to GitHub, then in Vercel choose Add New → Project, import the repo and keep the detected settings. Every push gets a preview URL; the default branch deploys to production.
• CLI: npm i -g vercel, then vercel login, then vercel for a preview deploy and vercel --prod for production.

Contributing

Mapping save flags, fixing content and reporting wrong flags are all welcome. See CONTRIBUTING.md for the ground rules, how item ids are protected, and a step-by-step guide to finding a flag with the save diff tool.

Credits

• Location data: Archipelago KH1 and KH2 worlds (MIT).
• KH1 save flags: derived from KH-1FM-AP-LUA's 1fmAPConnector.lua (MIT): its Steam memory addresses minus 0x2DE9360 give the save offset. Map prize (Trinity mark, flower, chair) flags come from KH1FM-RANDOMIZER's globals.lua (MIT).
• Save structure: Kingdom Save Editor (GPL-3.0). Its documented offsets, item ids and enums are referenced; none of its code is copied.
• Trophy names, tiers and requirements: KHWiki, Exophase, PSTHC, PlayStation LifeStyle, Gamer Guides. Journal sections, synthesis lists and Ultima Weapon recipes: KHWiki and Gamer Guides.
• Game images (item icons, trophy images, world logos): © Square Enix and Disney, sourced from KHWiki. public/icons/CREDITS.json links every file's source page. The spell glyphs are drawn for this project.

License

MIT, see LICENSE. The MIT license covers this project's code and text only. Kingdom Hearts is a trademark of its owners, and the game images in public/icons/ belong to Square Enix and Disney (see Game images).

Open questions (left as TODOs, with manual fallbacks)

Nothing below is guessed; each is a manual check or input in the UI.

KH2: see reference/completion-definitions.md. The game-cleared (Final Xemnas) flag, entry lists for six Journal sections, the full mini-game list, Mushroom XIII count, and save offsets for the Anti Form counter, feats, Gummi ranks, synthesis materials, Synthesis Notes and Moogle level.

KH1: entry counts for Chronicles, Characters and Mini-games; the Trinity mark counter; cup wins, solo and time-trial records (outside the save slot by the connector's addresses); synthesis record; gummi records; whether 0x1400 counts torn pages held or delivered; which staves and shields Master Magician and Master Defender need.

Decisions

Choices the brief didn't settle, with the default picked:

1. Menu order (KH2) follows the route table and the What's Left design: Status, What's Left, Worlds, Journal, Trophies, Synthesis, Drive & Magic, Keyblades, Records, Config. KH1 mirrors it, with Magic & Summons and Equipment in place of Drive & Magic and Keyblades.
2. Duplicate KH2 location keys. The extractor truncates keys to 24 characters, so five pairs of chests share a key (e.g. two ElephantGraveyardMythril… chests with different flags). The first keeps the prototype id; the second gets -2. A prototype backup with the shared id checks both rows. The real-save fixture still gives 272/317.
3. Data-model extensions. SaveProbe gains level (clamped byte, optionally gated by an unlock bit), bitCount (set bits in a range, for KH1's 99 puppies) and listHas (KH1's owned-summon list); an item may list several probes (any match counts), which is how a Keyblade counts if owned or equipped. Rule gains { section } (a Journal section complete) and { count, atLeast } ("open 100 chests", "synthesize 15 items").
4. Level ids are lv.sora, lv.valor, … stored in values.
5. Manual overrides. Any change by hand (row toggle, stepper, Check all/Clear, trophy mark, game-cleared toggle) records an override. Both Sync and Only add skip overridden items. Overrides are cleared by Reset.
6. Backups. Codes are { app, v: 3, s: Progress & { profile } } with app = kh1fm-100 or kh2fm-100. KH2's prototype v1/v2 codes still restore.
7. Store shape. One persisted store per game; progress lives in playthroughs[id] with an activeId; the profile and NEW! flags are per game. Persisted data is validated on load, and storage failures fall back to memory.
8. No Web Worker. Scanning a full PC save (7 MB for KH2, 18 MB for KH1) takes well under 100 ms.
9. What's Left. KH2: Count toward / Hints / Group by live in the query string; quick wins score = remaining items
   • 0.5 per item that counts toward an unearned trophy + 0.5 per Ultima item; Area hides chest contents with a name-splitting heuristic (games/kh2/model/areas.ts). KH1 has a simpler version (Count toward, world groups, trophies within reach).
10. Synthesis. KH2: with the Energy Crystal toggle on, the recipe lists Orichalcum+ ×7 plus Energy Crystal ×1; material counts, Synthesis Notes and Moogle level are manual. KH1: Ultima material counts are read from the inventory (item ids from Kingdom Save Editor); the 33 synthesis items are manual checks.