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 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.
bdo-toolkit exposes these 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.
| Capability | What it provides | Guide | Status |
|---|---|---|---|
| Item activity | A continuing stream of typed BDOEvent objects for supported loot, gathering, inventory, and storage changes |
Item events | Stable |
| Inventory and town storage | A finite ItemStateSnapshot assembled from character-load traffic, with inventory, known balances, and observed town storage |
Inventory & town storage | Beta |
| Arena of Solare leaderboards | A finite SolareCaptureResult containing overall rankings, class tables, and player statistics when the capture is complete |
Arena of Solare | Beta |
| Grind tracking | One capture for confirmed mob drops, with optional profile-based Agris and solo XP | GrindSession | Experimental |
| Raw server messages | Every length-framed server-to-client message, opcode-free and undecoded, for protocol research | Raw server messages | Experimental |
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.
python -m pip install bdo-toolkitPython 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.
- Complete Installation & setup.
- For item events or item state, prepare a current local profile through Opcode profile setup.
- 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.
The source checkout includes maintained, run-ready lessons. They are not installed with the Python wheel.
| Workflow | Representative script |
|---|---|
| Observe live item activity | examples/live_transfer_log.py |
| Capture inventory and town storage on character load | examples/live_character_load_snapshot.py |
| Rebuild an item profile after a patch | examples/live_calibrate_profile.py |
| Observe calibration progress and stop on completion | examples/live_calibration_progress.py · async |
| Capture an Arena of Solare leaderboard load | examples/solare_live_snapshot.py |
See the Examples index for every script, its prerequisites, and the guide that explains it.
For questions, contact me on Discord: ._.__.__._._.__._____.__._.___.
For bugs and feature requests, open a GitHub issue.
bdo-toolkit is available under the MIT License.