bdo-toolkit

Passive, read-only Python tooling that turns live or recorded Black Desert traffic into structured, application-ready data.

Documentation · Quickstart · Examples · API index · Report an issue

Passive, read-only boundary. bdo-toolkit observes local traffic or saved captures. It does not send or modify packets, replay traffic to the game, automate gameplay, inspect process memory, or bypass anti-cheat software.

Live-capture limitations

Live capture depends heavily on your network setup and on whether the capture backend can see BDO traffic. VPNs and routing services such as ExitLag may require manual interface, local IP, and port settings; automatic detection may select the wrong connection. Traffic visible only as an encrypted tunnel cannot be decoded. Follow Diagnose capture when automatic selection fails to inspect connections on Windows, select grouped capture settings, and verify them with game activity. The guide covers VPNs, local proxies, and cases where no usable adapter is found. Discovery does not apply settings or verify decoding.

Capabilities

bdo-toolkit exposes four passive workflows. Item activity, item state, and Solare support live capture and saved PCAP or PCAPNG replay. Grind tracking combines supported observations in one live session.

The standalone workflows include synchronous and asyncio sessions, capture and decoder health diagnostics, console and JSONL event writers, and a command-line interface. Exact signatures, fields, lifecycle behavior, and failure contracts are in the API index.

Testing and validation cover NA/EU only. Compatibility with other regional services is unknown.

Installation

python -m pip install bdo-toolkit

Python 3.14 or newer is required. Before live capture, complete Installation & setup, including Npcap on Windows and permission to capture on the selected interface. Offline PCAP and PCAPNG replay does not require Npcap.

Get started

1. Complete Installation & setup.
2. For item events or item state, prepare a current local profile through Opcode profile setup.
3. Run the Quickstart or choose a task from the Examples index.

Local calibration is the dependable patch-day path because maintained profiles require manual verification and may lag a weekly update. The Calibration guide walks through rebuilding one. Arena of Solare uses structural classification and does not require an item opcode profile.

Runnable examples

The source checkout includes maintained, run-ready lessons. They are not installed with the Python wheel.

See the Examples index for every script, its prerequisites, and the guide that explains it.

Support

For questions, contact me on Discord: ._.__.__._._.__._____.__._.___.

For bugs and feature requests, open a GitHub issue.

License

bdo-toolkit is available under the MIT License.