BonkAPI

Description

BonkAPI is an open-source telemetry framework for MegaBonk. It is a BepInEx plugin that reads live game state and streams it over a local WebSocket (port 5556) as JSON — so anyone can build external tools, overlays, trackers and dashboards on top of it.

The plugin changes no gameplay: it only observes. Two ready-made browser clients are included: a live HUD and a live map viewer.

Source code: https://github.com/urukaiko/BonkAPI

Installation instructions

1. Install BepInEx 6.x (IL2CPP) for MegaBonk.

2. Download `BonkAPI.zip` from the Files tab and extract it anywhere.

3. Copy `BonkAPI.dll` to `BepInEx/plugins/`.

4. Copy the `BonkAPI-web-hud` folder anywhere you like (e.g. `web/hud`).

5. Copy the `BonkAPI-web-map` folder anywhere you like (e.g. `web/map`).

6. Open `BonkAPI-web-hud/index.html` or `BonkAPI-web-map/index.html` in a browser.

7. Start the game — tools connect automatically to `ws://localhost:5556`.

Optional: override the endpoint via query string, e.g. `index.html?ws=ws://localhost:5556`.

Main features

API / core

- Local WebSocket server, JSON protocol, no internet required

- Full state snapshot on connect, then differential events on change

- 20 tracking modules: player, health, level/XP, 31 stats, weapons + passives, items + rarity, tomes, kills (by enemy / category / source), per-source damage (hits, crits, executes, blocked), offers & choices (level-up, moai, shady guy, shrine, microwave, chest), bans, resources, interactables, run lifecycle, stage events, map data

- Open source, MIT license

Live HUD (browser)

- Run / stage timers with overtime indicator

- HP / Shield / Overheal, gold, kills, level / XP, skips / refreshes / banishes

- Per-source damage breakdown with DPS

- Weapons, items, tomes, banned pool, interactables usage

- Run history and filterable event log

- Offer overlays for level-up / moai / shady guy / shrine

- Export current run as JSON for replay

Live Map (browser)

- 2D top-down and 3D orbit view of the generated stage

- Enemies by category, pickups, orbs, interactables, boss marker

- Player position and heading, filters, zoom / pan, hover info

Fair play

- Map data is automatically disabled while "Upload score to Leaderboards" is enabled; visibility is locked at the start of each run.

Requirements

- MegaBonk with BepInEx 6.x (IL2CPP)

- Modern browser

- Free local port 5556

- No other mods or dependencies needed

Shout outs

- My sister, who asked me to release this mod, so I could end my everlasting suffering in development.

This project was developed with the assistance of AI tools.