Commands#

Viscord exposes three command surfaces: Minecraft commands registered through Brigadier, native Discord application commands registered per guild, and legacy Discord text triggers kept for compatibility. Permission levels are vanilla Minecraft op levels — 0 is any player including a non-op, 4 is full op.

In-game: /discord#

The whole /discord tree is registered with hasPermission(0), so every player can use it.

messages and events are pure toggles: each invocation flips the stored preference and prints the new state — Cross-server messages disabled! or Cross-server messages enabled!. There is no on/off argument, so running the same command twice returns you to where you started. servermessages is the exception: it has explicit enable and disable children, plus a bare form that only reports.

If discord.invite_url is empty, /discord prints Discord invite URL is not configured. rather than an empty link.

Preferences are stored per UUID in config/viscord/viscord-preferences.json and survive restarts. A player who has never run these commands sees everything, because all three stored flags default to false.

In-game: /viscord#

The /viscord root node itself carries no permission predicate. Gating is per-branch: reload and status each declare hasPermission(4), while the discord sub-tree is player-level.

/viscord status prints a three-line block: Status: Running or Status: Stopped, Platform: <value>, and Enabled: Yes or Enabled: No. It reports the configured platform string, not the live connection state per platform — a Platform: both server with only Discord connected still shows both.

/viscord reload announces Reloading Viscord configuration..., then does the work off-thread. The final message is one of Viscord reloaded successfully!, Viscord is disabled in config., or Failed to reload: <message>. Because the reload rebuilds the platform objects, it also re-sends the startup embed and re-registers native commands.

/viscord discord link fails early in three distinct ways, each with its own message:

• Account linking is disabled. — account_linking.enabled is false.
• Already linked to <name> <@id> — your UUID is already bound.
• Discord bot is not connected. Please contact an administrator. — the platform is not running, so no code can be redeemed anyway.

A successful call prints Your link code is: 123456, the instruction to run /link 123456 in Discord, and the expiry in minutes.

/viscord discord unlink reports Your Discord account has been unlinked. or You don't have a linked Discord account. It removes the binding for the executing player only.

You will notice that /viscord discord invite appears in the help text. It is not a registered node — the invite path lives on /discord. Use /discord.

In-game: /vonix (deprecated)#

The old alias still exists so muscle memory does not fail, but it does nothing except tell you to move on. The entire root requires op level 4.

Neither branch reloads anything or runs a subcommand. A non-op running /vonix gets the standard unknown-command behaviour, because the permission check fails before any executor runs.

Discord application commands#

Viscord registers five native commands, scoped to the guild that owns the configured discord.channel_id. Registration happens on bot connect: existing Viscord-owned commands are updated in place, and a name already owned by a different Discord application is skipped with a log warning rather than overwritten.

Constraints that apply to all five#

• Channel restriction. Every command checks that the invoking channel is in the configured discord.channel_id list. Anywhere else the reply is Viscord commands are only available in the configured server channel.
• Readiness. If the Minecraft server handle is missing or the integration is not running, the reply is Minecraft server integration is not ready.
• DMs are disabled. Commands are registered with setEnabledInDms(false).
• Ephemeral replies. Immediate responses are flagged ephemeral, so failures and /help output are only visible to the caller.

/link code#

The argument is length-constrained to exactly 6 by the command definition, and the handler additionally rejects anything that is not ^\d{6}$ with a single generic message: Invalid link code. Use the six-digit code from /viscord discord link. There is no distinction between "too short", "wrong digits", and "no such code" in the format stage — that is deliberate, so the reply cannot be used to narrow a search.

/link consumes the per-user and global link buckets before doing any lookup. A rate-limited attempt returns Too many link attempts. Please wait before trying again. on the native path.

/list#

Returns the server name, players <online>/<max>, then one line per player. With nobody online it says No players are currently online. The response is deferred and completed from the server thread, so a slow tick does not expire the interaction. Rate limited by the list_* buckets.

/home name#

This is the only command that can cause a Minecraft action, and its surface is deliberately narrow:

• The Discord user must be linked. Otherwise: Link your Minecraft account first with /link code.
• The home name must match [A-Za-z0-9_-]{1,32}. Anything else returns Invalid home name. Use 1–32 letters, numbers, _, or -.
• The linked Minecraft player must be online. Otherwise: Your linked Minecraft player is not currently online.
• Dispatch happens on the Minecraft server thread against a command source built from the player entity, at permission level 0, with output suppressed. The command root is the literal string home and the validated name is appended. No other command can be reached, and Discord never becomes a console bridge.
• Rate limited by the home_* buckets.

On success the reply names the player and the home. On failure you get The safe home action failed; no arbitrary command was executed.

/help#

Lists /link code, /list, /home name, and /status with one-line descriptions. It does not list the in-game commands; run /viscord discord help in Minecraft for those.

/status#

Requires the Discord Administrator permission on the invoking member, checked against the guild. Non-administrators get Administrator permission is required for /status. The command is also registered as administrator-only by default, so most members will not see it in the picker at all. Output reports integration state, Discord connection state, and the live player count.

Legacy Discord text triggers#

Two ordinary-message triggers still work. They are read from the same channel list as the native commands and are checked before the bot and webhook filters, so they function even with filters.ignore_bots enabled.

!list is matched case-insensitively against the whole trimmed message. /link is matched by prefix — any message starting with /link is treated as a link attempt.

When to prefer the native form#

Use /link code, /list, and /home name unless you have a specific reason not to:

• The native commands reply ephemerally. A wrong code does not broadcast your attempt to everyone watching the channel, and does not leak that a code was tried at all.
• The native /link reports rate limiting to the caller. The text trigger is silent on a rate limit — it returns without replying, so a throttled user sees nothing and assumes the bot is broken.
• Native /home exists only as a slash command. There is no text equivalent.

The text triggers remain the right choice when a member's client cannot show slash commands, or when a relay bot posts messages that a human would otherwise type. Note that a message beginning /link from any allowed author is treated as an attempt, including messages that merely quote the syntax.

Command surface summary#