TFT Advisor

Trợ lý Đấu Trường Chân Lý (TFT) thời gian thực — overlay đè lên game, mỗi vòng khuyên: đi comp nào, level/econ ra sao, roll hay giữ máu, mua gì, xếp đội hình và lắp đồ / xoay đồ.

Fuses meta của op.gg + MetaTFT với trạng thái sống trong ván (đọc qua Overwolf Game Events).

Read-only, an toàn ToS. App chỉ đọc (Overwolf GEP + hiển thị overlay). Không giả lập chuột/phím, không đọc/ghi memory game, không inject. Cùng loại với op.gg desktop / Mobalytics / Blitz — những app chạy dưới Vanguard hàng triệu người dùng không bị ban. Ranh giới cấm: tự động thao tác input hoặc đụng vào tiến trình game — dự án này không bao giờ làm.

Kiến trúc

   op.gg MCP  ─┐                          ┌────────────── Overwolf app (JS, nhẹ) ─────────────┐
   MetaTFT API ┴─► meta-service (Node) ──►│ playbook.json                                     │
                    build 1 lần/patch     │        │                                          │
                                          │        ▼                                          │
   Overwolf GEP ───────────────────────► │ background.js ──► engine.decide() ──► overlay UI   │
   (gold/level/hp/shop/board/đối thủ)     │  (map GEP→GameState)   (bộ não)     (hiển thị)     │
                                          └───────────────────────────────────────────────────┘

meta-service (src/meta, scripts/build-playbook.mjs): kéo op.gg + MetaTFT → chuẩn hoá theo Riot apiName → data/playbook.json. Chạy 1 lần mỗi patch, không gọi mạng lúc đang đánh.
engine (src/engine): bộ não thuần — decide(GameState, Playbook) → Recommendation. Không phụ thuộc Node, chạy y hệt trong demo lẫn trong app.
app (app/): app Overwolf. background.js ăn event GEP → dựng GameState → chạy engine → đẩy lời khuyên sang overlay.

Vì bộ não là event-driven + thuần JS (không computer-vision, không Python, không YOLO) nên nhẹ như op.gg — GEP đẩy dữ liệu, app chỉ tính vài mili giây mỗi vòng.

Cấu trúc thư mục

tft/
├─ src/
│  ├─ meta/           op.gg MCP + MetaTFT clients + normalize
│  ├─ engine/         bộ não: fit / econ / items / decide  (pure ESM)
│  └─ demo/           mock state + CLI demo
├─ scripts/           build-playbook · bundle-app · make-icons
├─ data/playbook.json meta đã chuẩn hoá (sinh ra, không commit)
├─ config/            app.config.json (weights, thresholds, hotkey)
├─ tests/             unit test engine (node:test)
└─ app/               ★ Overwolf app (sản phẩm ship)
   ├─ manifest.json
   ├─ background/     background.html/.js + gep.js
   ├─ windows/overlay/ overlay.html/.css/.js
   ├─ lib/            engine (bundled .js) + playbook.json + config
   └─ icons/

Yêu cầu

Node.js ≥ 18 (đã test Node 24) — chỉ cần để build meta + đóng gói. App chạy không cần Node.
Overwolf — runtime chạy app + cấp Game Events (GEP).
League of Legends client (TFT chạy trong đó; game id Overwolf = 5426).

Cài & chạy

1) Build data + đóng gói app

npm run build          # = build:playbook + icons + build:app

Sinh data/playbook.json, copy engine + playbook + config vào app/lib, tạo icon, và tự verify engine bản bundle import được.

2) Xem bộ não chạy thật (không cần game)

npm run demo           # in ra lời khuyên cho 1 tình huống mẫu
npm test               # 7 unit test engine

3) Nạp app vào Overwolf (dev, unpacked)

Mở Overwolf → Settings → About → bật Development options (Developer mode).
Support / Development → Load unpacked extension → trỏ vào thư mục app/ (thư mục chứa manifest.json).
Mở Đấu Trường Chân Lý. Overlay tự hiện. Ctrl+Shift+T để ẩn/hiện.

4) Xem thử overlay ngoài game (tuỳ chọn)

Mở app/windows/overlay/overlay.html?demo bằng trình duyệt để render sample-recommendation.json.

✔ Đã kiểm định trên máy thật (2026-07-24, trong 1 ván TFT Xếp Hạng đang chạy)

Chạy npm run probe:live khi đang trong ván, đo được:

Nguồn local	Cho gì	Kết luận
LCU (lockfile `E:\Riot Games\...`)	phase=`InProgress`, gameMode=`TFT`, queue, summoner	✅ dùng cho lifecycle (bật/tắt overlay)
2999 `activeplayer.level`	`3` (khớp "Cấp 3" trên màn hình)	✅ level lấy được
2999 `activeplayer.currentGold`	`553.04…` (thật là 6)	❌ hỏng — số thập phân vô nghĩa, bỏ
2999 HP / board / shop	không có	❌ phải GEP/CV

Bonus proof: đã chụp màn hình 1 ván thật → đọc state (stage 2-1, L3, 6g, shop Caitlyn/Poppy/TF) → cho qua engine (src/live/advise-live.mjs) → ra lời khuyên khớp op.gg overlay + phân tích thêm shop. Tức pipeline chạy đúng trên game thật; chỉ còn thiếu khâu ĐỌC board/shop TỰ ĐỘNG.

Overwolf GEP — đã VERIFY schema (2026-07-24)

GEP cho TFT vẫn chạy — kiểm chứng từ tft-events-sample-app chính thức của Overwolf + 3 app thật (tftatics, tftCalculator, TFT-Scout). app/background/gep.js đã map đúng ground-truth:

Feature đúng: me, board, bench, store, match_info, roster, carousel, game_info, gep_internal (KHÔNG phải tft/shop/game_flow — mấy tên đó bịa, Overwolf lặng lẽ bỏ).
Shape đúng: payload là info.<feature>.<key>, collection là JSON-string keyed cell_N/slot_N (không phải array); me.gold/health là string có nháy; piece .level = số sao (1/2/3).
Lấy được qua GEP: board của BẠN (quân+sao+đồ), bench, shop 5 ô, gold, level, health, stage → đủ chạy comp/econ/roll/item/shop.
KHÔNG lấy được qua GEP: board đối thủ (chỉ có health/xp/rank qua roster.player_status → state.standings). ⇒ tính năng contested-pivot (đếm người tranh carry) là CV-only, GEP không làm được. Streak suy ra gần đúng từ tụt máu.

Nạp app vào Overwolf (dev) + debug GEP thật

Cài Overwolf (máy này chưa có) → https://www.overwolf.com/
Overwolf tray → Settings → About → bật Developer options.
Settings → Development → Load unpacked extension → chọn thư mục app/ (chứa manifest.json).
Mở TFT (app tự chạy nền theo launch_events). Ctrl+Shift+T ẩn/hiện overlay.
Debug payload: mở trình duyệt → http://localhost:54284 → chọn target background / "TFT Advisor" → Console. Xem log [gep] features set: và [gep] unmapped .... Xác nhận 2 điểm còn nhập nhằng giữa các nguồn: me.xp.level vs current_level, và piece .level = sao.
Không muốn chờ vào trận: chạy github.com/overwolf/gep-sim (Game Events Simulator) để bơm payload board/store/me giả xem đúng shape.

⚠️ Vẫn re-verify mỗi patch/set TFT — GEP scrape từ client nên có thể vỡ tới khi Overwolf vá. Mọi field đã bọc ?./parseObj phòng thủ.

Bộ đọc CV — như op.gg, KHÔNG cần Overwolf (`src/live/cv/`)

op.gg desktop không dùng Overwolf GEP — nó là app Electron đọc màn hình bằng model AI (end2end.onnx + onnxruntime.dll, xác nhận từ chính thư mục cài trên máy). Đây là đường thứ 2, và bộ đọc CV này đi theo — zero cài đặt:

OCR = Windows.Media.Ocr (có sẵn trong Windows, không cài gì). scripts/win-ocr.ps1 + scripts/capture-window.ps1 (chụp CLIENT area cửa sổ game, DPI-aware, neo ROI theo tỉ lệ nên không lệ thuộc vị trí/size cửa sổ).
Đọc được (đã test thật trên ảnh ván): shop 5 ô (OCR tên → fuzzy-match roster 73 tướng), stage, level, gold. Ví dụ đã chạy: OCR ảnh shop nhiễu → lọc đúng ra Caitlyn, Poppy, Twisted Fate. Roster giàu (playbook.roster) có cả cost + traits mỗi tướng.
Nhận diện chân dung (perceptual hash / dHash): npm run build:portraits tải 70+ tile tướng từ Community Dragon + hash. Đã kiểm nghiệm: khớp tuyệt đối ảnh giống hệt (self-match dist 0, phân biệt Jinx↔Caitlyn dist 37) — NHƯNG match ảnh LIVE trong game thì THẤT BẠI (crop shop live → gần nhất Illaoi dist 19, sai). Lý do: ảnh render trong game khác tile HUD tĩnh, và quân board là model 3D.
⇒ Kết luận thật (frontier): đọc QUÂN trên board bắt buộc cần MODEL AI train (đúng như op.gg dùng end2end.onnx) — template-match không đủ, đã chứng minh. Shop thì OCR tên là đủ & chính xác (khỏi cần ảnh).

Board model — nguồn có sẵn + data-prep scaffold

Đã khảo sát nguồn để "tìm ở đâu về mà làm":

Pretrained/dataset (Roboflow): có model + dataset TFT champion detection thật (Fynn lol-tft-champion-detection, tft-recognition, tft-object 801 ảnh, tft-champion classification 827 ảnh) — nhưng cho set cũ (tướng đổi mỗi set) → dùng để tham khảo kiến trúc/augmentation, phải train lại cho set hiện tại.
Reference bot đọc board: jfd02/TFT-OCR-BOT (OCR + template đọc board/bench/item) — gần nhất với phần đọc board.
Reframe (dễ hơn op.gg): ô cờ ở vị trí cố định → rút về phân loại crop từng ô (74 lớp: 73 tướng + trống), không cần bbox detection. Khớp đúng dataset tft-champion classification.
Scaffold đã dựng: npm run cv:cells (+ src/live/cv/cells.mjs, scripts/crop.ps1) chụp board → cắt 28 ô hex ra ảnh riêng để gắn nhãn + train. Auto-label được board của mình bằng GEP/lịch sử-mua (nhãn ground-truth miễn phí) → gom crop qua nhiều ván → train offline (Python, ngoài scope phiên chat).

Chạy: npm run cv:advise (chụp live) hoặc npm run cv:advise -- --image=<ảnh.png> (test offline). Lần đầu nên chỉnh ROI trong src/live/cv/regions.mjs cho khớp layout (dùng cv:advise xem "ĐỌC ĐƯỢC" đúng chưa). Khuyên chơi TFT fullscreen cho CV ổn định.

CV vs GEP: cùng cắm được vào engine (đã tách rời). CV = không cần Overwolf + đọc được cả board đối thủ (khi scout) nhưng nặng hơn & vỡ theo set. GEP = nhẹ + cần Overwolf + không có board địch. Giữ cả hai làm nguồn thay thế.

Lộ trình (đã làm ✅ / kế tiếp)

✅ v0.1 — meta pipeline (op.gg + MetaTFT), bộ não (comp/econ/roll/items/positioning/contested), demo + test, Overwolf app (GEP + overlay). GEP schema đã VERIFY + map đúng.
⏭ v0.2 — chạy live trên Overwolf máy thật, chốt me.xp.level; streak chính xác từ round_outcome; đọc augment (màn chọn, CV) + tra tier MetaTFT.
⏭ v0.2+ — CV scout board đối thủ để bật lại contested-pivot (GEP không cấp board địch).
⏭ v0.3 — enrich MetaTFT (levels/rerolls chính xác theo từng comp); positioning lật theo hiểm hoạ đối thủ.
⏭ v0.4 — đóng gói installer .opk (Overwolf Package) + auto-update; onboarding UI.
⏭ Set 18 (~12/8/2026, Unreal Engine) — set mới đổi toàn bộ ID; chỉ cần chạy lại npm run build (không hardcode set — đọc từ MetaTFT tft_set). GEP/CV có thể cần chỉnh lại ROI/field.

Rủi ro đã biết (nói thẳng)

Rủi ro	Ảnh hưởng	Giảm thiểu
GEP TFT có thể vỡ theo patch	thiếu board/shop sống	schema đã verify + parse phòng thủ (`parseObj`); re-check mỗi set
GEP KHÔNG cấp board đối thủ	contested-pivot không chạy bằng GEP	chỉ có standings (health/xp/rank); board địch cần CV scout
Set 18 sắp ra (UE rebuild)	đổi ID, có thể đổi field GEP	không hardcode set; `npm run build` lại mỗi patch
Positioning là meta mặc định	chưa lật theo đối thủ	v0.3
op.gg/MetaTFT là API không chính thức	có thể đổi/khoá	cache theo patch, chuẩn hoá `apiName` để đổi nguồn dễ, có op.gg MCP (được cho phép) làm fallback

Giấy phép

MIT — xem LICENSE. Dùng cá nhân; không phân phối lại data của op.gg/MetaTFT.

Navigation Menu

Repository files navigation

TFT Advisor

Kiến trúc

Cấu trúc thư mục

Yêu cầu

Cài & chạy

1) Build data + đóng gói app

2) Xem bộ não chạy thật (không cần game)

3) Nạp app vào Overwolf (dev, unpacked)

4) Xem thử overlay ngoài game (tuỳ chọn)

✔ Đã kiểm định trên máy thật (2026-07-24, trong 1 ván TFT Xếp Hạng đang chạy)

Overwolf GEP — đã VERIFY schema (2026-07-24)

Nạp app vào Overwolf (dev) + debug GEP thật

Bộ đọc CV — như op.gg, KHÔNG cần Overwolf (`src/live/cv/`)

Board model — nguồn có sẵn + data-prep scaffold

Lộ trình (đã làm ✅ / kế tiếp)

Rủi ro đã biết (nói thẳng)

Giấy phép

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
app		app
config		config
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
jsconfig.json		jsconfig.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

TFT Advisor

Kiến trúc

Cấu trúc thư mục

Yêu cầu

Cài & chạy

1) Build data + đóng gói app

2) Xem bộ não chạy thật (không cần game)

3) Nạp app vào Overwolf (dev, unpacked)

4) Xem thử overlay ngoài game (tuỳ chọn)

✔ Đã kiểm định trên máy thật (2026-07-24, trong 1 ván TFT Xếp Hạng đang chạy)

Overwolf GEP — đã VERIFY schema (2026-07-24)

Nạp app vào Overwolf (dev) + debug GEP thật

Bộ đọc CV — như op.gg, KHÔNG cần Overwolf (src/live/cv/)

Board model — nguồn có sẵn + data-prep scaffold

Lộ trình (đã làm ✅ / kế tiếp)

Rủi ro đã biết (nói thẳng)

Giấy phép

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Bộ đọc CV — như op.gg, KHÔNG cần Overwolf (`src/live/cv/`)