歷史記錄 · 2026-11-02¶
重大重構里程碑¶
2026-11-02 ─ 比賽視口固定算圖削減（issue 001173 第一階段）¶
賽中頓挫在內顯機器的實測根因是 GPU 填充率（主執行緒等 GPU 300～740 ms、JavaScript 只 8 ms）。使用者
裁決分兩階段：先做確定性削減——比賽舞台的 drawing-buffer 像素預算由 8,000,000 降為 3,500,000（O4ThreeStage
新增 maxDrawingBufferPixels，viewport 依場景種類傳入），比賽、組裝與場地預覽的 canvas 改不透明、只有展示車
保留透明（rendererContextAttributes 純函式）；renderScalePercent 與 antialias 設定不變。後製 composer
只在主題啟用 outline 時才建、現況沒有 outline，MSAA 與後製兩項無可動之處。第二階段的 GPU 幀時間自適應另裁決。
同日補修：three r163+ 自己開的 context 一律 alpha: true，不透明要由工廠親自開 WebGL2 context（createStageWebGLContext）
再交給 renderer 才落到 context 層。內顯實測（AMD、DPR 1.5）顯示不透明與透明長幀幾乎相同、算圖倍率 50% 只把
長幀由約 300 ms 縮到約 220 ms，固定削減不能單獨救回內顯機器的可玩幀率，已記入 ADR 後果段。驗證者複驗抓到
renderer 工廠 computed 直接讀整個場景描述、同種場景換內容會整顆重建 renderer 的回歸：改為只依賴 antialias 與
canvasAlpha 兩個基本型別 signal，工廠建構者走注入點 STAGE_RENDERER_FACTORY_BUILDER，守門
viewport-renderer-factory.spec.ts；stage 的 effect 同時追蹤 maxDrawingBufferPixels，預算改變即重算 ratio。
同型既有寫法（issue 001181）：編輯器視口的工廠 computed 直接讀整個設定物件，頁首語言／主題切換與 UGC contribution
更新都會在編輯中整顆重建 renderer；比照改為只依賴 antialias 字串 computed 並走同一注入點，守門
editor-viewport-renderer-factory.spec.ts。行為不變、不另立 ADR。
決策檔：D-20261102-01
2026-11-02 ─ 比賽視口背景層移除與像素單軸自適應（issue 001182 第二階段）¶
乾淨環境（影片暫停、分頁可見）的開關表定位到內顯長幀的兩層成本：比賽頁 o4-game-scene 的全幅背景層（CSS filter＋
呼吸動畫、藏在不透明 canvas 之下）整層不掛後長幀 124→59、rAF 18→28 fps；剩餘成本按像素走，像素 3.5M→0.87M 後
長幀 10、42 fps。MSAA 與 effectsQuality 都不是槓桿、場景本身極輕（87 draw call、9 萬三角形）。使用者裁決兩步都做：
O4GameScene 新增 canvas surface mode（無背景層、保留裝飾層）供比賽頁使用；新增純邏輯 AdaptiveRenderScale
（階梯 100→80→60→45、rAF 間隔 2 秒窗 P90、超過兩幀預算持續 2 秒降階／低於 0.8 倍持續 10 秒升階、換階靜置 2 秒），
O4Viewport 只在比賽場景餵樣本、與玩家 renderScalePercent 相乘後交 stage；PresentationSettingsRuntime 多一個
adaptiveRenderScalePercent，賽中效能警告橫幅在模擬層或呈現層任一不足時顯示。落地後實機：起跑後 11.5 秒內逐階降到 45，
階 45 穩態 35 fps、p90 29 ms、長幀 ≥200 ms 歸零（修前 17 fps、每 40 秒 118 個）。驗證者複驗抓到兩處狀態脫鉤：
renderer 更換時 controller 清樣本但已發布的倍率沒同步回 100；回報給設定頁的實際比例含自適應削減，賽後設定頁會把
session 降階標成「受裝置 GPU 上限限制」——改為共用的回 100 重設、回報值除回自適應倍率並以玩家設定封頂，守門 viewport.spec 兩案。第二輪再抓到除回自適應的取整殘餘
（玩家 85×階 45→38→除回 84 仍誤標）→改純函式 hardwareRenderScalePercent：以 stage 要求值對實際值判截斷（floor 容差 1），
無截斷回報玩家設定本身，守門 race-render-budget.spec 全枚舉。第三輪指出截斷折算用等比會高估（預算是 pixelRatio 的絕對上限，
玩家 100 階 80 截到 66 會回報 83）→截斷時照實回報 stage 實際值（以玩家設定封頂）。
決策檔：D-20261102-02