ItemGraph

ItemGraph

Trace item movement through time.

ItemGraph is a server-side Minecraft moderation and forensic analysis mod for NeoForge 1.21.1.

Existing loggers such as GriefLogger and CoreProtect are excellent at recording what happened at a single coordinate. When items move across players, ground drops, and containers, server administrators still have to reconstruct the chain manually. ItemGraph adds that missing reconstruction layer.

Instead of assigning artificial, invasive UUIDs to every Minecraft item, ItemGraph models item history as a directed temporal multigraph using canonical component fingerprints and an explicit quantity-allocation ledger.

Evidence first. Inference second. Confidence explicit. Every conclusion traceable.

---

Core architectural principles

1. No synthetic per-item UUIDs. Works with vanilla and modded items without altering item NBT or bloating world saves.
2. Strict quantity conservation. The engine never manufactures quantity. Stack splits and merges are tracked through an explicit allocation ledger.
3. Explicit provenance. Query output distinguishes OBSERVED raw evidence from INFERRED transfers and prints confidence on inferred edges.
4. Read-only integration. GriefLogger's SQLite database is opened read-only. ItemGraph owns its own isolated SQLite storage at run/itemgraph/itemgraph.db.
5. Zero server lag. Graph traversal, historical scans, and invariant audits execute on asynchronous worker threads.

Key features

• Ground bridge reconstruction for player-to-player transfers across ground tosses and pickups.
• Authoritative Minecraft ItemEntity UUID continuity, boosting confidence when the same entity is observed on drop and pickup.
• Transformation tracking across anvil repairs and renames, crafting, and smelting.
• Armor stand and container integration covering armor swaps, chests, barrels, and hoppers.
• Live invariant auditing for quantity conservation, positivity, relational integrity, and lifecycle consistency.

Commands and examples

All commands require permission level 2 (moderator or operator).

Item trace

The item trace reconstructs a complete lifecycle by fingerprint ID, registry ID, or custom name. It distinguishes raw observations from inferred temporal flows and includes timestamps, quantities, and evidence identifiers.

Example: CONTAINER to Alice, Alice to GROUND, inferred Alice to Bob, then GROUND to Bob. Every inferred transfer includes deterministic confidence, candidate counts, spatial and temporal deltas, supporting observations, and evidence IDs.

Player, container, and audit traces

Player traces reconstruct item ingress, egress, container interactions, ground exchanges, and armor stand activity. Container traces show item additions and removals for a specific block coordinate. The audit command runs asynchronously and reports conservation violations, non-positive quantities, orphaned allocations, missing endpoints, and lifecycle inconsistencies.

Installation and requirements

• Platform: NeoForge 1.21.1, tested on 21.1.248 and newer.
• Java: Java 21 or newer.
• Environment: Server-side only. Players do not need ItemGraph installed on their clients.
• Required runtime dependency: GriefLogger, version 1.2.10 or newer for Minecraft 1.21.1.
• Runtime dependencies of GriefLogger: Architectury API and SuperMartijn642's Config Lib.

Project links

• Source code: https://github.com/DurdeuVlad/itemgraph
• Issue tracker: https://github.com/DurdeuVlad/itemgraph/issues

Evidence first. Inference second. Confidence explicit. Every conclusion traceable.