Custom Commands

Canonical path for features is always /sa <subcommand>.

customcommands.yml extends that with aliases, overrides, disables, and blocked vanilla commands. Custom entries (and their aliases) also register as top-level commands (/heal, /lobby) even when register-all-commands is false. Built-in /sa names only become top-level when that setting is true.

Every custom entry requires a type.

Types

Type	Purpose
action	Run a list of commands (console: prefix for console)
message	Message / title / sounds only (no command list)
alias	Extra /sa names for a built-in (usually just aliases:)
override	Change a built-in: empty commands = wrap (extras then native); non-empty commands = replace

Create in-game

1. /sa customcommand (or GUI) → Create → pick type
2. Action / override replace: opens the Command Builder GUI — add player or console steps, remove steps, Finish or Cancel
3. Chat still works while creating (type a command, or /sa customcommand finish)
4. On finish the command is registered immediately (no /sa reload needed)

Editing customcommands.yml on disk still needs /sa reload customcommands.

Override aliases (e.g. /sa gm → gamemode) run through the same override extras (cooldown, warmup, sounds) as the primary name.

Silent -s / -confirm / -force are preserved when forwarding through overrides (stripped from placeholder args, re-attached on wrap).

Global Settings

settings:
  enabled: true
  register-all-commands: false

When register-all-commands is true, every /sa subcommand also registers as a top-level command (/home, /heal, /ban, etc.).

Disable Built-in Commands

disabled-commands:
  - rocket
  - fakeop

Disabled names apply to /sa <name>, aliases that resolve to them, and custom overrides for those names.

Manage in-game from the Custom Commands GUI → Disabled.

Block Vanilla Commands

blocked-server-commands:
  plugins:
    enabled: true
    message: "<red>Plugin list is restricted."
    bypass-permission: "soapsadmin.bypass.blockedcommands"

Examples

Action

custom-commands:
  godheal:
    type: action
    description: "Fully heal, feed, and clear effects"
    permission: "soapsadmin.custom.godheal"
    commands:
      - "sa heal {player}"
      - "sa feed {player}"
      - "sa cleareffects {player}"
    message: "<green>You have been fully restored!</green>"
    aliases:
      - "gh"

Message

custom-commands:
  discord:
    type: message
    description: "Show Discord link"
    message: "<aqua>Join us at discord.gg/example</aqua>"

Override (wrap)

custom-commands:
  spawn:
    type: override
    description: "Teleport to spawn"
    warmup: 3
    message: "<green>Teleported to spawn!</green>"
    aliases:
      - "spn"

Override (replace)

custom-commands:
  whois:
    type: override
    description: "View player info"
    permission: "soapsadmin.playerinfo"
    commands:
      - "sa playerinfo {args}"

Alias-style override

Built-in shortcuts are usually type: override with empty commands and aliases: only (e.g. home → h, vault → pv).

vault:
  type: override
  description: "Open player vaults"
  permission: "soapsadmin.vault"
  aliases:
    - "pv"
    - "playervault"

vaultadmin:
  type: override
  description: "Manage other players' vaults"
  permission: "soapsadmin.vaultadmin"
  aliases:
    - "pva"

Options

Option	Description
type	Required: action, message, alias, override
enabled	true/false
description	Shown in /sa help
permission	Blank = public (auto-set for sensitive cases)
showInHelp / showInTab	Discovery flags
commands	Action/replace list
cooldown / cooldown-group	Per-command or shared cooldown key (seconds)
delay / warmup	Timing (seconds)
limit	Max uses per player (-1 unlimited)
min-args / max-args / usage	Argument guards + deny message
worlds / worlds-blacklist	Allow-list / deny-list of world names
auto-use	none, join, first-join, respawn, death, kill, sneak, world-change
message / title / actionbar / bossbar	Feedback (title: Title|Subtitle; bossbar: Text|COLOR|seconds)
message-cooldown / message-denied / message-limit	Optional per-command deny text
sound-success / sound-error / sound-no-permission	sound.key [volume] [pitch]
aliases	Extra /sa names

Placeholders

Token	Meaning
{player}	Sender name
{uuid}	Sender UUID
{world}	Current world name
{online}	Online player count
{args}	All args after the command name
{arg0}, {arg1}, …	Positional args
%…%	PlaceholderAPI (when installed)

Flags (-s, -confirm, -force) are stripped from {args} / {argN} and re-attached when wrapping built-in overrides.

Management

Command	Description
/sa customcommand / GUI	List, create (type wizard + command builder), edit, disable built-ins
/sa customcommand finish	Finish action/replace command collection (also Finish in the builder)
/sa customcommand cancelcreate	Abort an in-progress create
/sa reload customcommands	Reload YAML from disk

Permission: soapsadmin.customcommand.manage