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. Entries without type are rejected on load.

Player how-to

1. Use shipped aliases such as /sa h (home), /sa pv (vault), /sa hub (lobby) when those entries exist in customcommands.yml.
2. Interactive blocks: staff binds a custom command; players with soapsadmin.interactive.use right-click the block to run it.

Staff / admin how-to

1. Create in-game: /sa customcommand → Create → pick type → finish the builder (registers immediately).
2. Or edit plugins/SoapsAdmin/customcommands.yml → /sa reload customcommands.
3. Disable a built-in: add its name under disabled-commands: or use the GUI → Disabled.
4. Block vanilla /plugins etc. under blocked-server-commands:.

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

Key	Default	Effect
settings.enabled	true	Master toggle for custom commands
settings.register-all-commands	false	Also register every /sa subcommand as top-level (/home, /ban, …)

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

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

Shipped defaults:

Command key	Default enabled	Bypass
plugins	true	soapsadmin.bypass.blockedcommands
pl	true	same
bukkit	true	same
version	false	same

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

Examples

Staff weather / time / gamemode shortcuts

Shipped action macros reuse existing permissions (soapsadmin.weather, soapsadmin.time, soapsadmin.gamemode, soapsadmin.clearinv):

Command	Runs
/sa sun	sa weather clear
/sa rain	sa weather rain
/sa storm / /sa thunder	sa weather thunder
/sa noon	sa time noon
/sa midnight	sa time midnight
/sa gmc / gms / gma / gmsp	matching gamemode
/sa ci	sa clearinv

Leave register-all-commands: false (default) if you share the server with EssentialsX. Set it to true only when you want every /sa name as a top-level command (/sun, /gmc, …) and nothing else claims those labels.

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. For extra names of a built-in, use an entry keyed as that built-in (type: alias or override) with aliases:. Do not create a separate pointer entry.
enabled	true/false
description	Shown in /sa help
permission	Blank = public. Invalid nodes are rejected (command is not loaded / not saved).
showInHelp / showInTab	Discovery flags
commands	Action/replace list
cooldown / cooldown-group	Per-command or shared cooldown key (seconds). In-memory cooldowns and usage counts survive /sa reload customcommands.
delay / warmup	Timing (seconds); soapsadmin.customcommand.bypass.delay / .bypass.warmup apply after warmup too
sound-success / sound-error / sound-no-permission	sound.key [volume] [pitch]. Success sound/message run after the command path succeeds (teleport macros skip FX when teleport cannot start).
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)
override-feedback	When true (default if message: is set), hide the built-in /sa success line so only this custom message shows. Toggle in the customcommand settings GUI. Weather/time/gamemode/clearinv/repair respect it.
message-cooldown / message-denied / message-limit	Optional per-command deny text
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	Cancel an in-progress create
/sa reload customcommands	Reload YAML from disk

Permission: soapsadmin.customcommand to open/list; soapsadmin.customcommand.manage to create, edit, delete, toggle, reload, or disable built-ins.

Sample macros

The shipped customcommands.yml keeps a short live set (godheal, lobby, staff-setup) plus built-in wraps/aliases. Paste more macros under custom-commands: as needed, then /sa reload customcommands.

  sun:
    type: action
    description: Set weather to clear
    permission: soapsadmin.weather
    commands:
      - sa weather clear
    message: "<yellow>Weather set to <white>clear</white>.</yellow>"
    override-feedback: true
    aliases:
      - clear

  day:
    type: action
    description: Set the time to day
    permission: soapsadmin.time
    commands:
      - sa time day
    message: "<yellow>Time set to <white>day</white>.</yellow>"

  gmc:
    type: action
    description: Creative mode
    permission: soapsadmin.gamemode
    commands:
      - sa gamemode creative
    message: "<green>Gamemode set to <yellow>creative</yellow>.</green>"

  fix:
    type: action
    description: Repair all items
    permission: soapsadmin.repair
    commands:
      - sa repair all
    cooldown: 300
    message: "<green>All items repaired.</green>"
    aliases:
      - fixall

  # Message-only (no commands)
  # welcome:
  #   type: message
  #   description: Welcome message
  #   permission: soapsadmin.custom.welcome
  #   message: "<green>Welcome, {player}!</green>"

Same pattern for rain/storm/night/noon and other weather or gamemode shortcuts.

Interactive commands (block binds)

Bind a custom command name to a block. Players with soapsadmin.interactive.use run that custom command by right-clicking the block.

Command	Usage	Permission
/sa interactive bind <customCommand>	Bind while looking at a block (range 5)	soapsadmin.interactive.manage
/sa interactive unbind	Remove bind from targeted block	soapsadmin.interactive.manage
/sa interactive binds	List all binds	soapsadmin.interactive.manage

Alias: /sa ic. The custom command must already exist in customcommands.yml (or be created in-game). Binds are stored in plugins/SoapsAdmin/interactive.yml (runtime file, created on first bind).

If a bind does nothing: check the custom command name, that the player has soapsadmin.interactive.use, and that you are looking at the bound block within 5 blocks.

Defaults: Default customcommands.yml · Config Reference · Intent: Want top-level commands