kol-remake-cht

Imported from wicanr2/kol-remake-cht (AGENTS.md). Install upstream with npx skills add wicanr2/kol-remake-cht. Copyright stays with the author.

《武士傳說》繁體中文重製專案

本專案以 Origin Systems 的 Knights of Legend（本文暫稱《武士傳說》）為研究 對象，使用 Go 與 Ebitengine（套件路徑仍為 github.com/hajimehoshi/ebiten/v2） 進行乾淨重寫。目標是保存原作可驗證的規則與氣氛，改善現代平台上的操作與可讀性， 並提供繁體中文遊戲與說明文件。

不可違反的作業規則

1. 所有分析、解包、轉檔、建置、測試、遊戲執行、抓圖、音訊、DOSBox、Xvfb、 IDA 與 GUI 自動化只能在 Docker 容器中進行。一次性工作使用 docker run --rm， 設定 --memory、--cpus、--pids-limit 與外層逾時，預設 --network none。
2. 原版封裝、說明書與研究輸入唯讀掛載。可寫容器必須使用目前使用者 UID/GID； 寫入前後檢查擁有權，不得產生 root-owned 專案檔案。
3. 主機只作 docker、git、GitHub 控制面、工作樹狀態檢查與儲存庫檔案編輯。
4. 每批工作後檢查並移除本專案不再需要的容器；不得清理其他專案資源。每輪交接都 要記錄容器、檔案擁有權與暫存產物狀態。
5. 開工先讀本檔與 WORKLIST.md，再檢查 git status --short。現有異動一律視為 使用者或前一工作階段所有，不得重設或覆蓋。

原始輸入與權利邊界

目前根目錄中的下列檔案是研究輸入，不得提交到 GitHub：

• Knights-of-legend.zip
• knightslegend-manual.pdf
• knightslegend-refcard.pdf
• KOL-MAP-001a4s2.jpg
• knightslegend.jpg
• knightslegend-back.jpg

開始研究時先在唯讀容器中建立檔案清冊、大小與 SHA-256，辨識 DOS 版本、執行檔、 資料檔、驅動程式及封裝來源。公開程式碼授權不涵蓋原版執行檔、資料、美術、地圖、 音樂、音效、商標或其轉換產物。所有素材都要分成「可公開」、「private GitHub 可保存」、 「僅本機」與「來源／權利未知而拒絕發布」四類。

本專案經使用者於 2026-09-01 明確決定，允許把從固定原版輸入可重生、已通過格式與視覺 驗證的 PNG 衍生物提交到目前的 private GitHub 儲存庫，並於同日再決定原版執行畫面的 截圖 PNG 同樣適用。此例外只適用 PNG，不包含原版 ZIP、EXE、archive、PDF、地圖、盒面、 原始音訊、反組譯 payload 或未驗證圖片；也不等於取得公開散布權。抽取器產生的素材 PNG 放在 assets/original-derived-png/；由模擬器擷取的執行畫面 PNG 與其收據同目錄放在 docs/verification/，因為收據以相對路徑索引畫格。兩者都必須隨附來源 entry、 來源 SHA-256、抽取器／版本、圖號或畫格編號、PNG SHA-256、證據狀態與權利分類 manifest。儲存庫若 轉為 public、建立 public fork、GitHub Release 或公開 dist-all/.../release/，必須先停止 並重新做權利審查；不得把 private repo 決策自動延伸成公開授權。

2026-10-17使用者另明確要求儲存庫轉為public，正式遊戲用HD素材全部收錄GitHub。 此新決定取代先前僅private保存的操作限制，範圍包含既有儲存庫及其歷史。 目前公開方式、逐檔清冊與遠端回讀以公開化審查 及公開化清冊為準。 舊素材manifest與收據的private文字及原雜湊保留。此決定不授予原作權利，原作散布 授權仍未確認；RRSAL-1.0與第三方條款保持。原始ZIP、EXE、PDF、WAV及生成原稿 不因此加入Git，完整版與影片仍留本機。可見度核對入口為tools/check_repo_visibility.sh， 依本次決定接受public，查詢失敗或其他可見度即停止。

專案起源與玩家觀點研究

建立或更新 README.md 的「專案起源」時，必須先查詢並閱讀魔旅士及其他華人老遊戲 玩家的部落格、論壇文章、中文評介與回憶。搜尋至少同時使用中文名稱、英文名稱、作者 名稱與可能的舊譯名；保存文章標題、作者、網址、發表／存取日期及重點摘要。

• 玩家心得用來說明本專案為何值得重製、玩家記得什麼，以及哪些摩擦最影響體驗。
• 心得、攻略與二手評介不可直接當作原版規則證據；規則仍須由說明書、原始資料、 IDA 交叉參照或可重現的原版實驗證實。
• 找不到具名文章時，要記錄查過的關鍵字與日期並標為待查，不可猜作者、拼湊引文或 把搜尋摘要冒充原文。
• 引用只能作短摘錄或摘要，附直接連結並遵守合理引用；README 不複製整篇文章。
• 華人玩家常提到的優點與痛點要轉成「待驗證的玩家體驗假說」，再由原版遊玩與 可丟棄原型確認；不可未經決策就改寫戰鬥節奏或忠實度目標。

技術與素材契約

Go／Ebitengine

• 正式重製版使用 Go 與 Ebitengine；核心規則不得依賴畫面更新頻率。
• 分層保持單向：cmd／平台與 UI → 遊戲適配器與規則 → typed data；解析器、規則、 呈現、輸入、音訊與存檔應可獨立測試。
• 亂數、時間與輸入必須可注入、可重播。正式玩家路徑不可依賴 direct-entry、座標注入、 強制勝利或測試旗標。
• 鎖定 Go、Ebitengine 與建置 image 版本；開發與發行命令都要能在 Docker 重現。

圖像

• 原版圖像必須由可重現的抽取工具轉成 PNG；runtime 只讀 PNG，不得在執行時解析 原版 archive、EXE、專有圖片格式或直接讀取原版封裝。
• 抽取器與 runtime 分離。每批轉換保存來源檔、來源 SHA-256、工具版本、命令、索引／ palette 規則、輸出 manifest 與 PNG SHA-256。
• 用 archive count、offset、尺寸、色盤、透明色與 atlas／接觸表驗證素材；檔案存在或 大小可整除不等於解碼正確。越界、格式不符或缺檔必須失敗即關閉。
• 已驗證的原作衍生PNG依上述現行公開化決定及來源清冊保存於 assets/original-derived-png/；未驗證PNG仍只留本機。release/維持引擎包與合法 資料匯入／抽取流程，不因儲存庫可見度改變而加入原始資料或完整版。

音樂與音效

• 正式 runtime 的音樂、語音與音效一律使用 Ogg Vorbis（.ogg）；WAV、PCM、MIDI、 晶片 dump 或原始 driver 資料只作來源、研究 oracle 或轉換中間檔。
• 每批 OGG 保存來源、來源權利分類、轉換參數、codec／quality、取樣率、聲道、時長與 SHA-256，並驗證可解碼、非靜音、峰值、循環接點及實際聆聽。
• 轉成 OGG 不會改變原版素材的著作權；未獲授權的音訊不得提交或公開發布。
• DOS DAC／PIT／DMA 等硬體時序採公開規格與成熟模擬器的合理近似，標為 hardware-spec approximation；玩家可見 cue 與等待播放完成控制流證實後即停止， 不追求硬體逐週期一致。

中文說明書

• 將 knightslegend-manual.pdf 與 knightslegend-refcard.pdf 逐頁翻譯為繁體中文 Markdown，正式入口放在 docs/manual/README.md，並保留章節、表格、圖說、頁碼與 原文對照定位。
• 先記錄來源檔 SHA-256、總頁數、OCR／擷取工具及版本；OCR 文字只是草稿，需逐頁人工 校對。無法辨識、版權聲明與專名不確定處要明示，不可默默補寫。
• 建立術語表，區分官方名稱、暫譯與待查；遊戲 UI 與說明書共用已核准術語。
• 說明書可證實公開規則與玩家流程，但執行順序、邊界條件、隱藏值與版本差異仍以鎖定 原版及可重現實驗為準。
• 翻譯 Markdown 可提交；原始 PDF 不得提交。引用插圖前另做權利審查。

證據、規格與逆向工程

1. 原版執行檔是行為 oracle；反編譯輸出與玩家文章都不是可直接移植的原始碼。
2. 每項結論標示 已證實、強推論、假說 或 未知，並附輸入檔名與 SHA-256、 工具版本、位址空間、原始位址／偏移、bytes／xref／資料差分或可重播實驗。
3. 正式行為遵循：RE 證據 → DRAFT spec → 證據審查 → READY spec → implementation → 同狀態驗證 → CONFORMED。未達 READY 的原型不得進 production path。
4. 逆向工程一律優先使用既有 IDA Pro 9.4 專用 image 與 .i64 關係；其他工具只作 交叉驗證。先辨識 compiler、linker、runtime、packer、driver 與資料格式，再解玩法。
5. IDA 註記採非破壞性附加：保留原始函式名、全域名、位址、operand 與 bytes；語意、 推論等級及證據來源另列。禁止用推測性改名覆蓋唯一定位資訊。
6. 一項玩家功能至少貫通：原始資料 → parser → typed data → 規則 → UI／音訊 → 存檔 → 正常玩家路徑 → 同狀態抽樣。綠色單元測試只證明 remake 自洽，不證明原版 parity。
7. 可玩性需要足夠證據後就停止深挖無關 helper；新增研究先判斷是否改變玩家體驗或 現行交付 gate。

忠實度與共同決策

任何會改變玩法、戰鬥節奏、操作方式、資料格式、原版忠實度、美術、授權／公開方式或 發行聲明的決定，都必須先列出已知事實、選項、建議與影響，等待使用者選擇。尤其原版 戰鬥被玩家批評繁複而緩慢，這是重要設計議題，但不得未經確認就縮短、刪除或自動化。 視覺與操作取捨先製作可丟棄原型／截圖，再請使用者判斷。

文件責任

• README.md：用途、專案起源、玩家文章來源、穩定入口、現況摘要與正式交付連結。
• CONTEXT.md：有日期的唯一目前真相、有效決策、限制與最近交接。
• WORKLIST.md：可執行工作、狀態、完成條件與下一閘門。
• WORKLOG.md：按時間追加命令摘要、變更、驗證、失敗分類、提交／推送與清理狀態。
• RESEARCH-LOG.md／docs/re/：逆向輸入雜湊、工具、位址、證據與推論等級。
• docs/spec/：DRAFT／READY／CONFORMED 行為規格。
• docs/verification/：原版／重製同狀態收據與正常玩家路徑。

README 不得累積日期 checkpoint、失敗嘗試或 commit 流水帳。歷史不得反向覆蓋目前狀態。

比較工作區清理

每次原型比較或對拍驗證完成後，保存必要證據、核對雜湊並修正引用，再刪除 workplace/ 中該次工作目錄。只清理已完成且已保存的範圍，不刪其他任務資料。 本機壓縮證據、工具及核對方法見 docs/verification/retained-evidence.md。

驗證、交付與完成定義

2026-10-11 起的目前驗收規則

使用者明確改採受控場景驗收：允許驗收專用程式鎖定隊伍生命值、提高攻擊與準備場景輸入。 重製版抵達對應場景，確認中文顯示與畫面正確，即通過該場景。工具、參數、畫面清單與收據 依 SPEC-040。此規則優先於下方及歷史文件中 正常長流程、未修改隊伍與完整原版對拍的收尾要求；歷史研究保留，不作 HD 開工門檻。 不得將受控場景通過寫成原版 parity。正式遊戲與存檔不加入驗收輔助數值。

• 先分開「可啟動」、「可玩」、「近似完成」與「嚴格 parity」，並預先登記每階段 gate； 不得做到一半才選容易通過的完成標準。
• 圖像、動畫、音訊、中文排版、存讀檔與替代戰鬥路徑分開驗收；CJK 欄位必須有文字安全 矩形、換行／截斷策略與最長字串測試。
• 最終至少驗證正常路徑：啟動 → 建立隊伍 → 城鎮／世界探索 → 戰鬥規劃與結算 → 任務 → 存檔 → 離開 → 重載 → 結局或預定完成點。
• 唯一現行交付根目錄是 dist-all/<版本>/，至少包含 full/、release/、promo/。 full/ 可保存僅本機的含素材完整版；release/ 必須通過權利審查；promo/ 保存影片、 metadata、來源、雜湊與影音驗收。
• 每次打包從乾淨輸入重建，驗證啟動、內容、manifest、SHA-256、平台／架構、存檔位置、 素材 deny-list 與授權文件。Linux 封包不等於 Windows／macOS 真機驗收。

RND() 固定種子對拍鐵則

• 測試項目涉及 RND() 或其他亂數判定時，必須透過 dosgolem 固定原版的測試種子（seed）， remake 也必須固定測試 seed，再以可重播的相同初始狀態與等價輸入做對拍驗證。
• 測試收據必須記錄兩側 seed、設定方式、工具／程式版本、初始狀態、輸入與比較結果。 seed 必須在執行前固定；不得反覆重擲或挑選碰巧通過的結果當作驗收。
• 不強求未受控的正式執行、即時時鐘初始化或自然運行的真實 RND() 也能逐次對拍； 不把跨整段流程的精確骰序、重擲次數或亂數內部呼叫次數一致列為預設完成閘門， 也不得為此持續深挖原版亂數內部實作。
• 相同 seed 數字不保證不同亂數實作產生相同結果。比較前須確認比較點的狀態與 亂數條件可比；必要時以明示的受控亂數輸入隔離待驗規則，並在收據標示方法。 固定 seed 本身不是對拍通過的證據，不得用它掩蓋規則、狀態轉移或玩家可見結果的差異。
• 固定 seed／受控亂數僅屬測試條件，不得把正式遊戲永久鎖成測試結果。局部常式 對拍不能取代正常玩家路徑驗收；完成聲明須限於實際驗證的範圍。