> 最新:已納入原始資料實際存在的全部 73 個 room,含龍穴後方 65/30 山洞及後段場景。操作與驗證範圍請見 [VM 連續測試說明](../../web/scumm/README.md)。下文的舊範圍與手動轉譯/交接說明保留作歷史紀錄,以新文件為準。 # LOOM 開場資源與 Node.js 原型 本次範圍為 room 01(320×144)、room 02(960×144),以及開場中途的 room 53 特寫(320×144)。圖片檔保留原始尺寸。瀏覽器內使用 320×200 邏輯畫布,其中上方 144 列為場景;CSS 提供 2~5 倍像素放大。 ## 啟動 ```bash npm start ``` 打開 http://127.0.0.1:3137 。Node.js 20 以上,不需安裝 npm 套件。可用 `PORT=另一埠號 npm start` 更改埠號。 也可直接開啟 `web/standalone.html`:已內嵌原始尺寸的 720 張 PNG、索引與全部 62 個音訊 MP3(約 39MB),無需伺服器、網路或模組載入。兩種執行方式使用相同的 app/core/audio/scumm 原始碼;另包含原始 LFL。 ## 操作 - 預設從 room 01 重播片頭;「重播開場」可重新開始,「進入 room 02」或 Esc 跳過。 - 「顯示倍率」只改畫布顯示大小;「播放速度」控制遊戲時間;空白鍵/暫停鈕可停住演出。 - 探索模式可拖動鏡頭中心滑桿,看完整 960 像素場景。互動區/行走線可切換顯示。 - hover 或鍵盤 focus 至 leaf/sky 時,右下角顯示原始圖像;單擊選取、走近並顯示名稱,雙擊觸發原始 0x36 查看事件。也可用表格按鈕選取,再按事件測試。 - 出口事件(object 153 / 0x38)追到 room 03 便停止;天空開啟事件追到 global 49 的跨場景依賴便停止。 - 事件測試是研究用直接呼叫;法杖與旋律在開場尚未解鎖,這些測試不是原作的遊戲操作選單。 - 「啟用音樂/音效」可接續播放原始開場音樂;選單提供 31 組資源的 AdLib/Tandy 版本,按「試聽(1×)」比較原速。詳見 `audio/README.md`。其餘遊戲音效事件尚未全部自動接回。 右下角圖示與名稱的位置來自 global 8/7:圖像 (248,152),名稱 (272,181)。擷取器從物件 0x39 handler 的 `Var[104]` 指定值讀出圖示 ID,因此 leaf 使用 object 158,sky 使用 object 159。hover 不會觸發走路或查看;未選取時離開會清除,選取後則保留,換場、重播或落葉後清除。名稱依本次需求在單擊時立即顯示,原 G7/G8 的距離判定仍未完整移植。 ## 放大文字 對話與底部提示改由獨立 DOM 文字層繪製,不經過低解析度 Canvas 放大。對話字級隨顯示倍率變成 16/24/32/40 CSS px,由瀏覽器直接按螢幕密度描繪,保留原腳本文字、換行、置中與位置對應,並加上陰影以提高場景上的辨識度。文字層不攔截滑鼠事件,也會跟隨暫停與台詞到期狀態。 使用本機等寬字型,不需網路;這是清晰字體替換,尚未還原原始 `99.LFL` 字型。背景、角色與 LOOM 標題圖仍保留原始像素資產。伺服器版重新整理頁面即可;離線版請使用最新 `web/standalone.html`。 ## 已擷取 | 產物 | 數量/內容 | |---|---| | room 背景 | 3 張,沿用 `analysis/backgrounds/room-01.png`、`room-02.png`、`room-53.png` | | 原始物件資料 | 89 個:room 01 為 53 個,room 02 為 7 個,room 53 為 6 個,room 69 為 23 個 | | 物件圖 PNG | 74 張,包含 room 53 的 765~770 | | 遮罩 PNG | 78 張:4 個 room 與 74 個物件的 z-plane;alpha 255 代表阻擋角色像素 | | costume | 11 組:1/2/3/4/5/6/7/8/141/150/164 | | 透明 cel PNG | 332 個;每個保留原尺寸、relX/relY、moveX/moveY、動畫 limb 序列與控制碼 | | 本地腳本 | room 01 的 200~211;room 02 的 200~222;room 53 的 200~201,加上 room 69 的 200~205,共 43 個 | | room 進出腳本 | 每 room 各一份 entry/exit,共 6 份 | | 物件事件腳本 | 89 份,沒有事件的資源仍保留原始 code header | | 全域腳本候選 | 116 份:115 份 descumm 成功;global 116 無法可靠解碼,保留診斷結果,不能視為已還原 | | 行走幾何 | room 01 為 1 個 walkbox;room 02 為 15 個,含原始 mask/flags | `resources.json` 是機器可讀索引,記錄來源 LFL、位址、尺寸、事件入口、動畫序列與圖檔位置。 `interactions.md` 列出全部 89 個物件。`scripts/*.txt` 是原始反組譯結果,`scripts/*.bin` 是供 descumm 使用的輸入。 注意:全域、entry/exit、本地腳本的 `.bin` 有工具額外加入的 4-byte 零標頭,後面才是原始 bytecode;物件 `.bin` 保留原始完整 code resource。反組譯的全域/本地/進出腳本 offset 從 bytecode 第一個 opcode 計算;物件 offset 則相對其 code resource。 ## 還原出的腳本結構 1. `global-001.txt` 為 bootstrap:畫面 0~144、字型/游標、全域腳本掛鉤、音源資源,先進 room 69,再呼叫 global 44。room 69 不在本次範圍。 2. `global-044.txt` 是開場主導流程:room 01 星空/標題、room 02 海景鏡頭與信使、room 53 特寫、再回 room 02 讓主角醒來,交還控制。 3. room 01 entry 只在初始化旗標未設時啟動 local 211。local 211 建立音符介面並產生旋律初始值;local 200~209 是星光、210 是七個天鵝 actor 的飛行。 4. room 02 entry 建立 costume 141 的環境動畫,條件性建立 leaf actor。local 200 設 leaf actor 的 costume 8、位置 (807,25);201 控制信使離場;202 讓主角朝向信使。 5. global 6/7 負責滑鼠定位、走近、雙擊與物件事件派送。物件 154 `leaf`:0x36/41/42 會觸發落葉與「Last leaf of the year.」;物件 156 `sky`:0x36 回應「Dawn.」,0x3A 呼叫 global 49。 6. global 45 另處理 walkbox 4/5/10/11 的換層/重新定位。原型已轉譯這四個分支,並依 global 17 切換 costume 1/2/3,使用原始大/中/小圖塊和各自步速。不是依 y 座標猜測縮放比例。 ### 回程岩石缺口 回程的 `putActor(890,118)` 是原腳本已有的山後定位;後面的行走必須經過原始 box 3→2→1→0,不能直接連到山上終點。原型已修正為逐段走到 box 出口/入口,並在入口處才更新人物的 mask;上坡期間會從缺口逐漸露出頭與上身。box 3 的 `0x12` 朝向旗標也會選取原始正面走路圖格。 換層強制行走期間暫停其他換層判斷與新點擊目的地,保留原始等待和站姿,再回到正常路徑。`validation/return-rock-gap.png` 提供六格原始像素合成檢查;它不是瀏覽器截圖。原型仍是本場景的腳本轉譯,未宣稱完整移植通用 SCUMM 尋路矩陣。 room 02 的 153/154/156 共享其他物件的 image pointer,但它們的熱區尺寸與該圖像 strip table 不相符;應當作邏輯熱區,不能把共享圖像以熱區尺寸解碼。物件 155/157 為場景狀態疊圖,158/159 為 leaf/sky 的介面圖示。 ## 原型的精確範圍 `web/app.mjs` 是對反組譯結果的**手動轉譯子集**,不是執行整份原始 bytecode 的 SCUMM VM。它使用原圖、真實 cel 與動畫序列,按原始座標重播選定演出。紀錄以 G44、R1:L210 等標記來源。 以下仍是近似或未實作:精確 SCUMM 排程/動畫控制碼、副作用及 limb 狀態繼承、音源與音樂計時分支、原字型、調色及通用尋路。已重建這個場景的換層連線,但尚未解析通用 SCUMM 路徑矩陣。圖塊透明色已分離,但未完成所有角色 palette 的逐場景重映射。 room 53 特寫已加入背景、主角 765→766→767 姿態、768/769/770 嘴部動畫,以及信使浮動、離開與飛回的演出,並顯示四段原始台詞。開天、出口轉場仍會報告依賴。下一階段應決定做真正的 SCUMM VM 子集或持續以可驗證的場景規格重寫,並與原作執行結果逐段對照。 ## 星光與遮罩修正的依據 - 原腳本先以 animateCostume(250) 設為 old direction 2;因此星光 frame 6 對應 costume 動畫 index **26**。index 24/25 是空白狀態,這是上一版沒有閃爍的原因。 - 初次星光使用 global 44 的兩組座標;標題及後續鏡頭則啟動 global 113/114 的兩組不重複隨機點,直到進入特寫前停止。等待仍以固定遊戲時間近似。 - room/object 的 bitmap 長度後面接 old-bundle z-plane:每條 strip 的 16-bit offset 指向 mask RLE;每個 bit 為一像素,1 表示阻擋。此資料直接來自 LFL,不由顏色或人工字形推導。 - 標題 actor 的 class 149 為 AlwaysClip,套用 object 152 的遮罩;星光 class 148 為 NeverClip。岩石與樹的遮擋依 walkbox mask 選擇 room 02 的 z-plane。 - Canvas 先將單個角色組合到透明暫存層,再以 `destination-out` 移除被遮罩阻擋的像素,最後合成至畫面;避免把其他角色或背景一起裁掉。 ## 工具與重建 ```bash # 原始全目錄索引與背景分析,需 Python 3 + Pillow python3 tools/inspect_loom.py # 編譯 descumm、擷取開場資源、重建離線 HTML # 另需 Linux little-endian 環境與 g++ npm run extract # 只更新離線 HTML,不重做擷取 npm run standalone # Node.js 測試,不需瀏覽器或監聽連接埠 npm test # 直接檢查原始 PNG 像素、mask 方向與遠近圖塊(需 Pillow) npm run test:assets ``` 上游 descumm 原始碼及 GPL 授權保留於 `tools/vendor/scummvm-tools/`,檔案 SHA/來源在 `SOURCES.json`;編譯器輸出 `analysis/tools/descumm`。 ## 驗證紀錄 2026-11-15:7 個 Node.js 測試通過,驗證 2/3/5 倍點擊座標、原始行走線投影、動畫循環/停格、332 個 cel PNG 的尺寸及引用、全部原始檔 SHA-256、HTTP handler 的資源/路徑限制,以及完整開場狀態機與 leaf/sky/出口事件。 狀態機測試使用 Node.js 的 DOM/canvas mock,**不是瀏覽器測試或視覺驗收**。初版環境以 EPERM 拒絕本機 TCP 監聽,Browser URL policy 另拒絕 file URL。後續使用者已自行啟動伺服器;本次瀏覽器控制連線回報 timeoutMs 介面錯誤,仍未完成瀏覽器互動驗收。 本次新增驗證:7 個 Node 測試通過(包含實際進入 room 53、多格星光、主角往返 1→2→3→2→1 costume);另 4 個 Pillow 像素/資產測試通過。`validation/title-mask-flight.png` 是以原始圖塊及 mask 合成的飛行軌跡檢查圖,不是瀏覽器截圖。 回程岩石缺口修正後:8 個 Node 測試與 5 個 Pillow 像素/資產測試通過,涵蓋沿坡行走、遮罩切換時機、原始朝向旗標及人物逐漸露出;DOSBox/瀏覽器逐幀時序仍待對照。 ## 主要參考 - https://github.com/scummvm/scummvm/blob/master/engines/scumm/resource_v3.cpp — v3old 索引與字型。 - https://github.com/scummvm/scummvm/blob/master/engines/scumm/room.cpp — room 資料、進出/本地腳本、walkbox。 - https://github.com/scummvm/scummvm/blob/master/engines/scumm/object.cpp — 物件標頭、位置與圖片/事件。 - https://github.com/scummvm/scummvm/blob/master/engines/scumm/costume.cpp — 舊 costume 動畫與 limb。 - https://github.com/scummvm/scummvm/blob/master/engines/scumm/base-costume.cpp — cel RLE 與舊版 (-72,-100) 繪製原點。 - https://github.com/scummvm/scummvm/blob/master/engines/scumm/boxes.cpp — walkbox 結構。 - https://github.com/scummvm/scummvm/blob/master/engines/scumm/gfx.cpp — EGA strip 與 mask。 - https://github.com/scummvm/scummvm-tools — descumm;本次使用 `-3u -o`。 - https://github.com/scummvm/scummvm/blob/master/dists/emscripten/README.md — 既有引擎的瀏覽器建置替代方向。