PS2 Web Recomp

PS2 Web Recomp 環境準備清單

轉換遊戲之前，先確認建置環境。上游列出的需求包括 Git、CMake、Ninja、C++20 編譯器與 Python 3，壓縮格式可能另需解壓縮工具。請依最新官方文件確認平台步驟，不能只因別人的電腦成功，就判斷自己的環境已準備好。

把儲存庫、遊戲映像檔與產出檔案放在容易區分的位置，並選擇一致的專案識別名稱。記錄開始時的工具版本；比較結果時，避免同時更換編譯器和瀏覽器。保留穩定基準，才能更有效地找出差異來源。

本機建置流程與指令範例

取得儲存庫後，在其目錄中執行下列範例，並把引號內的檔名替換成自己的遊戲映像檔。mygame 是說明用的識別名稱，不是可下載的遊戲。啟動本機伺服器時也需使用相同名稱，讓路徑對應剛產生的檔案。

cd ps2-web-recomp
scripts/port.sh mygame "My Game.iso"
python3 scripts/serve.py build/web-mygame games/mygame/disc.iso

編譯失敗和瀏覽器執行失敗是不同階段。若編譯指令沒有成功，先保存第一個有意義的錯誤訊息，再考慮開啟頁面。建置完成後，使用工具提供的本機伺服器與網址，不要直接雙擊 HTML 或混用不同次建置的檔案。

若使用既有的 Emscripten，確認執行建置的終端機已啟用其環境設定；另一個終端機未必繼承相同 PATH。記錄 SDK 版本與專案修訂版本，再進行修改，才能分辨結果來自程式碼變動還是工具鏈變動。

PS2 瀏覽器版本的排錯方式

在真正執行遊戲的裝置上確認瀏覽器功能。WebGPU 是否可用，取決於瀏覽器、作業系統、顯示硬體與驅動程式；單看瀏覽器名稱並不能判斷相容性。先查看圖形診斷與頁面錯誤訊息，確認能否取得繪圖裝置，再把問題歸因於個別遊戲。

遇到 SharedArrayBuffer 或執行緒錯誤時，可在開發者主控台檢查 crossOriginIsolated。跨來源隔離需要回應標頭與相關文件政策，並非把檔案放上 HTTPS 就會自動啟用。請依專案配套的啟動方式操作，先區分伺服器設定與編譯問題。

若頁面開啟後停止，保存最早的主控台錯誤與對應的網路請求。確認要求的路徑是否真的有檔案，以及回應是否其實是 HTML 錯誤頁。一次只調整一個條件；檔案缺失、繪圖裝置不可用與未支援的遊戲功能，需要不同的調查方式。

分開管理瀏覽器存檔與建置檔案

上游播放器提供記憶卡匯入與匯出功能。在清除網站資料、更換瀏覽器設定檔，或改用其他本機網址之前，先備份存檔。匯出的記憶卡應放在標示日期的資料夾，與產出的建置檔案分開；複製網站目錄並不代表瀏覽器中的進度也會一併移動。

記錄存檔來自哪款遊戲與哪個本機網址，並用額外副本測試還原，不要覆蓋唯一的備份。這有助於區分存檔處理問題，以及遊戲尚未達到可正常執行的階段。

如何記錄有用的相容性回報

出現標題畫面只是進展，不代表整款遊戲皆可遊玩。請記錄實際確認的階段：啟動、選單、可操作場景、音效、場景切換，以及存檔或讀檔。沒有測試的項目標為未知，並區分觀察到的結果與預期，避免把短暫成功描述為完整相容。

回報時附上遊戲版本與地區、專案修訂版本、作業系統、瀏覽器版本、顯示裝置、建置指令與簡短的重現步驟。若有測量效能，說明場景、解析度與測量方法，並在相同條件下比較多次結果。具體紀錄比單純標示可玩或不可玩，更能幫助其他讀者重現問題。

HY8BIT 現有遊戲資訊是整理作者的公開回報。上述清單是提供個人測試的編輯建議，不代表本站已完成這些測試。請把自己的結果與上游回報分開，分享技術問題時附上對應的 issue 或修訂版本。