⚡ SimpleCommands

Create your own commands without writing code — for Paper Minecraft 1.20+ servers

SimpleCommands lets server admins define custom commands in a simple config file (or live in‑game). Each custom command runs one or more real commands — as the player or as the console — with cooldowns, permissions, aliases, placeholders, and optional time windows. Players type /spawn, not /sc spawn: commands are registered directly into the server and behave like native ones.

✨ Key Features

🛠️ Custom Commands Without Code

Define /spawn, /discord, /shop and more in YAML or in‑game
Each command runs a list of real commands in order
No Java, no recompiling — just edit and /sc reload

🎭 Run As Player or Console

PLAYER → runs with the player's own permissions
CONSOLE → runs with full permissions (teleport, give, etc.)
Perfect for letting players trigger admin‑only actions safely

⏱️ Persistent Cooldowns

Per‑command, per‑player cooldowns
Saved to disk — survive player logout and server restarts
Bypass permission for staff (simplecommands.cooldown.bypass)

🔒 Flexible Permissions

EVERYONE → open to all
OP → operators only
PERMISSION → custom node, fully LuckPerms‑compatible

🧩 Placeholders

{player}, {uuid}, {world}, {x}, {y}, {z}
Extendable architecture — add new placeholders without touching existing code

📅 Time‑Limited Commands

Optional available-from / available-until window
Great for events, sales, and limited‑time rewards

🌐 Proxy Support (Velocity / BungeeCord)

Move players between servers with the [server] <name> action tag
Works where plain proxy commands (/server) can't — sent via plugin messaging

🔊 Sound Effects

Play sounds before and after command execution
Uses Bukkit sound names (ENTITY_ENDERMAN_TELEPORT) or namespaced keys (minecraft:entity.player.levelup)
Invalid sound names are safely skipped — no crash, just a warning in the console

⏳ Delay with Action Bar Countdown

Optional delay before command execution (e.g. 3 seconds before teleport)
Action bar countdown — shows remaining time (customizable text with {time} and {total})
Freeze mode — optionally block player movement (walking, jumping) during the delay
Head rotation still allowed, player just can't walk away

📝 Named Arguments

Define /warp spawn, /warp shop, /warp nether with a single command entry
Each argument maps to its own list of commands
/warp (no argument) runs the default commands list (e.g. usage hint)
Tab-completion suggests available argument names automatically
Editable in-game: /sc edit warp addarg mine tp {player} 100 64 200

🛡️ Loop‑Safe Execution

A command that (directly or indirectly) calls itself is detected and aborted
No StackOverflowError, no server crash from a misconfigured command

♻️ Live Reload & Translations

/sc reload applies changes without a restart
Every message lives in lang.yml — fully translatable

📥 Installation

Download .jar from GitHub or Modrinth
Place in plugins/ folder
Restart server
Edit plugins/SimpleCommands/commands.yml (auto-generated)
Run /sc reload

Requirements: Paper (or fork) 1.20.x–1.21.x, Java 21. Optional: LuckPerms.

🎮 Player Commands

/spawn          # or any command you define in commands.yml

Players simply type the command name you created (and its aliases).

🔧 Admin Commands

/sc create <name> <command...>      # Create a new command
/sc delete <name>                   # Delete a command
/sc edit <name> <field> <value...>  # Edit a single field
/sc list                            # List all commands with status
/sc info <name>                     # Show full details of a command
/sc reload                          # Reload config + commands

/simplecommands and /sc are interchangeable.

🔐 Permissions

Permission	Default	Description
`simplecommands.admin`	op	All admin commands
`simplecommands.admin.create`	op	`/sc create`
`simplecommands.admin.delete`	op	`/sc delete`
`simplecommands.admin.edit`	op	`/sc edit`
`simplecommands.admin.list`	op	`/sc list`
`simplecommands.admin.info`	op	`/sc info`
`simplecommands.admin.reload`	op	`/sc reload`
`simplecommands.cooldown.bypass`	op	Ignore custom-command cooldowns

Custom commands using permission-mode: PERMISSION require whatever node you set in their permission field (e.g. simplecommands.cmd.spawn).

Example: LuckPerms

/lp user <player> permission set simplecommands.cmd.spawn true
/lp group admin permission set simplecommands.admin true

⚙️ Configuration

SimpleCommands splits config across focused files:

File	Purpose
`config.yml`	General plugin settings
`lang.yml`	All plugin messages (translatable)
`commands.yml`	Your custom command definitions
`cooldowns.yml`	Saved cooldowns (auto-generated)

Command Definition

commands:
  spawn:
    enabled: true
    description: "Teleport to spawn."
    permission-mode: PERMISSION
    permission: simplecommands.cmd.spawn
    aliases:
      - lobby
      - hub
    cooldown: 5
    execute-as: CONSOLE
    commands:
      - "tp {player} 0 78 0"
    message: "&aTeleported to spawn."

Field Reference

Field	Description
`enabled`	`true`/`false`. Disabled commands stay registered but refuse to run
`description`	Shown in `/sc list` and `/sc info`
`permission-mode`	`EVERYONE`, `OP`, or `PERMISSION`
`permission`	Node checked when mode is `PERMISSION`
`aliases`	Alternate names for the command
`cooldown`	Seconds between uses (`0` = none). Saved across restarts
`execute-as`	`PLAYER` (player's rights) or `CONSOLE` (full rights)
`commands`	List of commands run in order (no leading `/`)
`message`	Optional message after execution
`available-from` / `available-until`	Optional `yyyy-MM-dd HH:mm` time window
`sound-before`	Sound played before execution (Bukkit name or namespaced key)
`sound-after`	Sound played after execution completes
`delay`	Seconds to wait before running commands (`0` = instant)
`delay-message`	Action bar text during countdown (`{time}` = remaining, `{total}` = total)
`delay-freeze`	`true`/`false`. Block movement during delay
`args`	Named arguments map — each key is an arg name, value is a list of commands

Placeholders

Placeholder	Meaning
`{player}`	Player's name
`{uuid}`	Player's UUID
`{world}`	World name
`{x}` `{y}` `{z}`	Block coordinates

Color Codes

&a &c ...        # classic color codes
&#RRGGBB         # hex colors (e.g. &#ff8800)

See full commands.yml and lang.yml for all options.

📊 Use Cases

Message-Only Command (Discord link)

commands:
  discord:
    enabled: true
    description: "Show the Discord invite link."
    permission-mode: EVERYONE
    execute-as: PLAYER
    commands: []
    message: "&bOur Discord: &fhttps://discord.gg/yourserver"

Multi-Command Starter Kit (once per day)

commands:
  starterkit:
    enabled: true
    permission-mode: PERMISSION
    permission: simplecommands.cmd.starterkit
    cooldown: 86400
    execute-as: CONSOLE
    commands:
      - "give {player} bread 16"
      - "give {player} iron_sword 1"
    message: "&aYou received the starter kit! Come back tomorrow."

Proxy Server Switch (Velocity / BungeeCord)

Proxy commands like /server cannot be run as a normal command entry — they run on the backend, not the proxy. Use the [server] (or [connect]) action tag instead:

commands:
  lobby:
    enabled: true
    permission-mode: EVERYONE
    execute-as: PLAYER
    aliases: [ hub ]
    commands:
      - "[server] lobby"
    message: "&bSending you to the lobby..."

Proxy-side requirements:

Velocity: velocity.toml → bungee-plugin-message-channel = true (default)
Paper backend: spigot.yml → settings.bungeecord: true

Time-Limited Event Command

commands:
  event:
    enabled: true
    permission-mode: EVERYONE
    execute-as: CONSOLE
    available-from: "2026-12-24 00:00"
    available-until: "2026-12-26 23:59"
    commands:
      - "give {player} firework_rocket 8"
    message: "&aHappy holidays!"

Teleport with Delay, Freeze & Sounds

commands:
  spawn:
    enabled: true
    permission-mode: EVERYONE
    execute-as: CONSOLE
    sound-before: BLOCK_NOTE_BLOCK_PLING
    sound-after: ENTITY_ENDERMAN_TELEPORT
    delay: 3
    delay-message: "&eTeleporting in {time}s..."
    delay-freeze: true
    commands:
      - "tp {player} 0 78 0"
    message: "&aTeleported to spawn."

Player hears a pling, sees "Teleporting in 3s..." on the action bar, can't move, and after 3 seconds gets teleported with the enderman sound.

Warp with Named Arguments

commands:
  warp:
    enabled: true
    permission-mode: PERMISSION
    permission: simplecommands.cmd.warp
    cooldown: 3
    execute-as: CONSOLE
    commands:
      - "msg {player} Usage: /warp <spawn|shop|nether>"
    message: ""
    args:
      spawn:
        - "tp {player} 0 78 0"
      shop:
        - "tp {player} -200 78 512"
      nether:
        - "tp {player} 0 78 0 world_nether"

/warp spawn → teleports to spawn
/warp shop → teleports to the shop
/warp → shows usage hint
Tab-completion suggests: spawn, shop, nether

🐛 Troubleshooting

Plugin won't load

Check:

Are you using Paper 1.20+? (/version)
Is the JAR in the plugins/ folder?
Do you have Java 21? (java -version)

Custom command not found

Check:

Did the plugin load? (Check console for "[SimpleCommands]")
Is the command enabled: true?
Run /sc reload after editing commands.yml

"You don't have permission"

Check:

The command's permission-mode and permission node
Grant the node (e.g. via LuckPerms)
For OP mode, the player must be an operator

Command runs but does nothing

Check:

execute-as — use CONSOLE for actions players can't run themselves
The commands in the commands: list have no leading /
Placeholders are spelled correctly ({player}, not %player%)

`/server` (proxy) says "unknown command"

Proxy commands can't run on the backend. Use the action tag instead of a plain command:

Write "[server] lobby" (not "server lobby") in the commands: list
Velocity: velocity.toml → bungee-plugin-message-channel = true
Paper backend: spigot.yml → settings.bungeecord: true

Note: cooldowns are stored per backend server, not shared across the whole network.

📈 Performance

SimpleCommands is lightweight and built for clean performance:

✅ Commands registered directly into the server's CommandMap
✅ Cooldowns saved asynchronously (no main-thread file I/O on quit)
✅ Recursive commands detected and aborted (no infinite loops / crashes)
✅ No external dependencies (LuckPerms optional, soft-depend)
✅ Single JAR runs across 1.20.x–1.21.x
✅ Main-thread safe execution

🔁 Version History

Future Roadmap

[ ] PlaceholderAPI integration
[ ] In-game GUI editor for commands
[ ] Periodic cooldown auto-save
[ ] Per-command usage statistics

1.0.3

Named arguments: define /warp spawn, /warp shop etc. in a single command entry via args map.
Tab-completion for argument names.
In-game editing: /sc edit <cmd> addarg <name> <command> and removearg <name>.
Unknown argument shows available options to the player.

1.0.2

Sound effects: sound-before and sound-after with safe handling of invalid sound names.
Delay system: action bar countdown with {time} placeholder, optional movement freeze (delay-freeze).
Commands now forcefully override existing commands (fixes /spawn conflict with other plugins).

1.0.1

Proxy server switching via [server] / [connect] action tags (Velocity/BungeeCord).
Infinite-loop protection: recursive commands detected and aborted safely.
Persistent cooldowns: saved to disk, survive player logout and server restarts.

1.0.0

Initial release: custom commands, player/console execution, persistent cooldowns, permissions (EVERYONE/OP/PERMISSION), aliases, placeholders, time windows, live reload, translatable messages.

🔗 Links

GitHub: https://github.com/Dominos111G/SimpleCommands
Modrinth: https://modrinth.com/plugin/simplecmds
Issues: https://github.com/Dominos111G/SimpleCommands/issues

SimpleCommands

Compatibility

Minecraft: Java Edition

Platforms

Links

Tags

Creators

Details

⚡ SimpleCommands

✨ Key Features

🛠️ Custom Commands Without Code

🎭 Run As Player or Console

⏱️ Persistent Cooldowns

🔒 Flexible Permissions

🧩 Placeholders

📅 Time‑Limited Commands

🌐 Proxy Support (Velocity / BungeeCord)

🔊 Sound Effects

⏳ Delay with Action Bar Countdown

📝 Named Arguments

🛡️ Loop‑Safe Execution

♻️ Live Reload & Translations

📥 Installation

🎮 Player Commands

🔧 Admin Commands

🔐 Permissions

Example: LuckPerms

⚙️ Configuration

Command Definition

Field Reference

Placeholders

Color Codes

📊 Use Cases

Message-Only Command (Discord link)

Multi-Command Starter Kit (once per day)

Proxy Server Switch (Velocity / BungeeCord)

Time-Limited Event Command

Teleport with Delay, Freeze & Sounds

Warp with Named Arguments

🐛 Troubleshooting

Plugin won't load

Custom command not found

"You don't have permission"

Command runs but does nothing

/server (proxy) says "unknown command"

📈 Performance

🔁 Version History

Future Roadmap

🔗 Links

`/server` (proxy) says "unknown command"