Skip to content

v2.3.0

Choose a tag to compare

@Vonix-Network Vonix-Network released this 14 Nov 19:09
· 6 commits to main since this release

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 with r:#nether,
    r:#overworld, r:#end, or r:#world_<name>. Rollback and lookup still default to
    the world you are standing in.
  • A window such as t:1h-2h deletes only rows inside that window. A single age such
    as t:90d still 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 reads Done — SUCCESS; a result needing repair reads
    Needs repair — REPAIR_REQUIRED.
  • Chat colours are lighter. In the default aqua theme, 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.
    #verbose adds 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 tp in 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 printing null.

Fixed

  • /vg purge #preview and /vg purge #count deleted 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 purge silently 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; a r: selector is kept as given.
  • A two-sided time range inverted the purge window. t:1h-2h deleted everything
    older than the newer edge. It now deletes only rows inside the window.
  • /vg config set on an actions key wiped both blacklists to disk. The handler
    rebuilt the Actions block through a compatibility constructor that substitutes empty
    lists for itemBlacklist and entityBlacklist, 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 status read 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 status labelled SELECT 1 as "health". A trivial query cannot see a locked
    table, a full disk, or a permission failure, so the row is now reachable and states
    what answered. The schema row reads vg_schema_version and 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 status flooded 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:#worldedit answered "no results" when WorldEdit was absent, no selection
    existed, or the selection could not be read. Each case now names itself.
  • /vg help described undo as dropping history. It now says undo changes the world
    again. The command list is rendered from CommandSpec, 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 the re/ro aliases — 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 — unplannedGap names 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.
  • #count on rollback and restore is one line and says nothing was changed.
    #preview says how many blocks would change and that the world was not changed.
  • #verbose on 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. The tt (Tatar) bundle resolves every key but keeps 29 lines in English
    deliberately, each marked #TODO-i18n with the reason, rather than inventing a
    translation. The bundles only cover the parser and status vocabulary; every command
    reply in GuardianCommands, LookupText, and MutationOutcomeFormatter is still a
    hardcoded English literal — see Known open.
  • /vg batch closing 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 uses visiblePage()
    and countVisible(). Proven unreachable by grep before deletion.
  • CommandSpec aliases no loader registers (n for near, ? for help), and
    Lookup.atPos on 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.
  • BlockWriteMixin now hooks LevelChunk.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.BreakEvent and calls setBlockState, so a naive hook would log every
    break twice — once attributed, once as unknown. RecentBlockWrites keeps a bounded,
    2-second record of positions the attributed layer just wrote and the fallback stays
    silent for those.
  • Unattributed changes record UNKNOWN as 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 in forge.mixin while thirteen mixins called it; Mixin forbids that reference and
      threw IllegalClassLoadError on the server thread when sugar cane grew. MixinAuditSupport
      and AnvilPositions had the same defect. All three moved to forge.support, and
      MixinPackagePurityTest now 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 became REPAIR_REQUIRED and 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 to getExploder(), which
      returns the source entity regardless of type, and the existing resolver credits the
      controlling rider.
  • 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/forge was 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.