Skip to content

Quick start

This walk-through takes you from an empty configuration to an exported ADV episode and a story directory. It needs your own installation of the game: its base.apk, and the keys and server addresses of your client (where the values come from).

1. Install

pip install 'nnnotes[fonts]'

Python 3.11 or later. Install vgmstream (vgmstream-cli) and FFmpeg as well, on PATH or named in the config file; stories decode their audio and videos with them.

2. Write the config file

nnnotes config init --user

In a terminal this asks for each setting in turn, among them the bundle and master data keys, the names of your regions with each region's CDN base and API root, the catalog language, and the paths of the cache, the APK and the tools. Enter leaves a setting empty; the keys are read without echo. The file is written to the per-user location, which every command reads from any directory (nnnotes config path shows it).

Check it:

nnnotes config check

Every setting is listed with where it comes from and whether it is valid, never with its value. A command that needs an unset setting stops with exit status 2 and names the TOML key, the environment variable and the flag that set it.

3. Look at the catalog

nnnotes catalog keys --prefix Adv/ --limit 5

The first command downloads the region's catalog into the cache; the keys it lists are the addressable keys of the game's assets. nnnotes catalog browse serves a local web page to browse the catalogs and bundles of every configured region.

4. Get the master data

nnnotes master version
nnnotes master download --latest -o work/master-bin
nnnotes master decode work/master-bin -o work/master
nnnotes config set paths.master work/master

master version asks the region's game API which master data version it serves now; master download fetches that version and checks every file's SHA-256; master decode writes one JSON file per table. The last line makes the decoded directory the default of every command that reads master data.

5. Export an episode and a story

nnnotes export episode 10462 -o out/episode_10462.json
nnnotes export story 10462 -o out/story_10462

export episode writes the episode's command list with its lines in five languages and the index of its voices, sounds and videos. export story writes the whole story directory: the episode, its audio, the stage scene and shaders, the story UI, frames, effects, stills, chats and videos; the Live2D models it uses go to out/live2d/, where the next story reuses them. Add --json to any command to get its report as JSON.

Next