Skip to content

Dominos111G/SimpleCommands

BranchesTags

Repository files navigation

⚡ 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

  1. Download .jar from GitHub or Modrinth
  2. Place in plugins/ folder
  3. Restart server
  4. Edit plugins/SimpleCommands/commands.yml (auto-generated)
  5. 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:

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

Custom command not found

Check:

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

"You don't have permission"

Check:

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

Command runs but does nothing

Check:

  1. execute-as — use CONSOLE for actions players can't run themselves
  2. The commands in the commands: list have no leading /
  3. 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:

  1. Write "[server] lobby" (not "server lobby") in the commands: list
  2. Velocity: velocity.toml → bungee-plugin-message-channel = true
  3. 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

📝 License

MIT License - Free to modify and distribute

📖 Documentation

💬 Support

Found a bug or want a feature? Open an issue!

Version: 1.0.3
Minecraft: 1.20+
Made with ❤️ for Minecraft Players

About

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.

modrinth.com/plugin/simplecmds

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages