Run any Skill in Manus with one click

zak-fmtowns-zhtw

Stars1

Forks0

UpdatedJuly 6, 2026 at 08:09

Zak McKracken (FM-Towns Steam 版) 繁中化的完整工具鏈、編碼陷阱與 ScummVM patch 點。當使用者談到「Zak McKracken」「Zak 中文化」「scummtr 不認 CJK」「Unknown function id 0xAB / 0xCF」「Truncated escaping」「FM-Towns 中文」「SCUMM 中文化」「chinese_gb16x12.fnt」等情境觸發。

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Run Skill in Manus

Source

wicanr2

wicanr2/my_skill

View GitHub Repository View Creator Repositories

Download

Run Skill in Manus

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

Zak McKracken FM-Towns 繁中化完整 SOP

LucasArts SCUMM v3 老遊戲的中文化路徑。表面看有兩個結構性卡點（字型 8×8 太小 + scummtr 拒收 CJK），實際兩個都可以繞過——scummtr 的「不認 CJK」是參數誤用，字型靠 patch ScummVM 走 ZH_CHN 12×12 路徑。本 skill 把所有非顯然的關鍵點記下來。

工作目錄結構

~/zak-zh/
├── original/   完整 Steam 快照（136 MB，含 ScummVM exe + PDF）
├── working/    工作副本，所有改動都在這裡（136 MB）
│   └── ScummVM/enhanced/   ← FM-Towns 遊戲資料（59 LFL + 98/99.LFL 字型 + Track*.mp3）
├── dumps/      抽出的英文 dump + 中文譯文 + 字型 BMP
├── tools/
│   ├── scummtr-0.5.1-linux86/   官方 release binary
│   ├── scummtr-src/             從 dwatteau/scummtr clone，自己 build
│   └── scummvm-src/             從 scummvm/scummvm clone，含 patch
└── sandbox_*/  各種編碼回填實驗（en/zh/big5/gb/gb_v2/zh_raw/gb_final）

不可動的東西：

~/.local/share/Steam/steamapps/common/Zak Mckracken/ — Steam 會驗證覆蓋
你自己維護的壓縮備份目錄（解壓來源，受損時靠它還原）

Steam 路徑裡實際的 FM-Towns 遊戲檔在 ScummVM/enhanced/ 子目錄，不是最外層。同捆還有 V2/DOS 版在 ScummVM/FDD/（gameid zakv2，對照用）。

版本辨識（FM-Towns vs PC V2）

特徵檔案	出現於	gameid
98.LFL + 99.LFL (各 2042 bytes)	enhanced/	`zaktowns`
Track1-21.mp3 (CD 音軌)	enhanced/	`zaktowns`
00-58.LFL（無 98/99）	FDD/	`zakv2`

zak.ini 寫 platform=fmtowns、gameid=zak、path=enhanced。

工具鏈速查

# 官方 binary
~/zak-zh/tools/scummtr-0.5.1-linux86/linux-x64/{scummtr,scummfont,scummrp,FontXY}

# 自 build 版（cmake + make，無外部依賴；C++11 即可）
~/zak-zh/tools/scummtr-src/build/bin/{scummtr,scummfont,scummrp,FontXY}

scummtr -L 列支援遊戲：zaktowns 是 FM-Towns 變體的 gameid。

⭐ scummtr CJK 突破（最非顯然的發現）

scummtr 0.5.1 預設參數下會 reject 中文 byte stream，會丟以下任一錯誤：

ERROR: Bad escaping in line N
ERROR: Truncated escaping in line N
ERROR: Unknown function id 0xAB（Big5/GB lead byte 撞 SCUMM 0xFF/0xFE escape）

錯誤結論（PROGRESS.md 早期版本曾寫過、已撤回）：scummtr 不認 CJK。

正確解法：兩個參數一起改就過：

加 -r (raw mode)：bypass charset 翻譯（不是 -c）
譯文必須 CRLF 行尾：scummtr _unEsc() 對 LF-only 行尾有 byte-count bug，CRLF 修復

可運作的命令

# 1. 譯文 UTF-8 → CRLF
sed -i 's/$/\r/' zak_zh_draft.txt

# 2. 譯文放到 working dir，scummtr 預設讀 scummtr.txt
cd ~/zak-zh/working/ScummVM/enhanced/
cp /path/to/zak_zh_draft.txt scummtr.txt

# 3. 回填（注意是 -rwh 不是 -cwh）
~/zak-zh/tools/scummtr-0.5.1-linux86/linux-x64/scummtr \
    -g zaktowns -rwh -A aov -if

# 4. 抽英文 dump（如要 round-trip 驗證）
~/zak-zh/tools/scummtr-0.5.1-linux86/linux-x64/scummtr \
    -g zaktowns -rwh -A aov -of dump.txt

英文 round-trip（-cwh dump → 同檔 -cwh import → re-dump）已驗證 byte-perfect（85091 bytes 完全相同，diff 無輸出）。

Bad data was found and ignored at 0x6 in 47.LFL (Block too big: 0x220F5708) 警告是 GOG/Steam FM-Towns Zak 已知無害現象（dwatteau/scummtr FAQ 明說可忽略）。

編碼選擇與 0xFE 衝突

編碼	譯文大小	0xFE byte 數
UTF-8	~80 KB	0
Big5	66400	41
GBK	66400	89
GB2312	63078	29
GB18030	68441	89

ScummVM 端走 ZH_CHN 路徑需要 GB18030/GBK 編碼（用 chinese_gb16x12.fnt GB2312 字型）。Big5 對應的 ZH_TWN 路徑只支援 v7+ 遊戲，Zak v3 不適用。

UTF-8 雖無 0xFE/0xFF byte 最乾淨，但 ScummVM 處理 CJK 假設雙位元組編碼（is2ByteCharacter），UTF-8 3-byte 中文會被切錯。結論：用 GBK 或 GB2312 把譯文 encode，搭配 ScummVM 端的 v3 escape patch。

# UTF-8 → GBK + CRLF（用 Python 確保 encode 行為一致）
python3 -c "
text = open('zak_zh_draft.txt').read()
gbk = text.encode('gbk', errors='replace')
open('zak_zh_gbk.txt','wb').write(gbk.replace(b'\n', b'\r\n'))"

ScummVM patch 點（路線 B）

Patch 寫在 ~/tmp/zak/scummvm-zhtw.patch（git apply 可直接套用）。

Patch 1: `engines/scumm/charset.cpp` line ~126

把 GID_ZAK 加進 ZH_CHN 字型白名單：

case Common::ZH_CHN:
    if (_game.id == GID_FT || _game.id == GID_LOOM || _game.id == GID_INDY3 ||
        _game.id == GID_INDY4 || _game.id == GID_MONKEY || _game.id == GID_MONKEY2 ||
-        _game.id == GID_TENTACLE) {
+        _game.id == GID_TENTACLE || _game.id == GID_ZAK) {
        fontFile = "chinese_gb16x12.fnt";
        numChar = 8178;
    }

Patch 2: `engines/scumm/string.cpp` line ~1487

drawString() 對 0xFE escape 處理，在 ZH_CHN/ZH_TWN CJK mode 跳過（GB lead byte 不應視為 SCUMM escape）：

- } else if ((c == 0xFF || (_game.version <= 6 && c == 0xFE)) && (_game.heversion <= 71)) {
+ } else if ((c == 0xFF || (_game.version <= 6 && c == 0xFE
+         /* ZH-CJK 模式下，0xFE 是 GB18030 lead byte，不可視為 SCUMM escape */
+         && !(_useCJKMode &&
+              (_language == Common::ZH_CHN || _language == Common::ZH_TWN))
+         )) && (_game.heversion <= 71)) {

預期還需要 2-3 處 minor patch（convertMessageToString、addMessageToStack 等），實機跑遊戲時迭代修補。

ScummVM build

build deps（一次性 sudo）：

sudo apt install -y build-essential libsdl2-dev libsdl2-net-dev libfreetype6-dev \
    libpng-dev libogg-dev libvorbis-dev libflac-dev libmad0-dev libmpeg2-4-dev \
    liba52-dev libfaad-dev libfluidsynth-dev libcurl4-openssl-dev libgtk-3-dev \
    nasm pkg-config

build：

cd ~/zak-zh/tools/scummvm-src
git apply ~/tmp/zak/scummvm-zhtw.patch
./configure --backend=sdl --enable-release --disable-debug
make -j$(nproc)   # 8 核約 12-15 分鐘，~4500 個 .o 檔
# 產出: ./scummvm

注意：git clone 時用 sparse-checkout 不夠 build；需 git sparse-checkout disable 抓完整 source（約 808 MB）。

字型檔 `chinese_gb16x12.fnt`

格式（依 charset.cpp 推導）：

8178 字符 × 24 byte/字 = 196 272 bytes
每字 12 rows × 2 byte (12 bit + 4 bit padding)
排列：index = (lead - 0xa1) * 94 + (trail - 0xa1)
對映：GB2312 EUC (lead 0xa1-0xfe × trail 0xa1-0xfe)

ScummVM 內建 fonts-cjk.dat 不含此檔（只有 Noto Sans TTF）。三條取得路徑：

找現成：ScummVM 中文化社群（Monkey Island 等專案）的 fan-translation patch 包
自製：~/tmp/zak/build-zh-font.py 用 Noto Sans CJK SC 渲染 12×12 點陣（依賴 PIL + /usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc）
從老中文系統提取：PalmOS / 老 Windows 中文系統有類似格式

字型檔放到 ~/zak-zh/working/ScummVM/enhanced/chinese_gb16x12.fnt。ScummVM 偵測邏輯（engines/scumm/detection_internal.h）：只要遊戲資料夾有此檔，自動把 _language 設為 Common::ZH_CHN，不需手動指定。

跑遊戲

~/zak-zh/tools/scummvm-src/scummvm -p ~/zak-zh/working/ScummVM/enhanced/ zaktowns

如果 chinese_gb16x12.fnt 缺，ScummVM fallback 用英文 8×8 字型，看到的是 mojibake。

已知陷阱清單

陷阱	症狀	解法
動了 Steam 原始資料夾	Steam 啟動會把改動覆蓋	只動 `~/zak-zh/working/`
譯文 LF 行尾	`ERROR: Truncated escaping in line 187`	`sed -i 's/$/\r/' file` 改 CRLF
用 `-c` 對中文	`ERROR: Unknown function id 0xAB`	改用 `-r` raw mode
譯文 UTF-8 不轉碼	ScummVM 把 3-byte UTF-8 切錯	用 Python encode 成 GBK
ScummVM sparse-checkout build	缺 audio/video/math 等目錄	`git sparse-checkout disable` 抓全
`chinese_gb16x12.fnt` 期望 fonts-cjk.dat 內建	不在 ScummVM 官方資源	自製或社群取得
`Bad data at 0x6 in 47.LFL` warning	scummtr 每次都印	已知無害，忽略

翻譯草稿

~/zak-zh/dumps/zak_zh_draft.txt（2050 行繁中，UTF-8）由 Claude Opus 4.7 一次性翻譯：

完整覆蓋 2039 行英文 dump
保留所有 \255\X 控制碼與 @@@ padding
開發者名單區保留原文
待校對：The King（貓王致敬）、雙頭松鼠新聞標題雙關語、SCUMM verb interface 慣用詞

工時估算

從零開始走完整路線 B：

環境 + scummtr 突破 + ScummVM patch 設計：已完成（一晚）
ScummVM 編譯：1-2 小時（含下載依賴 + make）
取得/自製 chinese_gb16x12.fnt：自製 4-8 小時；找現成 30 分鐘起
實機跑遊戲 + 迭代 patch 0xFE 邊際 case：1-2 天
翻譯校對：2-3 天

預計總工時 4-6 天（比初估 5-7 天樂觀，因為 scummtr 不必 patch）。

2026-05-20 PoC 實測結果

走到 build + 實機跑為止，剩下一個 charset render crash 沒解：

已驗證通的部分

✅ scummtr 修改 funcLen → funcLenSafe 容忍未知 SCUMM function id（GBK 0xFE lead 不再炸） — patch 在 ~/zak-zh/tools/scummtr-src/src/ScummTr/text.cpp
✅ Python state-machine 轉 UTF-8 → GBK 並 escape GBK trail 0x5C（「運」= 0xDF 0x5C 等字會撞 scummtr \ 解析）：對每對 GBK 雙位元組，若 trail byte 是 0x5C，轉成 5C 5C 兩個 byte（scummtr _unEsc 看到 \\ 還原成單一 \）
✅ ScummVM patch 三處：
- charset.cpp loadCJKFont 加 GID_ZAK 進 ZH_CHN 白名單
- charset.cpp getDrawWidthIntern/getDrawHeightIntern 移除 assert(_cjkFont)，nullptr 時 fallback 到 _2byteWidth/_2byteHeight
- string.cpp drawString() 在 ZH_CHN/ZH_TWN 跳過 v3 SCUMM 0xFE escape
- scumm.cpp setupCharsetRenderer 對 ZH_CHN/ZH_TWN FMTowns 用 V3 而非 TownsV3 renderer
✅ 自製 12×12 字型 generator build-zh-font.py：8178 字全 render 無 skip，196272 bytes 完全匹配
✅ ScummVM 偵測為 (FM-TOWNS/Chinese (Simplified)) 自動切 ZH_CHN
✅ 標題畫面（ZAK MCKRACKEN AND THE ALIEN MINDBENDERS）正常顯示
✅ Intro 動畫第一場景（地球地圖 + alien 警報黃色閃光）跑出來

已知未解 issue

❌ drawBits1 對 12×12 _2byteFontPtr glyph 在 V3 renderer 也 segfault（gdb stack: displayDialog → V3::printChar → drawBits1）。Crash 發生在 intro 第一段對話框（Zak 的 dream sequence）渲染。
- 推測：V3::drawBits1 path 計算 src offset 對 12×12 字型 idx 算出來可能 out-of-range
- 或：12 寬度時，drawBits1 pitch = dest.pitch - width * bytesPerPixel 對 320x240 螢幕有寬度 alignment 問題
- 下一步：
  1. gdb 抓 crash 時 src 指標值，看是否 out of _2byteFontPtr 範圍
  2. 在 get2byteCharPtr 加 bounds check，idx out of [0,8178) 時返回 safe glyph
  3. 或 patch drawBits1 對 width != 8 用 separate code path

譯文中 GB18030 4-byte 字陷阱

UTF-8 → GBK encode 時，某些字會被擴展成 GB18030 4-byte 編碼（lead byte 在 0x81-0xFE 但跟 0x30-0x39 ASCII digit）。實際統計：

編碼	0xFE byte	0x5C trail
UTF-8	0	0
Big5	41	(未測)
GBK	89	多處（「運」「橋」等繁中字）
GB2312	29	0
GB18030	89	多處

GB2312 trail 範圍 0xA1-0xFE 不含 0x5C，最乾淨；但只支援 6763 簡體常用字，繁中譯文有 476 字 unencode 會變 ?。所以繁中專案實務上仍須用 GBK + 0x5C escape transformer。

Sandbox 副本快速參考

目錄	內容	狀態
`~/zak-zh/sandbox_en/`	英文 round-trip 驗證	LFL byte-perfect
`~/zak-zh/sandbox_final/`	GBK 譯文 + chinese_gb16x12.fnt	LFL 中文已寫入 + 字型備齊；ScummVM 開到對話框前 crash
`~/zak-zh/working/`	乾淨工作副本	原始（含產出的字型檔）
`~/zak-zh/original/`	Steam 完整快照	不動

立即可繼續的方向

加 bounds check 到 get2byteCharPtr — 最 minimal patch，避免 invalid idx 引起 segfault
用 valgrind 跑 scummvm 看詳細 memory access pattern
改用社群字型 — 自製字型可能有 layout 問題，社群 chinese_gb16x12.fnt 可能 layout 不同（pixel row 順序、stride 等）
試 Big5 編碼 + ZH_TWN 路徑 — 但 ZH_TWN 字型 chinese.fnt 是 16x15，要再做一份；同樣需 patch SCUMM v3 走 ZH_TWN

2026-05-20 下午後續

valgrind 抓到 root cause：get2byteCharPtr 對 FMTowns 早期 return nullptr（原本給 JA_JPN）。Patch（關鍵 fix）：

 if (!isScummvmKorTarget() && (_game.platform == Common::kPlatformFMTowns || _game.platform == Common::kPlatformPCEngine)
+    && _language != Common::ZH_CHN && _language != Common::ZH_TWN)
 	return nullptr;

Patch 後 ZH 版本能跑到 Mars+Earth 太空場景 + Dream sequence Zak+Annie 相遇，比之前多走 2 個場景。但更後面還有 silent crash，需繼續 debug。

ASCII-only 對照組（譯文中 byte >= 0x80 換成 ?）證明流程其他部分都對 — crash 純粹在 CJK render path。

8 處 patch 全清單見 PROGRESS.md。

2026-05-20 下午後續 3 — 中文完全顯示成功 ✨

兩個關鍵 fix 解決所有亂碼：

Fix 1: V3 renderer height hardcoded 為 8

// 原本 (charset.cpp line 893)
int CharsetRendererV3::getDrawHeightIntern(uint16) {
    return 8;  // ← CJK chr 也用這 → 12x12 字被截只剩上 8 rows
}

// Patch:
int CharsetRendererV3::getDrawHeightIntern(uint16 chr) {
    if (chr >= 256 && _vm->_useCJKMode)
        return _vm->_2byteHeight;  // ZH_CHN = 12
    return 8;
}

同樣 patch getDrawWidthIntern 對 CJK 返回 _2byteWidth。這是核心 root cause — 之前所有「亂碼」其實是 12x12 字 render 成 12x8（被截下半），加上 V3 8x8 spacing 算錯，看起來像橫條紋噪點。

Fix 2: 字型擴到 GBK 全 range

繁中字大多在 GBK 擴展區 (lead 0x81-0xA0)，原本 generator 只 cover GB2312 (lead 0xA1-0xFE)。

# build-zh-font-gbk.py — GBK 線性 index
def gbk_index(lead, trail):
    return (lead - 0x81) * 190 + (trail - 0x40 if trail < 0x7F else trail - 0x41)
# NUM_CHAR = (0xFE - 0x81 + 1) * 190 = 23940

對應 ScummVM 端 get2byteCharPtr ZH_CHN ZAK case 改用 GBK 線性公式。loadCJKFont 對 GID_ZAK 設 numChar = 23940。

字型選擇 — 設計師視角

12x12 點陣中文不易識別，需 careful 選字型：

字型	12px 效果	評語
Noto Sans CJK Regular	❌ 太細像噪點	不適
Noto Sans CJK Black	⚠️ 太粗筆畫融合	中央太擠
WenQuanYi MicroHei	✅ 清晰	推薦
WenQuanYi Zen Hei Sharp	✅ 點陣設計	也好
AR PL UMing TW	⚠️ 細明體偏細	對比度不夠

apt install fonts-wqy-microhei 後 /usr/share/fonts/truetype/wqy/wqy-microhei.ttc 是最終選擇。

2026-05-20 深夜 — 譯文 review + auto-wrap + verb 中文化嘗試

Auto-wrap 對話框（已 patch）

ScummVM 預設 addLinebreaks 只在「半形空格」處 break，中文無空格 → 不 wrap。Patch engines/scumm/charset.cpp 加 byte-level CJK break：

// CJK byte-level line break for ZH_CHN / ZH_TWN: every CJK char is a valid break point.
if ((_vm->_language == Common::ZH_CHN || _vm->_language == Common::ZH_TWN) && (chr & 0x80)) {
    lastspace = pos - 2;
}

Wrap 觸發條件：當行 curw > maxwidth。對 12x12 中文，maxwidth ~280-300px = 約 23-25 字一行。短句不 wrap，長句自動 break。

Dialog 高度限制 → 改用 click-to-continue（已解，2026-05-20 終夜）

對話框預設高度 16px（一行 ASCII 8x8 + margin）。CJK wrap 成 2 行 = 24px 時第 1 行會被頂到 viewport 上方外。曾嘗試 initScreens 把 text area 從 16→24px，但背景偏移 8px 整個畫面糊掉 → 撤回。

最終方案：把 wrap 點從 0x0D newline 改成 \255\003（end-of-message + 等 click），長對話自動分頁、不撞 main virtscreen。Patch engines/scumm/charset.cpp addLinebreaks() 對 ZH 路徑：

// CJK 模式下：wrap 點變成 \255\003 而非 0x0D
// 需插入 2 bytes (0xFF, 0x03)，把 lastspace 後面 memmove 右移
byte *breakPtr = str + lastspace;
int tail = strLength - lastspace + 1;  // +1 含 NUL
memmove(breakPtr + 2, breakPtr, tail);
str[lastspace] = 0xFF;
str[lastspace + 1] = 0x03;
strLength += 2;
pos = lastspace + 2;
lastspace = -1;

非 CJK 路徑仍走原 str[lastspace] = 0x0D。

Verb interface 中文化嘗試

譯文 verb 還原中文（推/拉/開/關/讀/拿起/是什麼等）
Patch engines/scumm/verbs.cpp drawVerb 對 ZH 加 row spacing：

if (_useCJKMode && _2byteHeight > 8 && _game.version <= 3
    && (_language == Common::ZH_CHN || _language == Common::ZH_TWN)) {
    int verbTopline = _virtscr[kVerbVirtScreen].topline;
    int rel = vs->curRect.top - verbTopline;
    if (rel >= 0) {
        int rowIdx = rel / 8;
        adjustedYpos = verbTopline + rowIdx * _2byteHeight;
    }
}

scummtr verb update 注意：-A aov 中的 v=verbs 是「保護不被改 size」flag。verb 中文短於英文要用 -A ao (不含 v) 才能 resize。

Verb hit-test 對齊（容易漏掉）：drawVerb 把 ypos 從 row*8 改成 row*_2byteHeight 後，findVerbAtPos 的 hit-test 必須做同樣的換算，否則點擊位置會錯位（看到的 verb 跟實際 hit 的 verb 不同 row）。curRect.top 仍保留原始 8-aligned 值，hit-test 端在 findVerbAtPos 重新算：

// engines/scumm/verbs.cpp findVerbAtPos
const bool cjkAdjustRow = _useCJKMode && _2byteHeight > 8 && _game.version <= 3
    && (_language == Common::ZH_CHN || _language == Common::ZH_TWN);
// 每個 verb 比對前：
int hitTop = vs->curRect.top;
if (cjkAdjustRow) {
    int rel = hitTop - verbTopline;
    if (rel >= 0)
        hitTop = verbTopline + (rel / 8) * _2byteHeight;
}
if (vs->curmode != 1 || !vs->verbid || vs->saveid || y < hitTop || y >= vs->curRect.bottom)
    continue;

已知問題：verb 中文化後 ScummVM 可能出現黑白條紋（palette 失效）—這是獨立問題，跟 verb 中文化「無關」(使用者觀察)，可能是某個 byte sequence 觸發 SCUMM v3 dual-layer mode 問題。需更深 debug。

譯文 review (677 行修訂)

Fork agent 後 review 對話品質，產出 /tmp/zh_review.txt 677 行修訂套用 484 個改動。包括：

人名統一：Zak→札克, Zachary→札克瑞, Annie→安妮, Melissa→梅麗莎, Leslie→萊絲莉, Jayne→珍, Sally→莎莉, Sandy→珊蒂, Ed→艾德, Edna→艾德娜
招牌笑話保留：The King→貓王, Caponian→卡彭星人, Skolarian→斯科拉里安
媽媽電話對話更口語親切
Boss 對話嚴肅口吻
報紙標題保留 tabloid 噱頭
卡彭星人對話帶誇張戲謔

SCUMM 控制碼速查

序列	意思
`\255\001`	換行 (newline)
`\255\002`	等待繼續顯示
`\255\003`	暫停等用戶 click
`\255\004\XX\YY`	顯示變數值
`\255\005\XX\YY`	切換顏色
`\255\006\XX\YY`	插入物件名
`\255\007\XX\YY`	插入 actor 名

Sandbox import 重要 quirks

cp 不覆蓋已存在 executable mode files — 用 rsync --delete 或 rm -f *.LFL + cp -f
scummtr -if 中途 fail 會 partial-modify LFL — 之後再 import 撞 stale state，先 rm + cp fresh
scummio-tmp 殘留 — import 失敗會留下 *.LFL~~scummio-tmp，下次 import 報「already exists」，要 rm -f *scummio-tmp
-A aov 保護 verb size — verb 中文短於英文，要去掉 v flag (用 -A ao)
譯文編碼：用 text.encode('gbk', errors='replace') + 0x5C escape transformer + CRLF 行尾 + scummtr -rwh -A ao -if

字型 generator 演進

build-zh-font.py v1：Noto Sans CJK Regular 12px → 太細像噪點
build-zh-font.py v2：Noto Sans CJK Black 12px → 太粗筆畫黏
build-zh-font.py v3：GBK 全 range (擴 23940 字) 解決繁中字漏
build-zh-font-wqysharp.py 最終版：freetype 直接 access WenQuanYi Zen Hei Sharp face 2 embedded bitmap (12px) — 真實點陣字，清晰可讀

字型載入：face = freetype.Face(path, 2); face.select_size(0) (face 2 = Sharp variant, size 0 = 12px)

譯文版本演進

檔案	內容
`/tmp/zh_test.txt`	原 AI 翻譯草稿（無還原）
`/tmp/zh_full.txt`	verb sections 英文還原（section-level）
`/tmp/zh_line.txt`	line-level 英文還原（<12 char 短句保留英文）
`/tmp/zh_polished.txt`	+ 人名中譯 + 19 處短譯文 polish
`/tmp/zh_final.txt`	+ 484 個 review 修訂套用 ← 當前最佳
`/tmp/zh_verb_zh.txt`	+ verb 中文化（會撞黑白條紋 — 待 fix）

對應 GBK encoded 版各有 _gbk.txt 後綴。Import 命令：

rsync --delete -av ~/zak-zh/working/ScummVM/enhanced/ ~/zak-zh/sandbox_final/
cp /tmp/zh_final_gbk.txt ~/zak-zh/sandbox_final/scummtr.txt
cd ~/zak-zh/sandbox_final/
rm -f *scummio-tmp
~/zak-zh/tools/scummtr-src/build/bin/scummtr -g zaktowns -rwh -A aov -if

跑 ScummVM：

systemctl --user reset-failed
systemd-run --user ~/zak-zh/tools/scummvm-src/scummvm \
    --no-aspect-ratio --no-fullscreen zak-fm-cn

2026-05-20 晚 — 終局最佳配置 🎉

8 處 ScummVM patch + WQY Zen Hei Sharp embedded bitmap 字型 + line-level 譯文還原 = 可玩 Zak 中文版！

✅ 對話框中文清晰：「我應該把夢裡看到的地圖畫下來。」可讀
✅ 彩色畫面 (TownsV3 renderer 保留 dual-layer)
✅ Verb interface 英文整齊（avoid 12px 中文擠 verb area）
✅ Inventory items 英文（avoid 擠）
✅ 字型 12x12 點陣（WQY 真實 embedded bitmap，非 PIL outline rasterize）

字型 — 用 freetype-py 直接 access embedded bitmap：

# build-zh-font-wqysharp.py
face = freetype.Face('/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc', 2)  # face 2 = Sharp
face.select_size(0)  # 12px embedded bitmap
face.load_char(ch, FT_LOAD_RENDER | FT_LOAD_MONOCHROME | FT_LOAD_TARGET_MONO)
# baseline 對齊：dst_y_start = 10 - face.glyph.bitmap_top

PIL TTF outline 12px 渲染太細變雜訊；WQY Sharp 真實點陣 → 設計師手繪 12x12，清晰許多。

譯文 — line-level 還原英文：

# 對每行單獨判斷，不是整 section
en_stripped = stripped_len(en_content)  # 去 @ padding
is_short_en = (en_stripped < 12 and not '\\255' in en_content)
if is_short_en:
    用英文  # verb names, short interactions, "I'll keep it." 等
else:
    用中文  # 長對話、新聞標題、敘述

避免坑點：

scummtr -if 中途 fail 後會 partial-modify LFL。每次 import 前 cp -f 強制覆蓋所有 *.LFL
cp -r 對已存在的 file 可能不覆蓋，要 rm -f + cp 或 cp -f
TownsV3 renderer 必須保留（不能改用 V3），否則 FM-Towns dual-layer color 失效 → 黑白條紋
verb sections 整 section restore 英文太 aggressive — 會把對話也還原英文。要 line-level 判斷
_2byteWidth/Height 對 V3 path 必須返回 _2byteWidth/Height，而非 hardcoded 8

完整 patch 清單 (2026-05-20 終版)

ScummVM (engines/scumm/)：

charset.cpp loadCJKFont — GID_ZAK 進 ZH_CHN 白名單，numChar = 23940 (GBK 全 range)
charset.cpp get2byteCharPtr — 對 FMTowns + ZH_CHN/ZH_TWN 不再 early return null；ZAK case 用 GBK 線性 index
charset.cpp CharsetRendererV3::getDrawWidthIntern — CJK 返回 _2byteWidth
charset.cpp CharsetRendererV3::getDrawHeightIntern — CJK 返回 _2byteHeight (最關鍵)
charset.cpp CharsetRendererTownsV3::getDraw*/drawBits1 — 移除 assert(_cjkFont) (備用，因為改用 V3 renderer 後不會走這路徑)
string.cpp drawString — ZH 模式跳 v3 SCUMM 0xFE escape
scumm.cpp setupCharsetRenderer — ZH FMTowns 用 V3 (不是 TownsV3)

scummtr (src/ScummTr/text.cpp)： 8. funcLenSafe — CJK lead 後未知 byte 視為字面而非錯

字型 (~/tmp/zak/build-zh-font-gbk.py):

WenQuanYi MicroHei 12px
GBK linear index (lead 0x81-0xFE × trail 0x40-0xFE 跳 0x7F)
23940 字 / 574 KB

譯文編碼：UTF-8 → GBK + CRLF + 0x5C escape transformer

scummtr 命令：-rwh -A aov -if (raw mode + CRLF + 確認 verb safety)

2026-05-20 下午後續 2 — 突破到房間 + 中文亂碼根因

加 systemd-run --user 真 detach 跑 valgrind 後發現 ScummVM 沒 internal crash — 整個流程通了！

進度：

✅ Title → intro → dream → room 001 (Zak 房間) 完整跑出來
✅ Verb interface 顯示 (Push/Pull/Open 等)
✅ Zak 可以走動 + cursor 工作
❌ inventory + 對話框中文「亂碼」 — 用 Black Noto Sans CJK 重 render 也沒救

亂碼根因（剛找到）：

譯文 byte stream 統計：

GB2312 lead 範圍 (0xa1-0xfe)：8923 byte ✓
GBK 擴展 lead 範圍 (0x81-0xa0)：1109 byte ← 我自製字型沒覆蓋
Other：0

我的 build-zh-font.py 只 render GB2312 (8178 字)，但譯文中 1109 個 byte 對應 GBK 擴展字 (0x81-0xa0 lead)。ScummVM 的 ZH_CHN idx 公式 (lead-0xa1)*94 + (trail-0xa1) 對 lead < 0xa1 算出負數，patch 的 bounds check 把它 clamp 到 idx=0 → render 同一個 glyph → 看起來像「噪點/亂碼」。

解法（下次接續）：

擴充 generator cover 完整 GBK (lead 0x81-0xFE, ~23940 字)，並 patch ScummVM 公式：

// ScummVM 公式需從「GB2312 區位碼」改成「GBK 線性 index」
case Common::ZH_CHN: {
    int lead = idx % 256;
    int trail = idx / 256;
    // GBK 線性 index (0x81-0xFE × 0x40-0xFE 但跳 0x7F)
    int t = trail - (trail < 0x7F ? 0x40 : 0x41);
    idx = (lead - 0x81) * 190 + t;
}

字型檔變大 ~24x 大 (4.5 MB)，需要 patch loadCJKFont 設 numChar 對應

或譯文預處理：把 GBK 擴展字替換成 GB2312 內近似字 (用 OpenCC 簡繁轉換工具)
或用 GB18030 4-byte 編碼：但 ScummVM 沒有 GB18030 路徑

當前 sandbox 狀態（下次接續位置）

~/zak-zh/sandbox_final/ — minimal 譯文 + chinese_gb16x12.fnt (Black, 12x12 GB2312 only)
~/zak-zh/working/ScummVM/enhanced/chinese_gb16x12.fnt — 同上
~/zak-zh/tools/scummvm-src/ — patched (8+ 處 patch in charset/string/scumm.cpp)
~/zak-zh/tools/scummvm-src/scummvm — patched binary 可跑
~/zak-zh/tools/scummtr-src/build/bin/scummtr — patched scummtr (funcLenSafe)
ScummVM config: ~/.config/scummvm/scummvm.ini target zak-fm-cn 指向 sandbox_final

跑命令：

DISPLAY=:1 systemd-run --user \
    ~/zak-zh/tools/scummvm-src/scummvm \
    --no-aspect-ratio --no-fullscreen zak-fm-cn

debug log:

~/zak-zh/debug-dream.sh  # valgrind wrapper

Files 在 `~/tmp/zak/`

PROGRESS.md — 詳細進度
scummvm-zhtw.patch — 原始三處 patch (v1)
scummvm-zhtw-v2.patch — 最新合併 patch (8 處改動，含關鍵 get2byteCharPtr fix)
scummtr-cjk.patch — scummtr CJK-tolerant funcLenSafe patch
install-deps.sh — sudo apt install script
build-zh-font.py — Noto Sans CJK 12×12 字型 generator
test-zh.sh — 回填 + 試跑 script

物件名批次翻譯（2026-05-20 晚）

scummtr -of dump 出來譯文中 verb 上方的 ON (object name) / OC (object class) sections 是英文。逐筆翻成中文太慢；用 dict patch 一輪一輪自動取代：

Dump 譯文檔（/tmp/zh_verb_zh.txt）裡所有 ON/OC 英文短句抽出來
AI 一次翻譯成中文 dict（"door" → "門", "rock" → "石頭" 等）
Python script 對譯文檔做 replace（要小心避開已是中文的部分）
Re-encode UTF-8 → GBK + 0x5C escape → CRLF
Import 到 ~/zak-zh/sandbox_final/
跑遊戲檢查，補翻沒覆蓋到的 token
重複 3-4 輪直到只剩冷僻 token

實測 4 輪後 359 個英文 ON/OC 翻到剩 15 個（多是含 \255 控制碼的 Y A K - 1 等特殊名）。tool 在 ~/zak-cht/tools/translate-objects.py。

Release repo `~/zak-cht/`

對外發佈 git repo（origin: git@github.com:wicanr2/zak-cht.git）。

zak-cht/
├── README.md
├── LICENSE              MIT for original work
├── NOTICE.md            版權合規說明
├── docs/                5 篇中文 docs（patch清單/字型方案/控制碼速查/編碼import/進度）
├── patches/
│   ├── scummvm-zhtw.patch
│   └── scummtr-cjk.patch
├── tools/
│   ├── build-zh-font-wqysharp.py
│   ├── encode-gbk.py
│   ├── translate-objects.py
│   └── import-to-game.sh
├── translations/zh_verb_zh.txt
├── screenshots/
└── vendor/
    ├── scummvm/         GPLv3+ — 修改過的 charset.cpp / string.cpp / verbs.cpp / scumm.cpp
    │                    + COPYING + AUTHORS + MODIFICATIONS.md
    │                    (上游 commit f4526cf007688d02b8c558f048f0889088545fd5)
    └── scummtr/         MIT — 修改過的 text.cpp

版權合規關鍵：因為 release 包內含修改過的 ScummVM binary（GPLv3+），必須附 source；放在 vendor/scummvm/ + MODIFICATIONS.md 滿足 GPL「accompanying source」要求。

Release 包（不在 git 內，太大）：~/zak-cht-build/

zak-cht-linux-x86_64.7z (82 MB) — patched ScummVM binary + game data
zak-cht-linux-x86_64.AppImage (95 MB)
zak-cht-windows-x86.7z (64 MB) — MinGW i686 cross-compile

Windows cross-compile：scummvm-win-src/ configure 時加 --host=i686-w64-mingw32，deps 在 ~/zak-cht-build/mingw-deps/。注意 make distclean 後要重 build Linux binary（同 source tree 切換 target）。

name	zak-fmtowns-zhtw
description	Zak McKracken (FM-Towns Steam 版) 繁中化的完整工具鏈、編碼陷阱與 ScummVM patch 點。當使用者談到「Zak McKracken」「Zak 中文化」「scummtr 不認 CJK」「Unknown function id 0xAB / 0xCF」「Truncated escaping」「FM-Towns 中文」「SCUMM 中文化」「chinese_gb16x12.fnt」等情境觸發。

zak-fmtowns-zhtw

More from this repository

More from this repository

Zak McKracken FM-Towns 繁中化完整 SOP

工作目錄結構

版本辨識（FM-Towns vs PC V2）

工具鏈速查

⭐ scummtr CJK 突破（最非顯然的發現）

可運作的命令

編碼選擇與 0xFE 衝突

ScummVM patch 點（路線 B）

Patch 1: engines/scumm/charset.cpp line ~126

Patch 2: engines/scumm/string.cpp line ~1487

ScummVM build

字型檔 chinese_gb16x12.fnt

跑遊戲

已知陷阱清單

翻譯草稿

工時估算

2026-05-20 PoC 實測結果

已驗證通的部分

已知未解 issue

譯文中 GB18030 4-byte 字陷阱

Sandbox 副本快速參考

立即可繼續的方向

2026-05-20 下午後續

2026-05-20 下午後續 3 — 中文完全顯示成功 ✨

2026-05-20 深夜 — 譯文 review + auto-wrap + verb 中文化嘗試

譯文版本演進

2026-05-20 晚 — 終局最佳配置 🎉

完整 patch 清單 (2026-05-20 終版)

2026-05-20 下午後續 2 — 突破到房間 + 中文亂碼根因

當前 sandbox 狀態（下次接續位置）

Files 在 ~/tmp/zak/

物件名批次翻譯（2026-05-20 晚）

Release repo ~/zak-cht/

相關 skill / 檔案

Zak McKracken FM-Towns 繁中化完整 SOP

工作目錄結構

版本辨識（FM-Towns vs PC V2）

工具鏈速查

⭐ scummtr CJK 突破（最非顯然的發現）

可運作的命令

編碼選擇與 0xFE 衝突

ScummVM patch 點（路線 B）

Patch 1: engines/scumm/charset.cpp line ~126

Patch 2: engines/scumm/string.cpp line ~1487

ScummVM build

字型檔 chinese_gb16x12.fnt

跑遊戲

已知陷阱清單

翻譯草稿

工時估算

2026-05-20 PoC 實測結果

已驗證通的部分

已知未解 issue

譯文中 GB18030 4-byte 字陷阱

Sandbox 副本快速參考

立即可繼續的方向

2026-05-20 下午後續

2026-05-20 下午後續 3 — 中文完全顯示成功 ✨

2026-05-20 深夜 — 譯文 review + auto-wrap + verb 中文化嘗試

譯文版本演進

2026-05-20 晚 — 終局最佳配置 🎉

完整 patch 清單 (2026-05-20 終版)

2026-05-20 下午後續 2 — 突破到房間 + 中文亂碼根因

當前 sandbox 狀態（下次接續位置）

Files 在 ~/tmp/zak/

物件名批次翻譯（2026-05-20 晚）

Release repo ~/zak-cht/

相關 skill / 檔案

Patch 1: `engines/scumm/charset.cpp` line ~126

Patch 2: `engines/scumm/string.cpp` line ~1487

字型檔 `chinese_gb16x12.fnt`

Files 在 `~/tmp/zak/`

Release repo `~/zak-cht/`

Patch 1: `engines/scumm/charset.cpp` line ~126

Patch 2: `engines/scumm/string.cpp` line ~1487

字型檔 `chinese_gb16x12.fnt`

Files 在 `~/tmp/zak/`

Release repo `~/zak-cht/`