Repository navigation
v2.3.0
VonixGuardian v2.3.0
Server-side block, inventory, and entity auditing with rollback tools for modded Minecraft.
Highlights
Taken from CHANGELOG.md section [2.3.0]. Schema version is 9.
Command replies now say what happened, and the dangerous commands do what their flags
claim. A purge marked as a preview or a count leaves the log in place. Changing one
actions setting keeps the item and entity blacklists. Undo is described as what it is,
a second change to the world. Rollback, lookup, and status are written so the outcome
and the number that matters are visible on the first read.
Every claim below was checked against this tree's source, not copied from a commit
message. What could not be verified is named in Verification and is not asserted;
what was checked and found still broken is in Known open.
Breaking changes
- A purge with no world selector covers every world. The reply names the scope it
used (all worlds, or the world you named). Limit a purge withr:#nether,
r:#overworld,r:#end, orr:#world_<name>. Rollback and lookup still default to
the world you are standing in. - A window such as
t:1h-2hdeletes only rows inside that window. A single age such
ast:90dstill deletes rows older than that age. The safety floor is checked against
the newest row that would be deleted, so a window reaching into the last 30 days
(in-game) or 24 hours (console) is refused even when its older edge is old enough. - Rollback output no longer contains
affected=. A check that parsed the old
key=value line will not find it. Zero counters are omitted from the line entirely.
A clean rollback readsDone — SUCCESS; a result needing repair reads
Needs repair — REPAIR_REQUIRED. - Chat colours are lighter. In the default
aquatheme, block and item ids are
near-white (#F4FFFF) instead of#00AAAA, which measured 3.85:1 against a mid-grey
chat background — below WCAG AA — and disappeared against a bright scene.
Added
/vg batch,/vg batch show <id>,/vg batch close <id>(permission
vonixguardian.rollback). List shows open batches with mode and action count; show
lists the action ids the batch covered; close marks the audit row finished. Close does
not replay the rollback, undo it, delete its action rows, or otherwise touch the world,
and the reply says so on every path — including "already closed" and "no such batch".
Registered in all ten command cells.- Purge preview prints the match count, up to eight sample rows (world, coordinates,
target, actor), and how many more match. Nothing is deleted. - Lookup rows show the world, the item amount where one applies, and a UTC clock time
beside the relative time. Sign side, dye colour, and waxed state appear when stored.
#verboseadds the inventory slot, source tag, paired row id, and the before/after
block state. The row id is click-to-copy, the target copies its full id, and the
coordinates offer/vg tpin the chat box. Where a client's chat API refuses the
click event, the text still renders. - A command failure names the failure. When a throwable carries no message — the
common case — the reply uses the exception type instead of printingnull.
Fixed
/vg purge #previewand/vg purge #countdeleted rows. The documented dry run
performed the purge: the flags were copied onto the filter and never read. They now
count (preview also samples) and call neither the delete nor the optimize path./vg purgesilently narrowed to the caller's world. The handler applied the
sender's world as a default, so an operator standing in the Overworld purged only the
Overworld and was told the row count as if that were the whole server. A bare purge
now spans every world and names the scope; ar:selector is kept as given.- A two-sided time range inverted the purge window.
t:1h-2hdeleted everything
older than the newer edge. It now deletes only rows inside the window. /vg config seton anactionskey wiped both blacklists to disk. The handler
rebuilt theActionsblock through a compatibility constructor that substitutes empty
lists foritemBlacklistandentityBlacklist, then saved it. Every write now starts
from the live block and changes one field.- Rolling back several edits of one block restored only the newest and reported
skipped=0. Older rows at an already-planned position were dropped from the plan
without being counted, so rows the operator asked about vanished from the operation
entirely. They are now counted as skipped; the newest row is still the one applied. - A failed rollback left its batch open forever and logged one WARN per affected
action on every boot. Boot now logs a single line naming the open batch ids and the
action count, and points at/vg batch. /vg statusread the database on the server thread. The report is built off-thread
and the lines are sent back on the server thread. On a slow or remote database the
diagnostic no longer stalls the tick it is being used to investigate./vg statuslabelledSELECT 1as "health". A trivial query cannot see a locked
table, a full disk, or a permission failure, so the row is nowreachableand states
what answered. The schema row readsvg_schema_versionand compares it with the
version this jar creates, so drift is named instead of assumed. A configured theme
name that is not registered is reported rather than silently resolved away./vg statusflooded chat. 62 lines with[VonixGuardian]on every one is now a
one-sentence opener plus five sections (version, storage, writer, recovery,
configuration) with the brand on the first section only. Counters that answer one
question share a row; per-type and per-batch detail still prints when it exists.r:#worldeditanswered "no results" when WorldEdit was absent, no selection
existed, or the selection could not be read. Each case now names itself./vg helpdescribed undo as dropping history. It now says undo changes the world
again. The command list is rendered fromCommandSpec, so it cannot omit a
subcommand that the spec knows about. It still does not list the registered
compatibility literals that are not in the spec (inspector,page,stats,
version) or there/roaliases — see Known open.- Error paths ended in the word
null. See Added. - A paused audit writer could let one row escape and accept another in the same
instant. The worker had already removed the held row when pause became visible, so
the queue looked empty. The row goes back and the next submit is rejected and recorded.
Changed
- The rollback line reconciles against the plan. It reports the plan total whenever
it differs from what changed (251 changed (of 468 planned)), and states plainly when
a gap has no other explanation —unplannedGapnames the remainder rather than leaving
the operator to subtract. The formatter accepts a per-reason skip histogram and will
render it, but no caller supplies one yet, so the line reports the skip total only. #counton rollback and restore is one line and says nothing was changed.
#previewsays how many blocks would change and that the world was not changed.#verboseon a lookup adds its fields on the same line rather than a second row;
the hover text carries the same detail without the flag. Long names are shortened on
screen while the click-to-copy value keeps the full id.- All fifteen language bundles now carry the full 32-key set. Fourteen bundles held
7 of 32 keys, so a non-English locale silently fell through to English for the other
25. Thett(Tatar) bundle resolves every key but keeps 29 lines in English
deliberately, each marked#TODO-i18nwith the reason, rather than inventing a
translation. The bundles only cover the parser and status vocabulary; every command
reply inGuardianCommands,LookupText, andMutationOutcomeFormatteris still a
hardcoded English literal — see Known open. /vg batchclosing an audit row is reported separately from changing the world.
The two are never conflated in one sentence.
Removed
LookupPermissionFilter.filter()— unreachable; the live path usesvisiblePage()
andcountVisible(). Proven unreachable by grep before deletion.CommandSpecaliases no loader registers (nfor near,?for help), and
Lookup.atPoson the 1.18.2 Forge cell. The spec had drifted from the real command
tree; the drift was removed rather than the tree changed to match it.
Known open — verified against this tree at release
Re-checked at the tip of the released commit, not carried forward from the candidate.
Items that were open when this entry was drafted and are now fixed have been removed
rather than left to mislead a reader.
| Issue | Effect |
|---|---|
a:+block / a:-block sign is parsed but not compiled into SQL |
QueryParser records PLACE_ONLY / BREAK_ONLY; no SQL builder reads it. Place-only and break-only filters therefore behave as the whole family. |
/vg help omits four registered literals |
inspector, page, stats and version exist in the command tree but not in CommandSpec, so the rendered list leaves them out. |
Ten near-duplicate GuardianCommands copies |
A single defect must be fixed ten times. A parity test now fails if the copies diverge, but the duplication remains — CommandTree has no consumer yet. |
| Command replies are not translatable | Every reply in GuardianCommands, LookupText and MutationOutcomeFormatter is a hardcoded English literal. The bundles translate player-facing parser errors only, so language=de changes those and little else. |
| No benchmark, so no performance claim | PerfReport exists but there is no method document, and the block-write hook added in this release runs on every block change. No number is asserted anywhere in this entry. |
| Endpoint is a single server; no MySQL runtime test | Every runtime check in this release ran against SQLite. A panel-MySQL deployment is untested. |
Fixed since the candidate was drafted, and therefore removed from this table:
ITEM_DROP / ITEM_PICKUP are now rollbackable; the 32 previously-unlogged interaction
types are hooked; #preview marks positions in the world; lookup.maxResultRows applies
to a live DAO; and /vg undo survives a restart via the persisted batch record.
Coverage: changes made by other mods are now visible
- The mod hooked game events, and an event only fires for paths vanilla chose to
instrument. A dragon's breath, a modded explosion, a custom machine, a ritual, or a
teleport that swapped terrain wrote blocks without raising anything we listened for, so
none of it reached the log — and a rollback cannot undo what was never recorded. On a
modded server that is most of the interesting grief. BlockWriteMixinnow hooksLevelChunk.setBlockState, the single point every block
write in the game passes through whoever initiates it. A change made by a mod that has
never heard of VonixGuardian is recorded like any other. This is the approach Ledger
takes, and the reason it attributes a ridden dragon's blast without a dragon-specific
hook.- Duplicate suppression is the load-bearing part. A player break raises
BlockEvent.BreakEventand callssetBlockState, so a naive hook would log every
break twice — once attributed, once as unknown.RecentBlockWriteskeeps a bounded,
2-second record of positions the attributed layer just wrote and the fallback stays
silent for those. - Unattributed changes record
UNKNOWNas the actor, not a guess. The write hook
genuinely cannot tell who caused a change; naming a suspect would be worse than
admitting it does not know.
Verification
What was and was not proven for this entry:
- Source-verified. Every behaviour above was read out of the implementation named in
the item, at the tip of this branch. Nothing here is inferred from a commit message. - Test suite: 1,517 tests, 0 failures. Run on the core module at the tip of this
branch. The number counts the tests this entry added; it is not a restatement of an
earlier figure. - Runtime-verified on a live server, and it found four defects that no gate caught:
- A mixin helper in the mixin package crashed the server.
MixinLoggingSupport
sat inforge.mixinwhile thirteen mixins called it; Mixin forbids that reference and
threwIllegalClassLoadErroron the server thread when sugar cane grew.MixinAuditSupport
andAnvilPositionshad the same defect. All three moved toforge.support, and
MixinPackagePurityTestnow fails the build if any non-mixin class sits in a declared
mixin package. - Ignite rollback was inverted. The row recorded the block that appeared (fire) as
the rollback target, so undo tried to re-place fire over the ground it had already
burned. It now records the block the fire consumed. - Explosion rows demanded 96/96 blocks. A handful of unplaceable positions is normal
in a blast, so every large explosion becameREPAIR_REQUIREDand left its batch open —
a griefing rollback could never report success. Now: nothing restored stays a plain
failure, over 25% missing escalates, and anything between is logged and continues. - Ridden-mount explosions were attributed to nobody.
Explosion.getSourceMob()
returns null for a non-living source, so a player riding a dragon and burning a base
produced rows with no actor. Attribution now falls back togetExploder(), which
returns the source entity regardless of type, and the existing resolver credits the
controlling rider.
- A mixin helper in the mixin package crashed the server.
- Not verified. A real MySQL-backed deployment is untested; every runtime check so far
ran against SQLite. Rollback of the two defect classes above was exercised from the log,
not from a clean world with a known-good target state. - Not compiled for the other six cells. Only
mc-1.18.2/forgewas built for this entry.
Thirteen primary jars share version 2.3.0. The NeoForge 26.3 cell is built against the NeoForge loader pin 26.3.0.6-beta. The jar name is vonixguardian-neoforge-26.3-2.3.0.jar.
This release covers the thirteen Fabric, Forge, and NeoForge cells below.
Public wiki: https://modwiki.vonix.network/mods/vonixguardian/
Drop-in jars
| MC version | Fabric | Forge / NeoForge |
|---|---|---|
| 26.3 | vonixguardian-fabric-26.3-2.3.0.jar |
vonixguardian-neoforge-26.3-2.3.0.jar |
| 26.2 | vonixguardian-fabric-26.2-2.3.0.jar |
vonixguardian-neoforge-26.2-2.3.0.jar |
| 26.1.2 | — | vonixguardian-neoforge-26.1.2-2.3.0.jar |
| 1.21.1 | vonixguardian-fabric-1.21.1-2.3.0.jar |
vonixguardian-neoforge-1.21.1-2.3.0.jar |
| 1.20.1 | vonixguardian-fabric-1.20.1-2.3.0.jar |
vonixguardian-forge-1.20.1-2.3.0.jar |
| 1.19.2 | vonixguardian-fabric-1.19.2-2.3.0.jar |
vonixguardian-forge-1.19.2-2.3.0.jar |
| 1.18.2 | vonixguardian-fabric-1.18.2-2.3.0.jar |
vonixguardian-forge-1.18.2-2.3.0.jar |
Pick the matching jar for your server, drop into mods/, restart.
Verifying
SHA-256 checksums are in SHA256SUMS. Run:
sha256sum -c SHA256SUMS
Configuration
On first boot, the mod writes config/vonixguardian/config.json. See README for the full schema.
Commands
/vg inspect, /vg lookup, /vg rollback, /vg restore, /vg purge, /vg near, /vg undo, /vg status, /vg reload, /vg help. Alias: /guardian.
See CHANGELOG.md for the full feature surface.