Filters & parameters#
lookup, rollback, restore, and purge all take the same filter expression.
Filters are whitespace-separated tokens; multiple tokens are ANDed together.
/vg lookup u:Steve t:1h r:20 a:-block i:minecraft:diamond_ore #count
└─ actor └─ time └─ radius └─ action └─ include ───────┘ └─ flag
The parser is strict. An unrecognised prefix or malformed value fails the whole command with a message naming the bad token rather than silently ignoring it.
Parameter reference#
| Token | Value | Multiple | Negative | Notes |
|---|---|---|---|---|
u: |
Player name or #sentinel |
✅ comma-separated | — | Names are 1–16 chars, A–Z a–z 0–9 _. |
t: |
Duration, or duration range | last wins | — | s m h d w. |
r: |
Blocks, or a keyword selector | last wins | — | Requires a player position for numeric radii. |
a: |
Action token or family | ✅ comma-separated | ✅ - prefix |
43 tokens, 8 families, 3 CoreProtect aliases. |
i: |
Namespaced id | ✅ comma-separated | — | Include only these targets. |
e: |
Namespaced id | ✅ comma-separated | — | Exclude these targets. |
#flag |
One of five flags | ✅ | — | #preview #count #verbose #silent #optimize. |
u: — actor#
Matches the player or non-player source that caused the action.
/vg lookup u:Steve
/vg lookup u:Steve,Alex
/vg lookup u:Notch,Intelli t:2h
Player names must be 1–16 characters of A–Z, a–z, 0–9, or _. Anything else
is rejected:
[VonixGuardian] bad token 'u:[email protected]': '[email protected]' is not a
valid player name (letters, digits, underscore; max 16) — did you mean a #sentinel?
Sentinels#
Non-player sources are recorded under a #sentinel actor name rather than a
fabricated username. Filtering on a sentinel matches those rows.
/vg lookup u:#tnt
/vg lookup u:#creeper
/vg lookup u:#fire
/vg lookup u:#mob:isleofberk:night_fury
Mob sentinels use the #mob:<namespace>:<path> shape. Fixed singletons are:
#creeper #tnt #end_crystal #wither_skull
#fireball #portal #hopper #command
#bed #respawn_anchor #fire #lava
#water #piston #fall #drown
#suffocate #magic #zombie #skeleton
#enderman #explosion #fluid #unknown
When the attribution chain resolved a responsible player behind a non-player
event, the row carries both the sentinel and that player's UUID. Use #verbose
to see both columns — that is how a dragon-mount griefer becomes identifiable.
t: — time#
A window measured back from now. Units are seconds, minutes, hours, days, and weeks, and they compose in a single token.
/vg lookup t:1h
/vg lookup t:30m
/vg lookup t:1d12h
/vg lookup t:2w5d7h
/vg lookup t:2.50h
/vg lookup t:2w,5d,7h,2m,10s
Fractions are honoured. Commas between components are tolerated for CoreProtect
compatibility — t:2w,5d and t:2w5d mean the same thing.
A duration that resolves to under one second is clamped to one second rather than becoming "now":
/vg lookup t:0.001s ≡ /vg lookup t:1s
Ranges#
A dash separates two durations and selects a band rather than a trailing window:
/vg lookup t:1h-2h
That means between two hours ago and one hour ago — the older duration becomes the start, the newer the end. Both sides are required.
| Written | Means |
|---|---|
t:1h |
Within the last hour. |
t:1h-2h |
Between 2 hours ago and 1 hour ago. |
t:0m-1h |
Within the last hour, expressed as a range. |
Missing a unit or a number is an error:
[VonixGuardian] bad token 't:5': duration '5' is missing a unit (use one of s, m, h, d, w)
[VonixGuardian] bad token 't:h': duration component must start with a number: 'h'
[VonixGuardian] bad token 't:5y': unknown duration unit 'y' in '5y' — use s, m, h, d, or w
Purge changes the meaning#
In lookup, rollback, and restore, t: selects rows inside the window.
In purge, t: selects rows older than the window:
/vg lookup t:30d ← the last 30 days
/vg purge t:30d ← everything except the last 30 days
r: — radius and world#
Numeric radius gives a spherical selection centred on you.
/vg lookup r:20
/vg rollback r:50 u:Griefer t:1h
The centre is your position at the time you run the command. Radius is bounded by
lookup.maxRadius (10,000 as shipped):
[VonixGuardian] bad token 'r:20000': radius 20000 exceeds configured maximum 10000
Console has no position
A numeric radius from the console is an error, because there is no centre:
[VonixGuardian] bad token 'r:20': r:<n> requires a player position; console
must use r:#global or r:#world_<key>
Use r:#global or a world selector from the console.
Keyword selectors#
| Selector | Effect |
|---|---|
r:#global |
No spatial bound. Explicit whole-universe. |
r:#world_<key> |
Restrict to one world. key may omit the namespace. |
r:#overworld |
minecraft:overworld. |
r:#nether |
minecraft:the_nether. |
r:#end |
minecraft:the_end. |
r:#we, r:#worldedit |
Your current WorldEdit selection. |
/vg purge t:90d r:#world_nether
/vg lookup r:#global a:-block i:minecraft:diamond_ore t:7d
/vg rollback t:15m r:#worldedit
r:#world_ accepts a bare key (r:#world_nether), a namespaced key
(r:#world_minecraft:the_nether), or a modded dimension
(r:#world_twilightforest:twilight_forest). A missing key is rejected:
[VonixGuardian] bad token 'r:#world_': r:#world_<key> requires a world key after '#world_'
WorldEdit selection#
r:#we resolves your live WorldEdit selection into an axis-aligned box at query
time. It requires WorldEdit to be installed, a player source, and an active
selection:
| Condition | Message |
|---|---|
| No WorldEdit | query.error.worldedit_not_installed |
| No selection | query.error.worldedit_no_selection |
| Console source | r:#worldedit reports the same player-position requirement as r:<n> |
a: — action#
Filters by what happened. Three shapes are accepted.
Exact tokens — the 43 canonical action types (+block, -block, kill,
chat, …). A leading + or - also constrains direction.
Families — a bare category name expands to every action in it:
block, container, item, entity, world, message, session,
interact.
CoreProtect aliases — login, logout, inventory.
/vg lookup a:kill
/vg lookup a:block
/vg lookup a:-block ← breaks only
/vg lookup a:+block ← places only
/vg lookup a:container,kill
/vg lookup a:inventory ← deposits and withdrawals
/vg lookup a:login ← same as a:+session
Multiple actions are comma-separated. The full token list, with direction and category for each, is on Action types.
An unknown token fails with the valid set spelled out:
[VonixGuardian] bad token 'a:fly': unknown action 'fly' — valid actions: +block,
-block, +container, -container, … (or families: block, container, item, entity,
world, message, session, interact)
i: and e: — include and exclude targets#
i: restricts results to the listed block, item, or entity ids. e: removes
them. Both take comma-separated namespaced ids.
/vg lookup i:minecraft:diamond_ore t:1h a:-block
/vg lookup e:minecraft:stone,minecraft:dirt
/vg rollback u:Griefer t:1h r:#global e:minecraft:air
The namespace defaults to minecraft: when omitted, and ids are lower-cased:
/vg lookup i:diamond_ore ≡ /vg lookup i:minecraft:diamond_ore
/vg lookup i:create:andesite_alloy
Valid characters in either half are A–Z a–z 0–9 _ - . /. Anything else is
rejected:
[VonixGuardian] bad token 'i:bad id': invalid identifier path 'bad id' in 'bad id'
i: and e: operate on the recorded target — the block placed, the item moved,
the entity killed — not on the actor. Use u: for the actor.
p: — explicit position#
p:<x>,<y>,<z>
Pins the query centre to absolute coordinates instead of your position. This is what the inspector uses internally, and it is available for scripted use:
/vg lookup p:128,64,-342 r:16 t:7d
A malformed position is rejected:
[VonixGuardian] bad token 'p:1,2': position token must be p:x,y,z
p: sets only the centre. A radius is still required to make it a spatial query.
Hash flags#
Flags are appended as separate tokens and never take a value.
| Flag | Applies to | Effect |
|---|---|---|
#preview |
rollback, restore | Plan and report without touching the world. |
#count |
lookup, rollback, restore | Return counts instead of executing or listing. |
#verbose |
lookup, rollback, restore | Extra detail: raw NBT in lookups, id counts in mutations. |
#silent |
lookup, rollback, restore | Suppress success output. Failures still report. |
#optimize |
purge | Run storage maintenance after the delete. |
/vg lookup r:20 t:1h #count
/vg rollback u:Griefer t:24h r:#global #preview
/vg purge t:90d #optimize
An unknown flag is an error:
[VonixGuardian] bad token '#fast': unknown flag '#fast' — valid flags: #preview,
#count, #verbose, #silent, #optimize
Combining filters#
Filters are ANDed, so each one narrows the result.
/vg lookup u:Alex t:3d a:block r:200
That reads: Alex, in the last 3 days, block actions only, within 200 blocks of me.
/vg rollback u:Griefer t:1h r:#global e:stone,dirt #preview
Griefer's last hour everywhere, except stone and dirt, previewed only.
Common mistakes#
| Symptom | Cause | Fix |
|---|---|---|
r:20 from console fails |
No player position | Use r:#global or r:#world_<key> |
| Rollback hit only a small area | No r: supplied |
Default is r:10; add r:#global or a larger radius |
| Purge deleted the wrong rows | t: means retention in purge |
t:30d deletes older-than-30-days |
| Lookup returns nothing near an explosion | Explosion rows store the blast centre | Widen r:, or roll back from the blast site |
a:block matches both place and break |
Family expands to every direction | Use a:+block or a:-block |
i: filters nothing out |
i:/e: filter the target, not the actor |
Use u: for the actor |
| "exceeded the 100000-row scan limit" | Permission filter needs more rows than the cap | Narrow time, radius, or action |