NOTE: I generated ONLY this description with AI and I'm open for your ideas!

⚡ 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

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:

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

Placeholders

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

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