Veck Tapper

Live lobby/match status detection for veck.io Shows where the player is rn - in lobby, or in a specific game mode (Deathmatch, TDM, FFA, 1v1, etc) by observing game traffic.

Files in package

• src/colyseus-tap.js precise for reading live room state in any Colyseus-based multiplayer game, without joining as a real player. This isn't specific to veck.io.

• src/heartbeat.js + src/modes.js veck.io specific: a custom API endpoint of veck.io and able to map out internal mode numbers to real game modes.

• src/index.js gives one final func watchVeckStatus(callback).

How it works

Colyseus games sync room state to connected clients binary frames. Normally.. reading that state means writing a real game client that actually joins the room (client.joinById(...) via colyseus's official colyseus.js library) and this is often rejected by server as its genuine vulnerability.

Instead of joining, colyseus-tap.js passively taps the game's own already websocket connection, the one opened by veck.io's client when you play. From there, every state update is decoded the same way Colyseus's own client does it internally using @colyseus/schema.

the protocol-byte layout (JOIN_ROOM = 10, ROOM_STATE = 14, ROOM_STATE_PATCH = 15, and the exact byte offsets for skipping the handshake's length-prefixed strings) isn't officially documented. Although its verified by reading colyseus.js's own source and confirming it against real captured traffic.

This part is reusable for any other Colyseus-based game. See Using colyseus-tap.js elsewhere.

The lobby/player layer (heartbeat.js)

Veck.io sends its own POST /api/friends/heartbeat request with a JSON body like {status: "playing", roomId: ",,,"} whenever your lobby/match status changes. Cleanest signal for "in lobby" or "in match".

veck.io is a Unity WebGL WASM game, and its networking layer doesn't consistently use one JS API, during testing it issue this request via fetch(), XMLHttpRequest and navigator.sendBeacon at different points and request bodies. heartbeat.js hooks all three transports and handles all observed body shapes.

Modes

veck.io's mode field is a plain int with no embedded name, this is decoded using this package:

mode	name
0	1v1
1	2v2
2	3v3
3	4v4
5	FFA
6	TDM
9	Kill Confirmed
12	Gun Game
13	1v1 Ranked
14	2v2 Ranked

Values 4, 7, 8, 10, 11 are unmapped. PRs welcome if you find them. See src/modes.js

Install

npm install veck-tapper

Usage

import { watchVeckStatus } from "veck-tapper";

watchVeckStatus((status) => {
  if (status.inLobby) {
    console.log("In Lobby");
  } else {
    console.log(`In ${status.mode ?? "an unknown mode"}`);
  }
}, { debug: true }); 

Calling this early in page load is recommended, for ex: a browser extension content script running at document_start in page's own JS context. (It's used in examples/extension)

Working example

examples/extension is a minimal, fully working chrome extension built on this library.

using colyseus-tap.js elsewhere

Its not veck.io specific. Can be used in different colyseus based game:

import { installGlobalHook } from "veck-tapper/src/colyseus-tap.js";
installBlobalHook(/any-colyseus-server\.example\.com/, (tap, socket, url) => {
  socket.addEventListener("message", () => {
    console.log(tap.state);
  });
});

State-tapping concept itself works unmodified.

What this is not

• not a way to control, join, interact with a room (read-only observations)
• not affiliated with veck.io or Legion games.

Tests

npm test

note: this only covers parts that dont need a real browser.

Making own browser extension

npm install veck-tapper alone isnt enough for extensions. In normal node.js projects its enough. So for extension usually libraries are bundled in single files:

1. npm install veck-tapper
2. Code importing it as normal:

import { watchVeckStatus } from "veck-tapper";

3. Run a bundler (esbuild, webpack, etc) with that file as the entry point.
4. IMP: Reference that bundled file in your extension's manifest.json

More details on veck.io

• Game servers are regionally named (ex: usa-1.veck.io, usa-5.veck.io) and works behind CloudFare.
• Only initial lobby-join flow goes through HTTP matchmaker call (/api/coly-matchmaker/find-lobby) with readable JSON response. Match connects via Webscoket directly.

Status

Experimental/Early although core detection has been tested and behaves correctly.

License

MIT.