Permissions#

Every /vg subcommand is gated by a permission node. Nodes are checked in a fixed order: LuckPerms first if available, then a vanilla op-level fallback.

Resolution order#

For a player source, PermissionResolver checks in this order and stops at the first definitive answer:

1. LuckPerms, when permissions.useLuckPerms is true and the bridge is available. A true grants, a false denies.
2. Op level, when LP is absent, disabled, or returns UNDEFINED. Grant iff opLevel >= requiredLevel, where requiredLevel is the per-node default or a permissions.perNodeOpLevels override.

The console is always authorised — a non-player source never fails a command gate.

LuckPerms is a soft dependency#

The bridge is pure reflection; VonixGuardian never imports net.luckperms.*. It compiles, ships, and runs with no LuckPerms present. Detection happens once per JVM and is cached:

Nothing needs configuring to switch between modes. Install LuckPerms and the next check uses it; remove it and the fallback resumes.

Node reference#

Canonical nodes live under vonixguardian.<action>. The default op level applies only when the fallback path is in use — with LuckPerms, the node's value decides.

Per-category child nodes#

For lookup, rollback, and restore, category-scoped child nodes allow a narrower grant than the whole family. They are checked per row when results are filtered.

Fall-open by design. If a family has no child node for a category, the family node is used. There is no way to be scoped out of a family that has no subdivision — holding vonixguardian.rollback grants rollback for messages and sessions too, where those types are reversible at all.

A player with vonixguardian.lookup but not vonixguardian.lookup.chat sees block and container rows in a /vg lookup and has chat rows silently filtered out of the result. #count respects the same filter, so counts match what is visible.

Reserved nodes#

These exist in the registry but do not gate a subcommand:

Do not build a permission scheme around them; they are declared for forward compatibility and are not enforced on a command path.

Setting up LuckPerms#

Two roles cover most servers: moderator investigates, admin mutates.

# Moderator — read-only investigation
/lp group moderator permission set vonixguardian.base true
/lp group moderator permission set vonixguardian.inspect true
/lp group moderator permission set vonixguardian.lookup true
/lp group moderator permission set vonixguardian.near true
/lp group moderator permission set vonixguardian.status true
/lp group moderator permission set vonixguardian.command.teleport true

# Admin — inherits moderator, gains mutation and maintenance
/lp group admin parent add moderator
/lp group admin permission set vonixguardian.rollback true
/lp group admin permission set vonixguardian.restore true
/lp group admin permission set vonixguardian.undo true
/lp group admin permission set vonixguardian.purge true
/lp group admin permission set vonixguardian.reload true
/lp group admin permission set vonixguardian.consumer true
/lp group admin permission set vonixguardian.command.give true

Notes that save support tickets:

• Grant vonixguardian.base to anyone who holds another node. It gates the root literal; without it some clients hide /vg from tab-completion entirely.
• Three nodes carry the .command. infix — command.config, command.teleport, command.give. Copy them exactly from the table; a plausible-looking vonixguardian.teleport grants nothing.
• purge at op 4 is deliberate. It is destructive and irreversible.
• consumer and reload are operational, not investigative. Pausing the writer during an investigation silently loses events; keep them with admins.
• Wildcards work: vonixguardian.* grants every node in the table.

Op-level fallback#

Without LuckPerms there is no per-command granularity by default — any player at permissions.defaultOpLevel or above passes every node check, including purge.

"permissions": {
  "useLuckPerms": true,
  "defaultOpLevel": 3,
  "perNodeOpLevels": {}
}

defaultOpLevel must be 0–4. 3 matches the vanilla /op tier, so a normally opped administrator can use everything.

Per-node overrides#

perNodeOpLevels restores per-command control without LuckPerms. This is the supported way to let a builder inspect without letting them purge:

"permissions": {
  "useLuckPerms": true,
  "defaultOpLevel": 4,
  "perNodeOpLevels": {
    "vonixguardian.base": 0,
    "vonixguardian.inspect": 0,
    "vonixguardian.lookup": 0,
    "vonixguardian.near": 0,
    "vonixguardian.status": 2,
    "vonixguardian.rollback": 3,
    "vonixguardian.restore": 3,
    "vonixguardian.purge": 4
  }
}

With that map, a level-0 player can inspect and look up, a level-3 admin can roll back, and purge stays at 4.

Rules:

• Keys are canonical node strings from the table. An unknown key logs a WARN and is ignored at runtime.
• Values must be 0–4. Anything else is a hard config validation error.
• The map only affects the fallback path. When LuckPerms answers, the map is not consulted.
• permissions is restart-only — /vg reload detects the change and reports Requires restart.

If a node is absent from the map, its own default op level applies. A malformed override does not silently degrade to the coarse default; it is rejected at load.

Choosing a scheme#