Skip to content

About

Overlay for League of Legends Arena: ranked, explained augment and item advice from Riot's local API plus screen OCR. No injection.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

arena-brain banner

A transparent overlay that watches your Arena game through Riot's official local API and tells you, with reasons, which augment or item to take.

Top language License Last commit Stars

Electron React TypeScript pnpm Vitest


What it does

Arena is the 2v2v2v2 mode (internal name CHERRY) where every shop phase offers you augments and anvils you have a few seconds to judge. arena-brain polls Riot's local Live Client Data API for the game state, reads the three offer slots from your own screen with OCR during shop phases only, scores every option with a champion-aware engine, and shows the result in an always-on-top overlay: ranked, with the reason for each rank.

[screenshot placeholder] Capture the overlay during a shop phase with three ranked offers and their reasons, the gold plan card, and the status strip reading LIVE. A second capture of the control panel's Replay tab helps contributors. Borderless window, 1920×1080.

No injection. No memory reading. No input automation. The game process is never touched. This is the same class of tool as the common stats overlays and is compatible with Vanguard. League must run in Borderless window mode for the in-game overlay, or you can use phone mode.

Features

  • Ranked offers with reasons. Every option is shown and scored. The tool highlights, it never dictates.
  • Champion-aware scoring with build synergy, per-champion tiers and effect tags for augments and items.
  • Pick memory. Tracks what you already took and reasons about what fits next.
  • Live pool intel on the enemies you are likely to face, from the same local API.
  • Gold plan card suggesting what to buy when.
  • Phone mode. Keep League in exclusive fullscreen and read the advice on your phone over your home network.
  • Replay server that impersonates the Live Client API, so the whole thing can be developed without the game installed.
  • Diagnostics tab with counters, the last connection errors and the log tail, plus crash dialogs and a log file.
  • Riot policy firewall. Raw win rates are never displayed. The renderer can only receive an OverlayViewModel, whose Zod schema rejects win-rate-shaped fields, enforced by a test.

Tech stack

Layer Choice
Overlay app Electron 43, electron-vite, React 19, Zustand, electron-store
Brain Pure TypeScript in packages/core: API clients, phase and round tracking, scoring engine
OCR node-screenshots capture, sharp preprocessing, tesseract.js, fuzzy match against catalogs
Contracts packages/shared: types, Zod schemas, economy constants
Data DDragon item.json, CommunityDragon arena data, OP.GG priors cached 24 hours with a bundled fallback
Tooling pnpm 10 workspaces, Vitest, tsx, electron-builder

Monorepo layout

Path What
packages/shared Frozen contracts: types, Zod schemas, economy constants
packages/core API clients, state tracking, scoring engine
packages/ocr Screen capture, preprocessing, tesseract, catalog matching
packages/replay JSONL replay format and playback clock
apps/overlay The Electron app: transparent overlay, control panel, phone page
apps/replay-server Fake https://127.0.0.1:2999 for development without the game
tools/recorder Records real games on the gaming PC as JSONL plus screenshots
tools/fetch-static Refreshes patch catalogs and stat snapshots
data/ Bundled snapshots, curated effect tags, OCR region presets
fixtures/ Synthetic replay and OCR regression corpus

Quick start

Requirements: Node 22 or 24, pnpm 10 (corepack enable), Git. Works on macOS, Linux and Windows without the game installed.

git clone https://github.com/Hade6556/arena-brain.git
cd arena-brain
corepack enable
pnpm install                       # downloads Electron and the native modules, takes a few minutes
pnpm test                          # engine fixtures, OCR corpus, policy firewall
pnpm typecheck
pnpm fetch-static -- --offline     # build catalogs from the bundled data/raw fixtures

Then, in two terminals:

pnpm dev:replay      # fake Live Client API on :2999 replaying a synthetic 3x6 game
pnpm dev:overlay     # the Electron overlay, pointed at the same URL as the real game

The control panel's Replay tab has play, pause, seek and speed. The UI Preview tab renders the overlay with canned data for styling work. Set ARENA_DEBUG=1 to log a line per view-model push.

Usage on the gaming PC (Windows)

  1. League → Settings → Video → Window Mode: Borderless.
  2. Build or download the installer, run it, and launch ArenaBrain. SmartScreen will ask once: More info, then Run anyway.
  3. Queue Arena and play. The overlay shows LIVE once the local API answers.
pnpm --filter @arena-brain/overlay package:win      # apps/overlay/release/ArenaBrain-Setup-<version>.exe and a Portable build
pnpm --filter @arena-brain/overlay release-gate     # launches the packaged app against the replay server and asserts a live view-model
pnpm --filter @arena-brain/recorder start           # record a real evening for OCR calibration
Hotkey Action
Ctrl+Shift+S Force a scan of the offer screen
Ctrl+Shift+O Hide or show the overlay
Ctrl+Shift+X Kill switch

Phone mode: control panel → Settings → Phone mode. Allow the Windows Firewall prompt for private networks and open the shown http://<your-pc-ip>:17878 on a phone on the same Wi-Fi.

If something looks wrong, open the Diagnostics tab, or send %APPDATA%\ArenaBrain\logs\main.log.

Data sources and limits

  • Live game: https://127.0.0.1:2999/liveclientdata/* (official, local, self-signed certificate).
  • Pre-game: the LCU champion-select session, read through the lockfile, to prefetch stats.
  • Static: DDragon items for map 30, CommunityDragon arena data.
  • Offers are not exposed by any Riot API. They are read from three small fixed regions of your own screen during shop phases only.
  • Personal-use tool. If you ever distribute it, register it on the Riot Developer Portal.

Contributing

  1. pnpm test and pnpm typecheck must pass across all eight packages.
  2. The policy firewall test in packages/shared/test/policyFirewall.test.ts is not negotiable. Do not add win-rate fields to the view model.
  3. Scoring changes go in packages/core/src/engine/ and should come with a fixture replay in fixtures/replays that shows the new behaviour.
  4. New augments or shards seen in live play go in data/tags/ with their effect tags.
  5. Before a release, run the release gate against the packaged app. v0.1 shipped broken because this step was skipped.

License

No license file is in the repository yet, so the default "all rights reserved" applies. [placeholder: add a LICENSE file; the badge above updates by itself]

League of Legends and Arena are trademarks of Riot Games. This project is not endorsed by Riot Games.

About

Overlay for League of Legends Arena: ranked, explained augment and item advice from Riot's local API plus screen OCR. No injection.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages