「數字 10 消除遊戲」的視覺輔助提示器。只分析畫面並提供視覺提示,不操作遊戲,滑鼠操作完全由使用者自己完成。
到 **Releases** 下載 StarSaviorHelper.exe,雙擊即用:
免安裝、設定檔(settings.json)和日誌都留在 exe 旁邊,刪掉 exe 即乾淨移除。
需要 Windows 10 1803 以上 64-bit(後台抓圖用;更舊的系統會自動退回前景模式,遊戲需保持可見)。
開局:滿盤時一次顯示前 N 組彩色編號提示,1 號綠框照著打:
中盤:消除留下的空格可跨越,提示自動跟著新盤面走:
後盤:剩餘數字稀疏時,提示照樣精準定位:
- 打開就緒、按 F8 開工:自動綁定遊戲視窗+記住棋盤位置,搬窗/換解析度免重框
- 連續自動偵測:畫面變化 → 等待穩定 → 重辨識 → 更新提示(消除動畫自動跳過)
- 彩色編號提示:前 N 組提示各用不同顏色+編號徽章,重疊也分得清;框住同一組數字的重複框只留最小一個
- 後台抓圖:遊戲被其他視窗蓋住照常工作;最小化自動等待、關閉自動停止
- 極簡主視窗:一行狀態+一顆開關+提示數,平常碰不到的收進「設定…」
- Phase 1:ROI 框選 + 設定儲存
- Phase 2:10×15 Grid + Cell State + Template Matching(含 1~9 完整模板)
- Phase 3:Rectangle Solver(純演算法,只吃 BoardState)
- Phase 4:Hint Selector(最小 area + 固定掃描順序+同組數字去重,選前 N 個)
- Phase 5:透明 Click-through Overlay(外框 + 起點 + 終點)
- Phase 6:畫面變化偵測(穩定等待 + Hint Lock + 穩定後重辨識)
- Phase 7:整合測試與 UX 修正(含 F8 全域快捷鍵)
- 開啟 StarSavior 遊戲(標題即
StarSavior的視窗),再開本工具 - 工具自動綁定遊戲視窗+驗證棋盤位置;若已有上次的框選,直接顯示「就緒」
- 第一次使用:主視窗只會看到「框選辨識區域來開始」→ 以後台遊戲畫面為底 拖曳框住 10 × 15 棋盤(Enter 或雙擊=確認、Esc=取消; 存的是視窗相對比例,搬窗/換解析度免重框),框完自動就緒
- 按「開始監控 (F8)」開工;
F8=開始/停止監控(監控總開關,只控制提示流程) - 「同時提示數」(1
10,預設 5):一次顯示前 N 組提示; 1 號首選亮綠粗框照著打,2N 號各用不同顏色+編號徽章,重疊也分得清; 框住同一組數字的重複矩形只留最小一個(多的只是空格留白,消下去一樣);偏好會記住 - 平常碰不到的東西全在「設定…」:ROI 微調/自動校正/預覽、辨識矩陣、主視窗置頂、 語言(繁中/English/日本語/한국어,預設跟系統語言,系統非此四者時用英文,切換立即生效)
抓圖管線:Windows 後台抓圖(被蓋也活)優先,不可用時退回前景; 遊戲最小化顯示「等待遊戲視窗」,關閉自動停止。
- 點主視窗引導按鈕或設定裡的「框選辨識區域」→ 主視窗暫時隱藏,出現全螢幕選取介面
- 按住滑鼠左鍵拖曳大略框住遊戲的 10 × 15 數字棋盤(任意方向皆可,畫面上會即時顯示 X/Y/W/H)
- 放開後會自動對齊到實際棋盤位置,並顯示 10 × 15 格線供檢查
- 對齊失敗時自動使用原始選取範圍
- 按
A可切換自動對齊開/關
- Enter 或雙擊=確認、Esc=取消、重新拖曳=重選
- 也可用設定對話框的 X / Y / Width / Height 數值欄手動微調;「自動校正」按鈕可用即時畫面重新對齊現有 ROI
- ROI 會自動儲存在專案根目錄
settings.json,下次啟動自動載入 - 啟動時若遊戲視窗移動了,程式會自動吸附到新位置並更新設定 (先在舊位置附近找,找不到再全螢幕搜尋+辨識驗證;都找不到才沿用舊設定)
- 設定對話框的預覽區會顯示框選結果與 10 × 15 格線,協助確認對齊
- 監控中的即時 10×15 辨識矩陣可在設定對話框查看(唯讀)
- 重建數字模板:
uv run python tools/build_templates.py <遊戲截圖> <標註JSON>(標註格式{"row,col": digit};ROI 預設讀settings.json) - Solver 是純函式
core/solver.py::find_rectangles(board); 單獨測試:uv run pytest tests/test_solver.py
- 監控中棋盤穩定變化且無 UNKNOWN 時,自動計算前 N 個提示並顯示透明 Overlay (1 號首選綠框+綠起點+青終點,標示建議的滑鼠拖曳起終格中心; 2~N 號各用不同顏色+編號徽章,一次全顯示)
- Overlay 不接收滑鼠、不搶焦點;停止監控(或 F8)即隱藏
- 擷取前會自動隱藏 Overlay,避免框線污染辨識
- 按「開始監控」(或 F8):每 300ms 比對 ROI 畫面,連續 3 幀穩定且與基準不同 才重辨識(消除動畫中間幀會被跳過);棋盤真正變化才更新 Overlay (Hint Lock),否則保持原提示
- 「停止監控」:停止迴圈並隱藏提示;變更 ROI 會自動先停止監控
- 監控中狀態列會顯示
#tick 穩定run/3進度與最近事件 (已更新提示/維持提示/UNKNOWN 等待),卡住時先看這行 debug/monitor.log記錄每次穩定觸發、重辨識結果與 Overlay 殘留重試, 回報問題時請附上這段日誌F8=開始/停止監控(監控總開關,只控制提示流程,不操作遊戲)
tests/test_integration.py:用 repo 內真實模板拼出合成棋盤, 端到端驗證 ROI 畫面 → 辨識 → Solver → Hint → Overlay 幾何, 以及跨棋盤變化的 monitor 全鏈- 變化偵測用「明顯變化像素比例」(非全圖平均),單格消除(約佔全 ROI 1%)
也能觸發;門檻見
core/monitor.py::MonitorConfig
- 顯示「找不到遊戲視窗」:先開遊戲再按開始監控;確認遊戲視窗標題是
StarSavior且未最小化。 - 按了開始監控但提示不更新:看狀態列——「等待遊戲視窗」表示最小化了;「維持提示(棋盤未變)」表示畫面真的沒變;卡住先看
debug/monitor.log。 - 很多格顯示問號(UNKNOWN):通常是遊戲特效/動畫遮住數字,等畫面靜止會自動重辨識;若長期如此,可能是遊戲改版換了字體。
- 框選框不準:框選放開後會自動對齊,失敗會用原始範圍;到「設定…」按「自動校正」,或直接重框。
- F8 沒反應:可能被其他軟體佔用;直接按主視窗的開關鈕效果一樣。
大功能已完工;後續以修 bug 和小體驗優化為主。歡迎開 Issue(附上 debug/monitor.log 會更快釐清)。
- Python 3.13+uv
- 開發測試:直接雙擊
run.bat(首次執行會自動安裝依賴;錯誤時視窗會暫停顯示訊息)
或使用命令列:
uv sync
uv run python main.pyuv run pytestcodegraph sync # 改完程式後同步索引(增量,很快)
codegraph index # 索引壞掉或大重構時整份重建- 索引檔放
.codegraph/(SQLite),只活在本機、不進 git;新 clone 下來跑一次codegraph init即可 - 日常查碼直接問(MCP
codegraph_explore):一次回傳相關符號原文+呼叫鏈,不用 grep+Read 繞圈
main.py # 進入點(DPI awareness + QApplication)
core/
roi_model.py # Roi(絕對)+ RoiFrac(視窗相對比例)+ IoU
settings_store.py # 設定 JSON:視窗標題 / roi_frac / ui 偏好(舊 roi 自動遷移)
game_window.py # 目標視窗綁定(精確標題+可見+最大)與客戶區
window_capture.py # WGC 後台擷取會話+單幀抓取(被蓋也活)
screen_capture.py # mss 前景擷取(備援;框選背景、絕對座標 ROI 用)
board_align.py # 10×15 棋盤自動對齊(ROI Auto-Align)
grid.py # ROI 固定切成 10×15(CellGeometry 含 center)
board_state.py # BoardState + CellState(DIGIT/EMPTY/UNKNOWN 三態分離)
templates.py # TemplateStore:1~9 模板讀寫(不管比對)
recognition.py # DigitRecognizer:白 tile 缺席 → EMPTY;否則模板比對
board_builder.py # ROI 畫面 → 切格 → 辨識 → BoardState
solver.py # Rectangle Solver:純演算法,BoardState → 全部合法矩形
hint_selector.py # Hint Selector:最小 area + 固定順序+同組去重,選前 N 個
monitor.py # 畫面穩定追蹤 + Hint Lock(不碰 GUI/擷取)
paths.py # frozen 路徑相容(資源走解包暫存,可寫走 exe 旁)
i18n.py # UI 字串 zh/en/ja/ko+系統語言偵測
gui/
main_window.py # 主視窗(一行狀態+監控開關+提示數+首次引導;邏輯仍住這裡)
settings_dialog.py # 設定對話框(ROI 框選/微調/預覽、辨識矩陣、置頂)
roi_selector.py # 全螢幕框選視窗(含自動對齊;背景可為後台幀)
recognition_panel.py # 10×15 辨識結果矩陣顯示
hint_overlay.py # 透明 Click-through Overlay(10 色外框+起/終點+編號徽章,不吃滑鼠)
global_hotkey.py # F8 全域快捷鍵(Win32 RegisterHotKey,監控總開關)
image_utils.py # QImage ↔ numpy 轉換
docs/
adr/ # 架構決策記錄(後台抓圖、相對 ROI…)
CONTEXT.md # 專案術語表(唯一推薦用語+禁用詞)
templates/
1.png ... 9.png # 真實遊戲畫面擷取的數字模板(tools/build_templates.py 建立)
tools/
build_templates.py # 從遊戲截圖 + 標註 JSON 建立/更新模板
tests/ # pytest 單元測試(含 solver vs 暴力參考實作比對)
管線全程使用實體螢幕像素:main.py 設定 Per-Monitor DPI awareness 並關閉 Qt High-DPI 縮放(QT_ENABLE_HIGHDPI_SCALING=0),確保 Qt 座標與擷取座標一致,後續 Overlay 也沿用同一座標系。設定檔存的是視窗相對比例(roi_frac),啟動/每 tick 以當下遊戲客戶區換算成絕對座標,因此搬窗/換解析度免重框。
本工具只讀取遊戲畫面並顯示提示,不修改遊戲、不送出任何滑鼠/鍵盤操作。請遵守遊戲的服務條款,使用風險自負(MIT License,不負任何擔保責任)。


