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.
Capabilities
| In-game task | Python result | Status | Guide |
|---|---|---|---|
| Watch supported item changes such as loot, gathering, and storage activity | A continuing stream of typed BDOEvent objects |
Stable | Item events |
| Log in or switch characters | One observational ItemStateSnapshot of inventory, known balances, and town storage |
Beta | Inventory & town storage |
| Load the Arena of Solare Leaderboard | One SolareCaptureResult; a complete result contains a leaderboard snapshot |
Beta | Arena of Solare |
Testing and validation cover NA/EU only. Compatibility with other regional services is unknown.
Installation
python -m pip install bdo-toolkit
Python 3.10 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 |
| 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.
Documentation
The documentation separates task-focused guides from the symbol-first API reference. Exact signatures, fields, lifecycle behavior, and failure contracts live there rather than in this README.
| Goal | Start here |
|---|---|
| Understand the package | Overview |
| Build with live item events | Item events |
| Query character inventory and town storage | Inventory & town storage |
| Rebuild item decoding after a patch | Calibration |
| Capture and query an Arena of Solare leaderboard | Arena of Solare |
| Integrate with an asyncio application | Asyncio integration |
| Look up a class, function, or model | API index |
| Use the terminal interface | Command line |
| Diagnose a problem | Troubleshooting |
| Review data handling and project boundaries | Safety & privacy |
Support
For questions, contact me on Discord: ._.__.__._._.__._____.__._.___.
For bugs and feature requests, open a GitHub issue.
Development
git clone https://github.com/ychwu/bdo-toolkit.git
cd bdo-toolkit
python -m pip install -e ".[dev]"
python -m pytest -q -W error
python -m mypy src/bdo_toolkit
python -m pip wheel . --no-deps --wheel-dir dist
CI runs tests, type checking, wheel construction, and a CLI smoke test on Ubuntu and Windows with Python 3.10 and 3.14. Tests that require private game-session captures skip when those local fixtures are absent.
License
bdo-toolkit is available under the MIT License.
1 maintainer
Metadata
1 maintainer
Release files for bdo-toolkit 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| bdo_toolkit-1.0.0.tar.gz | 340.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bdo_toolkit-1.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 558.1 kB
Release files / bdo_toolkit-1.0.0.tar.gz
| Download URL | bdo_toolkit-1.0.0.tar.gz |
|---|---|
| Size | 340.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e0b56cd9f84a8c5d896b517caaf9265bfd490a6826e2cbfd3c9fa7112e804eab
|
|
BLAKE2b-256 checksum How to use checksums |
ebf45c5ba902713edeb8ef410c8a2069b2b67fe2940a617f3e896b7b2ca0d28a
|
| 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 Aug 31, 2026.
Transparency logRelease files / bdo_toolkit-1.0.0-py3-none-any.whl
| Download URL | bdo_toolkit-1.0.0-py3-none-any.whl |
|---|---|
| Size | 218.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
23724de80715cd837e49b64ff024909093dd37fa75ee11b56ffb9eb618661186
|
|
BLAKE2b-256 checksum How to use checksums |
b1ec678a972c65a4f003730ef3000845d382da9c9392c19c7dcad0920d86f0d3
|
| 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 Aug 31, 2026.
Transparency log
