BlockData APIv0.6.9
C++by TheNINJALLONative C++ and Python API for Endstone that exposes block states, block actors, container inventories, item NBT, transactions and snapshots.
- Stars
- 6
PLUGINSBLOCKDATA API
# Install
Use the animation for reference. Follow the plugin's README for exact steps.
# README
Endstone 0.11.15 release 0.6.9: This release includes verified Linux native artifacts. Windows runtime qualification remains pending for this Endstone update. The recorded validation defines the tested scope.
Endstone 0.11.15 update: v0.6.9
This release targets Endstone 0.11.15, BDS 1.26.60.6 / runtime 26.60, and CPython 3.14 on Linux x86-64. Network protocol is 2225. See build status for validation. Qualification uses the default enable-script=true; enable-script=false is unqualified for this release.
The package requirement remains Endstone >=0.11.11 without an upper bound; these native binaries require the exact 0.11.15 runtime. Install the complete inspector bundle wheel, which includes the matching native provider.
Download v0.6.9 for Endstone 0.11.15.
A high-performance, detached Block State, Block Entity, and Canonical NBT manipulation API for Endstone Bedrock Dedicated Servers (BDS).
Designed for complex inventory handling, container snapshots, anti-grief transaction diffing, and live block trait modification without risking world corruption or looper thread lockups.
Documentation & Technical Wiki
Comprehensive guides, architecture diagrams, container audit tutorials, and full API specifications are available on the Docsify Documentation Site.
Direct Release Downloads (v0.6.9)
Use the complete ZIP matching BDS 1.26.60 and the server platform. It contains the self-contained /bd wheel with its matching native provider inside. The raw library is for native-API-only/manual installations.
| Platform | BDS Version | Artifact Filename | Direct Download |
|---|---|---|---|
| Linux x64 ZIP (recommended) | 1.26.60 | endstone-blockdata-api-v0.6.9-bds-1.26.60-linux-x64.zip | Download |
| Linux x64 raw plugin | 1.26.60 | endstone-blockdata-api-v0.6.9-bds-1.26.60-linux-x64.so | Download |
Linux /bd wheel | CPython 3.14 | endstone_blockdata_inspector-0.6.9-cp314-cp314-linux_x86_64.whl | Download |
Architecture Overview
graph TD
A[Bedrock World / Player Interaction] -->|Capture State| B[BlockDataService]
B -->|State & NBT Snapshot| C[BlockSnapshot]
C -->|Construct View| D[ContainerView]
D -->|NBT Item Modification| E[BlockPatch]
E -->|Apply with Policy| B
B -->|Optimistic Revision Check| F[ApplyResult]
C -->|Diff Engine| G[BlockEntityAuditDelta]
G -->|Transaction Event| H[Anti-Grief Audit Log]Quickstart Code Examples
Python API Example
from endstone_blockdata import (
BlockDataService,
ContainerView,
ConflictPolicy,
LiveBlockDataAdapter,
)
# Inside an Endstone plugin, self.server is the live server instance.
service = BlockDataService(LiveBlockDataAdapter(self.server))
# 1. Capture block state & NBT snapshot
snapshot = service.capture("overworld", (100, 64, 200))
print(f"Block: {snapshot.type}, Revision: {snapshot.revision}")
# 2. Inspect & Modify Container NBT
if snapshot.block_entity:
view = ContainerView(snapshot)
# Insert custom item with NBT into slot 0
patch = view.patch_item(0, {
"Name": "minecraft:diamond_sword",
"Count": 1,
"tag": {"display": {"Name": "§6Excalibur"}}
})
result = service.apply(patch, ConflictPolicy.FAIL_IF_CHANGED)
print(f"Apply Status: {result.status}")C++ API Example
#include <endstone_blockdata/live_service.h>
#include <endstone/endstone.hpp>
#include <string>
void onContainerTouch(endstone::Server &server) {
using namespace endstone_blockdata;
auto service = server.getServiceManager().load<LiveBlockDataService>(
std::string(BlockDataServiceName));
if (!service) return; // The native BlockData plugin is not enabled.
BlockLocation location{"overworld", 100, 64, 200};
auto snapshot = service->capture(location);
if (!snapshot) return;
BlockPatch patch;
patch.location = location;
patch.expected_revision = snapshot->revision;
patch.state_updates["minecraft:cardinal_direction"] = std::string("north");
auto result = service->apply(patch, ConflictPolicy::FailIfChanged);
if (!result.ok()) {
server.getLogger().warning("BlockData apply failed: {}", result.message);
}
}In-Game Inspector Test Suite (/bd)
The repository includes the endstone_blockdata_inspector command plugin. Choose the platform-specific CPython 3.14 wheel from the same exact build as the native plugin; its _endstone_blockdata_live bridge is bundled inside the wheel.
Stop the server and remove older BlockData inspector wheels before copying v0.6.9; leaving multiple versions in plugins/ can make Endstone install them in an undefined order.
# Linux example: copy both files from the complete ZIP's plugins/ directory.
cp endstone_blockdata_inspector-0.6.9-cp314-cp314-linux_x86_64.whl /path/to/endstone/plugins/In-Game Command Reference
| Command | Usage | Description |
|---|---|---|
/bd or /bd menu | /bd menu | Opens the guarded in-game menu with navigation for every command below. |
/bd locate [radius] | /bd locate 10 | Uses native region capture to find live container block entities. |
/bd inspect [x] [y] [z] | /bd inspect 100 64 200 | Displays state, revision, a bounded canonical-NBT preview, capacity, and occupied inventory. |
/bd item add <slot> <id> [cnt] [nbt] | /bd item add 0 diamond 64 | Writes a live item with optimistic revision checking. |
/bd item remove <slot> | /bd item remove 0 | Clears a live item with optimistic revision checking. |
/bd audit <start|stop|history> | /bd audit start | Captures and compares live native snapshots. |
/bd state set <prop> <val> | /bd state set facing south | Writes a live block-state property. |
The menu allows only one BlockData form per player, validates every submitted field, and asks for confirmation before inventory or state writes. Closing a submenu navigates back; disconnect, death, plugin shutdown, or form-send failure releases its lock. Typed commands remain available, and the console receives the text help because Bedrock forms are player-only.
Documentation & Wiki
Full technical documentation, architecture deep dives, and API reference manuals are available in the project Wiki:
- 📖 Documentation Index
- 🏗️ Architecture & Memory Model
- 📦 Canonical NBT & Container Systems
- 🎒 Bundle & Storage Item Module
- 🛒 Live Shelf API and Shop Example
- 🧍 Player Inventory Adapter
- 🛡️ Container Transaction Audit Engine
- 📘 Complete API Reference
- 💡 Code Examples & Recipes
License
Distributed under the Apache License 2.0.
0.6.9 dependency repair
The inspector wheel now bundles and loads the matching native blockdata_api provider. Install that complete wheel by itself in plugins/; remove older loose BlockData libraries and inspector wheels while stopped. The deployment ZIP uses the same wheel. See installation. The standalone native library is an optional advanced artifact, not an additional dependency to copy alongside the bundle.
Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.
Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.