Custom Commands

Custom Commands

The custom command system lets you define your own Discord slash commands that respond with text, embeds, and live Minecraft data — all through YAML configuration, no coding required.

---

Enabling Custom Commands

In discord-custom-commands.yml:

custom-commands:
  enabled: true

---

File Structure

Each custom command is a separate YAML file inside plugins/uxmDiscordSync/discord-commands/:

discord-commands/
├── ip.yml
├── profile.yml
├── stats.yml
├── balance.yml
├── store.yml
└── mycommand.yml     # Your custom command

The plugin loads all .yml files in this folder automatically. Add a new file and run /uxmdiscordsync reload to register it.

---

Command File Format

# The Discord slash command name (lowercase, no spaces)
name: "ip"

# The description shown in the Discord command picker
description: "Get the server IP address"

# Whether the response is visible only to the user who ran it
ephemeral: false

# Optional: cooldown in seconds between uses per user
cooldown: 10

# Optional: only allow in specific channels (by ID). Empty = all channels.
allowed-channels: []

# Optional: only allow users with specific Discord roles (by ID). Empty = all roles.
required-roles: []

# The response to send
response:
  type: embed          # "embed" or "text"
  embed:
    title: "Server IP"
    description: "Connect using: **play.yourserver.com**"
    color: "#5865F2"
    fields:
      - name: "Java Edition"
        value: "play.yourserver.com:25565"
        inline: true
      - name: "Bedrock Edition"
        value: "play.yourserver.com:19132"
        inline: true
    footer:
      text: "See you online!"

---

Response Types

Plain Text

response:
  type: text
  content: "The server IP is **play.yourserver.com**"

Embed

response:
  type: embed
  embed:
    title: "Title here"
    description: "Description here. Supports **markdown**."
    color: "#FF0000"
    thumbnail: "https://example.com/image.png"
    image: "https://example.com/banner.png"
    fields:
      - name: "Field Name"
        value: "Field Value"
        inline: true
    footer:
      text: "Footer text"
      icon-url: ""
    author:
      name: "Author Name"
      url: ""
      icon-url: ""

---

Placeholders

Placeholders are replaced in both text and embed content. They pull live data from the Minecraft server.

Server Placeholders

Placeholder	Description	Example
%server_name%	Server name from config	Survival
%online_players%	Current online players	42
%max_players%	Max player slots	100
%server_tps%	Current TPS	19.98
%server_uptime%	Server uptime	3h 12m
%server_ram_used%	RAM in use (MB)	2048
%server_ram_max%	Max RAM (MB)	8192

Discord Placeholders

Placeholder	Description
%total_boosts%	Number of Discord server boosts
%linked_accounts%	Total number of linked accounts
%member_count%	Total Discord member count

Player-Specific Placeholders

These require the user to have a linked account and be online on the Minecraft server. They are available when a command targets a specific player.

Placeholder	Description
%player_name%	Minecraft username
%player_uuid%	Minecraft UUID
%player_level%	XP level
%player_health%	Current health
%player_food_level%	Current hunger
%player_exp%	Experience points
%player_world%	Current world
%player_x%	X coordinate
%player_y%	Y coordinate
%player_z%	Z coordinate

Economy Placeholders (Vault)

Requires Vault and an economy plugin:

Placeholder	Description
%vault_eco_balance%	Player balance (raw number)
%vault_eco_balance_formatted%	Player balance (formatted string)

PlaceholderAPI

If PlaceholderAPI is installed, any %statistic_*% and third-party PAPI placeholders work inside custom command responses.

---

Built-in Example Commands

The plugin ships with these example commands in the discord-commands/ folder. Edit or delete them freely.

ip.yml — Server IP

Returns the server's connection IP.

profile.yml — Player Profile

Shows a player's Minecraft profile with stats pulled from a linked account.

name: "profile"
description: "View a player's profile"
options:
  - name: "player"
    description: "Minecraft username or @Discord user"
    type: string
    required: false

stats.yml — Server Statistics

Shows a live server stats embed using server placeholders.

balance.yml — Player Balance

Shows a player's in-game economy balance. Requires Vault.

store.yml — Server Store

Returns a link or embed for your server's webstore.

---

Command Options (Arguments)

Custom commands can accept user input via slash command options:

options:
  - name: "player"
    description: "The player to look up"
    type: string    # string | integer | boolean | user | channel | role
    required: false

The value of an option can be used in the response:

response:
  type: text
  content: "Looking up player: %option_player%"

---

Access Control

Channel Restriction

allowed-channels:
  - "CHANNEL_ID_1"
  - "CHANNEL_ID_2"

Attempts in other channels get an ephemeral "This command is not available here" error.

Role Requirement

required-roles:
  - "ROLE_ID"

Users without one of the listed roles receive an ephemeral permission error.

Cooldown

cooldown: 30    # Seconds between uses per user

---

Reload

After adding or editing command files:

/uxmdiscordsync reload

New slash commands are registered with Discord. Note: Discord can take up to an hour to propagate newly registered slash commands to all clients globally. For instant testing, set the command as guild-specific in your bot settings.