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 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.
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
- 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.
Runnable examples
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.
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.
1 maintainer
Metadata
1 maintainer
Release files for bdo-toolkit 1.0.10
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| bdo_toolkit-1.0.10.tar.gz | 462.4 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bdo_toolkit-1.0.10-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 767.3 kB
Release files / bdo_toolkit-1.0.10.tar.gz
| Download URL | bdo_toolkit-1.0.10.tar.gz |
|---|---|
| Size | 462.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
072b1ce4faa3d5420efcce52f758ba1f17f7ea658251af5303eb139374183a66
|
|
BLAKE2b-256 checksum How to use checksums |
1e0a44e5598aca2ad540944860760b4d2a1c70bedeba839d362c0bb034981f5f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logRelease files / bdo_toolkit-1.0.10-py3-none-any.whl
| Download URL | bdo_toolkit-1.0.10-py3-none-any.whl |
|---|---|
| Size | 304.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fbdc054753d8e544d90a6999dca6f3e51c97c1cabb3870b290dbe928a85764c9
|
|
BLAKE2b-256 checksum How to use checksums |
faa732d561ca505acb56405bb12283f4f9f76bfba922b94a7120f0c98d6b758e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logSecurity for bdo-toolkit 1.0.10
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for bdo_toolkit-1.0.10.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
