VonixGuardian — Filter Mini-Language

VonixGuardian uses a unified filter parser across /vg lookup, /vg rollback, /vg restore, and /vg purge. Multiple filter tokens compose via boolean AND.

1. Filter Tokens Reference

Filter	Syntax & Examples	Description
Users (`u:`)	`u:Steve` `u:Steve,Alex` `u:#fire,#tnt,#creeper` `u:#mob:minecraft:zombie`	Targets actors. Accepts player usernames, comma-separated lists, and `#sentinel` tokens.
Time (`t:`)	`t:1h` `t:2w5d7h` `t:2.50h` `t:1h-2h`	Time window backwards from current timestamp. Units: `s` (seconds), `m` (minutes), `h` (hours), `d` (days), `w` (weeks). Supports decimal and range syntax.
Radius (`r:`)	`r:10` `r:100` `r:#global` `r:#overworld` `r:#nether`	Distance in blocks from player. Defaults to `r:10` for rollbacks if omitted. `#global` removes distance bounds. Dimension aliases bound to named worlds.
Actions (`a:`)	`a:block` `a:+block` `a:-container` `a:kill,chat`	Action categories or granular tokens. Prefix `+` includes only; `-` excludes.
Include (`i:`)	`i:minecraft:diamond_ore` `i:stone,dirt` `i:create:gearbox`	Include only actions involving these namespaced block, item, or entity IDs. Comma-separated.
Exclude (`e:`)	`e:minecraft:air` `e:minecraft:leaves`	Exclude matching namespaced target IDs from the query or rollback.
World (`w:`)	`w:minecraft:overworld` `w:the_nether`	Explicit dimension target. Defaults to the player’s current dimension if not specified.
Flags (`#`)	`#preview` `#count` `#verbose` `#silent` `#optimize`	Modifier directives: preview in glass, return counts only, dump raw NBT/tags, suppress staff broadcast.

2. Action Types Reference

VonixGuardian categorizes events under 40 distinct action types. You can target umbrella categories or granular tokens:

Umbrella Categories

a:block — All block break, place, form, fade, burn, and ignite events.
a:container — All container slot transactions (insert and remove).
a:item — All item drops, pickups, and craft operations.
a:entity — Entity kills, spawns, and entity block alterations.
a:player — Player sessions, chat, commands, kicks, and deaths.
a:world — Passive environmental events (leaf decay, fluid flow, spread).

Granular Action Tokens

block_break     block_place     block_burn      block_ignite
block_form      block_fade      block_spread    block_dispense
piston_extend   piston_retract  bucket_empty    bucket_fill
leaves_decay    sign_change     container_in    container_out
item_drop       item_pickup     item_craft      entity_kill
entity_spawn    entity_change_block             explosion
explosion_block player_join     player_quit     player_chat
player_command  player_kick     player_death    player_respawn

VG-Specific Expansion Tokens

VonixGuardian provides 22 granular expansion tokens for advanced operator queries: burn, ignite, fade, form, spread, dispense, piston, bucket, fluid, decay, hanging, spawn, einteract, hopper, craft, grow, portal, populate, entityblock.

3. Sentinel Tokens (Universal Attribution)

When damage or alterations are initiated by a non-player source, VonixGuardian records a #sentinel token in the source_tag column while tracing back to the responsible player UUID:

Sentinel	Event Trigger
`#fire`	Natural fire spread or flint-and-steel ignition.
`#tnt`	TNT detonation (correlates to player if primed by ignition).
`#creeper`	Creeper explosion.
`#explosion`	Generic explosion (wither skulls, end crystals, ghast fireballs).
`#natural`	Environmental physics: leaf decay, liquid flow, ice melt.
`#natural:raid`	Block modification or kill occurring during an active raid.
`#mob:<namespace>:<entity>`	Entity action (e.g., `#mob:minecraft:enderman`, `#mob:dragonmounts:fire_dragon`).

Dual-Column Attribution

If a player rides a mount or fires a projectile, VonixGuardian stores both the sentinel in source_tag and the player’s identifier in actor_uuid. You can query using either u:Steve (to see everything Steve caused directly or indirectly) or u:#mob:dragonmounts:fire_dragon.

4. Hash Flags Reference

Append hash flags to modify command execution:

#preview — Renders the proposed rollback using temporary glass blocks without altering world state. Glass renders client-side or non-permanently, allowing staff to verify coordinates.
#count — Skips row pagination and prints an aggregate count of matching rows.
#verbose — Displays complete raw NBT payloads, pair_id, and source_tag values in chat or console.
#silent — Suppresses the default broadcast notification sent to other online staff members.
#optimize — dialect maintenance flag: MySQL runs OPTIMIZE TABLE, PostgreSQL runs VACUUM ANALYZE, SQLite runs VACUUM. Use during low activity.

5. Practical Operator Recipes

Investigate Base Damage

Find who modified blocks within 20 blocks in the past 12 hours:

/vg lookup r:20 t:12h a:block

Check Container Thefts

See what was removed from containers in the area:

/vg lookup r:5 t:3d a:container_out

Track Down Modded Griefing

Find block destruction caused by modded dragons or contraptions:

/vg lookup u:#mob:dragonmounts:fire_dragon t:6h a:block_break #verbose

Scope to Specific Items

Find who deposited or withdrew Netherite Ingots:

/vg lookup a:container i:minecraft:netherite_ingot t:7d

WorldEdit Radius Note

Passing r:#worldedit or r:#we is accepted by the parser for CoreProtect muscle-memory compatibility. However, in 3.0.0-m1, WorldEdit selection bounding boxes are not natively bridged; the filter defaults to global unbounded scope.