@hoangvu12/gigi

Live Valorant game-state — match lifecycle, round phase, agent, map, mode, match id, player identity, shop, local-player kills/deaths, live roster and episode/act, and (opt-in OCR) precise score + health — without Overwolf, by tailing Valorant's own ShooterGame.log and the local 127.0.0.1 client API.

Strictly read-only: no memory reading, no injection, no input automation, no mutating API calls. The OCR layer captures gigi's own screen at ~2 fps, gated on match/round state.

Windows + x64 only. The native addon links Windows screen-capture APIs. The prebuilt binary shipped with this package includes the OCR vision layer; it stays dormant unless you pass { ocr: true }.

Install

npm install @hoangvu12/gigi

The prebuilt binding.win32-x64-msvc.node is bundled — no Rust toolchain or build step needed to consume it.

Usage

const { Gigi } = require('@hoangvu12/gigi');

const gigi = new Gigi({ ocr: false }); // ocr opt-in (precise score + health)

// (a) EventEmitter-style
gigi.on('match_start', e => console.log('match', e.pseudo_match_id));
gigi.on('round_phase', e => console.log(e.phase, e.round));
gigi.on('kill',        e => console.log('kill', e.headshot));
gigi.on('score',       s => console.log('score', s.allies, s.enemies)); // precise with ocr
gigi.on('health',      h => console.log('hp', h.value));                 // ocr only
gigi.on('event',       ev => console.log(ev.type, ev.data));             // every event

// (b) or async iterator
// for await (const ev of gigi.events()) console.log(ev.type, ev.data);

gigi.start();
// ...later
gigi.stop();

const snap = gigi.snapshot(); // { agent, map, game_mode, round_number, health, ... }

Options

new Gigi({
  ocr?: boolean,      // enable the OCR vision layer (precise score + health). Default false.
  logPath?: string,   // override ShooterGame.log path
  fromStart?: boolean,// replay log history before following live. Default false.
  localApi?: boolean, // local client API roster/season poller. Default true.
});

Events

match_start, match_end, scene_change, round_phase, round_number, agent, map, game_mode, match_id, match_state, team, kill, death, headshot, shop, player, roster, season, score, health.

Each event is { type, data }. .on('<type>', cb) receives data; .on('event', cb) and events() receive the whole { type, data }. Full TypeScript types ship in index.d.ts.

Identity values (agent, map) are Riot internal codenames — resolve to display names via valorant-api.com.

Caveats

• kill / death / headshot are approximate (derived from agent voice-line log lines, gated to the local player).
• team side is best-effort (the log doesn't reveal starting side; gigi assumes attack first and flips at the half / overtime).
• Without OCR, score is coarse (from the presence blob) and health is unavailable; outcome is null.
• OCR ROIs are calibrated for 16:9; other aspect ratios need re-tuning.

License

MIT.