AntiGriefv1.5.24
Pythonby TheNINJALLOBlockData-powered anti-grief logging, exact container NBT snapshots, rollback, and WebUI for Endstone.
pip install https://github.com/TheNINJALLO/endstone-antigrief/releases/download/v1.5.24/endstone_antigrief-1.5.24-py3-none-any.whl- Stars
- 4
PLUGINSANTIGRIEF
# Install
Use the animation for reference. Follow the plugin's README for exact steps.
# README
Overview
BlockData-powered anti-grief logging, exact container NBT snapshots, rollback, and WebUI for Endstone. This release targets BlockData API 0.6.9 on Endstone 0.11.15, Minecraft Bedrock Dedicated Server 1.26.60.6, and CPython 3.14 on Linux x86-64. AntiGrief is distributed as a Python wheel for direct installation in an Endstone server.
What it does
- Records block changes, player interactions, and container activity through the BlockData API.
- Captures exact container snapshots so staff can inspect and restore item-level changes.
- Provides searchable audit history, player/device bans, rollback tools, and a browser-based review interface.
How to use
- Install and enable the required
blockdata-apiplugin before AntiGrief. - Start the server once, then review the generated database and WebUI settings in the plugin data folder.
- Use
/agfor a local lookup,/agsfor staff searches, and/agbackonly after reviewing the matching records. - Grant
antigrief.command.oponly to trusted investigators; normal players receiveantigrief.command.memberby default.
Commands and permissions
| Command / usage | What it does | Access |
|---|---|---|
/ag [pos:pos] [time:float] [radius:float] | Query nearby audit records | antigrief.command.member |
/aghelp | Show AntiGrief command help | antigrief.command.member |
/agban <player:str> [reason:str] | Ban a player from the server | antigrief.command.op |
/agunban <player:str> | Remove a player ban | antigrief.command.op |
/agbanlist | List AntiGrief player bans | antigrief.command.op |
/ban-id <deviceID:str> | Ban a device identifier | antigrief.command.op |
/unban-id <deviceID:str> | Remove a device ban | antigrief.command.op |
/banlist-id | List banned device identifiers | antigrief.command.op |
/ags [type:str] [keyword:str] [time:float] | Search audit records by type, keyword, and time | antigrief.command.op |
/agback <time:float> [pos:pos] <radius:float> [player:str] | Roll back matching block and container changes | antigrief.command.op |
/ago [player:str] | Inspect a player's recent activity | antigrief.command.op |
/agclean <hours:float> | Delete audit data older than the requested age | antigrief.command.op |
/density [size:int] | Find nearby entity-density hotspots | antigrief.command.op |
/agcontainer [player:str] [hours:float] [radius:float] | View container access logs (items taken/added) | antigrief.command.op |
/agowner <action:str> [pos:pos] [player:str] | Set, inspect, trust, or clear a container owner | antigrief.command.op |
/agstop [rollback_id:str] | Cancel all pending rollback work, or one batch by recovery ID | antigrief.command.op |
/agconfiscate <player:str> | Retry item recovery from an administrator-confirmed rollback | antigrief.command.op |
Compatibility
| Component | Supported version |
|---|---|
| Endstone | 0.11.15 |
| Endstone API | 0.11 |
| Bedrock Dedicated Server | 1.26.60.6 (Minecraft 1.26.60) |
| BlockData API | 0.6.9 complete inspector bundle wheel |
| Native runtime | Linux x86-64, CPython 3.14 |
| Plugin release | v1.5.24 (local candidate) |
Install
Download the wheel from the matching GitHub release:
gh release download v1.5.23 --repo TheNINJALLO/endstone-antigrief --pattern "*.whl"Copy the downloaded wheel into the server's plugins/ directory, remove any older wheel for the same plugin, and restart Endstone.
Important
Use BlockData 0.6.9 with Endstone 0.11.15, BDS 1.26.60.6, and CPython 3.14 on Linux x86-64. See the installation guide for the complete bundle and upgrade steps.
Configuration and secrets
Runtime databases, logs, local .env files, server directories, and root config.toml files are excluded from source releases. When an example configuration is provided, copy it locally and keep live tokens, passwords, webhook URLs, and server identifiers out of Git.
Release automation
Every v* tag runs the wheel release workflow, builds the package in a clean GitHub runner, stores the wheel as a workflow artifact, and attaches it to the matching GitHub release.
Project guide
A player-behavior audit, exact container backup, rollback, and security dashboard plugin for Endstone Minecraft Bedrock servers.
What changed in v1.5.1
AntiGrief now uses Endstone BlockData API as its native block and container data source. Container records are no longer limited to item IDs and counts. The plugin captures the live block actor and stores:
- Block type, runtime ID, block states, dimension, coordinates, and revision
- Canonical block-entity NBT and raw SNBT
- Every occupied container slot
- Full item payloads, including names, lore, enchantments, durability, nested shulker contents, and other supported tags
- Before-and-after snapshots for container access auditing
- Snapshot IDs that link event rows to the full NBT record in the WebUI
Rollback recreates the block in the correct dimension, waits one server tick for its block actor to exist, then atomically restores its states, block-entity NBT, and exact inventory through BlockData.
Required dependency
Install a matching release of TheNINJALLO/endstone-blockdata-api before AntiGrief.
The BlockData installation must include both files from the complete platform ZIP:
Install endstone_blockdata_inspector-0.6.9-cp314-cp314-linux_x86_64.whl from the BlockData v0.6.9 deployment ZIP. This complete wheel contains the Python bridge and loads its matching native blockdata_api provider automatically. Do not install an additional standalone provider library alongside it.
The BDS version, Endstone version, Python ABI, platform, and BlockData release must match. AntiGrief declares depend = ["blockdata_api"] and dynamically loads the bridge shipped in the matching inspector wheel.
The supported native set is BlockData v0.6.9, BDS 1.26.60.6, Endstone 0.11.15, and CPython 3.14 on Linux x86-64. The portable SDK wheel alone is insufficient; this BlockData release does not provide a Windows native bundle.
AntiGrief v1.5.18 fixes repeated SQLite flush failures caused by non-UTF-8 item NBT. It escapes canonical JSON for storage and preserves the original bytes for restore. Update AntiGrief as well as BlockData: safe diagnostic SNBT alone does not fix older AntiGrief JSON serialization. The update does not require a database migration.
Installation
- Stop the server.
- Remove older duplicate BlockData native plugins, inspector wheels, and AntiGrief wheels from
plugins/. - Copy the complete BlockData 0.6.9 inspector bundle wheel into
plugins/. - Copy
endstone_antigrief-1.5.24-py3-none-any.whlfor the local candidate (or1.5.23from the published release) intoplugins/. - Start the server and verify the console reports
BlockData API connected. - Change the WebUI secret in
plugins/antigrief_data/config.jsonbefore exposing the dashboard.
The old antigrief_companion_bp is no longer required for v1.5.1. It remains in the source package only as a rollback compatibility path for database records made by older AntiGrief versions.
Configuration
{
"record_nature_block": true,
"record_human_block": true,
"only_record_important_animal": true,
"10s_message_max": 6,
"10s_command_max": 12,
"enable_web_ui": true,
"no_log_mobs": ["minecraft:item", "minecraft:xp_orb"],
"web_ui_port": 8098,
"web_ui_secret": "change_this_secret_key",
"require_blockdata_api": true,
"capture_container_open_close": true,
"store_raw_snbt": true,
"build_legacy_history_index": false
}Database layout
interactions
Stores the compact event stream for block breaks, placements, explosions, interactions, attacks, joins, commands, and slot-level container changes. BlockData-backed rows include a snapshot ID or exact before/after item payloads in blockdata.
container_snapshots
Stores complete detached BlockData snapshots:
snapshot_id- player/reason/time
- position and dimension
- block type and revision
- occupied-slot and item totals
- canonical-NBT flag
- full snapshot JSON
- raw SNBT
Indexes are created for event time, snapshot time, and world position. /agclean removes expired interaction rows and container snapshots together.
Exact container auditing
When a player opens a supported container, AntiGrief stores a native baseline snapshot. Inventory transactions and authoritative item-stack responses schedule an exact slot comparison on the next server tick, after BDS commits the change. The baseline advances after each comparison, so adds and takes across successive ticks remain separate records even if the final inventory matches its opening state. Notifications in the same tick are combined into one comparison of the committed state; this does not reconstruct every intermediate transfer within that tick. Client and server closes, disconnects, and plugin shutdown capture any remaining changes. Logged events include:
Container AddContainer TakeContainer ChangeContainer NBT Changefor non-inventory actor metadata such as custom names or locks
The database writer flushes buffered records every 20 seconds. Refresh the WebUI after that interval and select the Container action filter to see item changes. Tracking requires capture_container_open_close to remain enabled; full item NBT requires a connected BlockData provider. The 1.5.20 event/persistence/dashboard regression suite runs without BDS; validation against a live player session is still pending.
Slot changes contain the slot, amount, full before item, full after item, revisions, and links to the before/after complete snapshots. Metadata changes include the before/after canonical actor NBT with inventory and coordinate fields removed for a clean comparison.
Supported containers include chests, trapped chests, all oxidation/waxing variants of copper chests, barrels, hoppers, droppers, dispensers, furnaces, blast furnaces, smokers (including their lit block types), brewing stands, wood shelves, chiseled bookshelves, crafters, decorated pots, and all shulker-box colors supported by the installed BlockData adapter. Direct shelf/bookshelf/pot interactions also schedule a committed-state comparison without requiring a window-close packet.
Rollback
/agback <hours> <x y z> <radius> [player]Examples:
/agback 1 100 64 -200 10
/agback 24 100 64 -200 20 SteveFor a broken or exploded container, rollback:
- Recreates the original block and block states in its recorded dimension.
- Schedules restoration one server tick later on the Endstone server thread.
- Captures the new block actor revision.
- Applies canonical block-entity NBT and exact slot contents using optimistic revision checking.
- Retries a revision conflict once with an explicit force policy.
- Stores a new
rollback_restoredsnapshot for auditing.
WebUI
Open http://SERVER-IP:8098 and authenticate with the configured secret.
Press Enter or APPLY to search. Player filters trim surrounding spaces; areas accept X Y Z Radius or comma-separated values, with radius 0 selecting one position. Search failures are shown explicitly, while successful empty searches say no events match. The CONNECTED badge describes the dashboard's API connection. New buffered events can take up to 20 seconds to appear. Dashboard API requests preserve a proxy URL prefix and send the access key in a header.
The event table now has a VIEW NBT control. The detail viewer exposes:
- Full stored event or snapshot JSON
- Canonical block-entity NBT
- Exact inventory slots and item NBT
- Raw SNBT, when enabled
API routes:
GET /api/logs
GET /api/logs/{log_id}/blockdata
GET /api/container-snapshots
GET /api/container-snapshots/{snapshot_id}
GET /api/stats
GET /api/bansPass the secret through the X-Secret-Key header or the existing secret query parameter.
Commands
| Command | Description | Permission |
|---|---|---|
/ag | Query logs | Member |
/ags | Search logs | OP |
/agback | Roll back block and container changes | OP |
/agstop | Cancel pending rollback work and item recovery | OP |
/agcontainer | View container access changes | OP |
/agclean | Remove old events and snapshots | OP |
/agban, /agunban, /agbanlist | Player bans | OP |
/ban-id, /unban-id, /banlist-id | Device bans | OP |
/density | Find entity-density hotspots | OP |
Building
python -m pip install build hatchling
python -m build
pytest -qThe AntiGrief wheel is pure Python. The BlockData native bridge is not bundled into it and must come from the matching BlockData platform release.
License
MIT License. The BlockData API dependency is distributed under its own Apache-2.0 license.
v1.5.1 startup crash fix
- Removed access to Endstone's native
Plugin.loggerproperty from the Python constructor. - Runtime state and the BlockData adapter are now initialized in
on_load(), after Endstone attaches the native plugin wrapper. - This fixes the Linux SIGSEGV seen in
pybind11::type_caster_base<endstone::Logger>duringPyPluginLoader::loadPlugins.
1.5.23 database startup hotfix
Skip building the additional coordinate/time history index by default. This fixes the 1.5.22 startup failure when its index build exhausts database, server-quota, or temporary storage. Existing indexes and audit history are retained. Administrators can opt in with build_legacy_history_index: true after checking available storage; optional maintenance failures no longer undo completed database setup or prevent startup. Audit writes still require free space. See troubleshooting.
1.5.22 container performance and BlockData 0.6.9
Routine container-access and item-change messages no longer fill the console. Audit history and unauthorized-access details remain available in the database and WebUI. Container ownership/trust lookups use a bounded cache, unchanged native revisions skip diff work and duplicate close snapshots, and player inventory scans run across multiple ticks. Known ordinary block placements no longer schedule native container checks.
Target the new Endstone 0.11.15 / BDS 1.26.60.6 native release. Recognize the bridge's canonical and snbt block-entity fields for snapshot metadata, audit rows, and WebUI inspection, while continuing to read older AntiGrief field names. Disabling store_raw_snbt excludes both SNBT field names from stored container snapshots. Existing databases and configuration are retained.
See validation for local regression and Python benchmark results. Live BDS load testing remains pending.
1.5.19 recovery hotfix
Recovery retries no longer refill containers. Run /agstop (console: agstop) to cancel all pending rollback work and saved recovery queues, or /agstop <recovery ID> for one batch. Cancellation persists across restarts and leaves already-applied changes in place. See the rollback guide for the upgrade procedure when an older server is already duplicating items.
1.5.18 dependency repair
AntiGrief 1.5.18 introduced preference for the current BlockData inspector bridge, rejection of mismatched native/bridge versions, and reconnection after stale service failures. That release was qualified with BlockData 0.6.6; see installation for the current supported bundle and runtime.
The exact released AntiGrief and BlockData wheels passed a disposable BDS integration test covering native service startup, container and item NBT, nested bundles, invalid-write rejection, and clean shutdown. Validation results and artifact hashes.
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.