Command Scheduler Documentation

Command Scheduler

Schedule commands to run at specific points — on an interval, on a cron expression down to the tick, or a set time after server start. Useful for announcements, recurring payouts, restarts, and any other server chore you'd rather not do by hand.

Download Command Scheduler on SpigotMC

Installation

  1. Add the Command Scheduler jar into your plugins folder.
  2. Restart your server.
  3. Edit commands.yml to your liking.
  4. Type /commandscheduler reload.

Commands

  • /commandscheduler help — Show the help message.
  • /commandscheduler reload — Reload the plugin.
  • /commandscheduler view <commandId> — View details of a scheduled command.
  • /commandscheduler execute <commandId> — Execute a specific configured command immediately.
  • /commandscheduler time — Check the current server time. Useful for configuring a cron.
  • /commandscheduler list — List all configured command ids.
  • /commandscheduler create <id> — Create a new empty command configuration in-game.
  • /commandscheduler delete <id> — Delete a command configuration in-game.
  • /commandscheduler rename <oldId> <newId> — Rename a command configuration in-game.
  • /commandscheduler set <id> <setting> [value] — Set or clear a scalar setting on a command configuration. Omitting the value clears (unsets) the setting.
  • /commandscheduler command <id> add|remove|list|clear — Edit the commands list of a command configuration.
  • /commandscheduler list-setting <id> <setting> add|remove|clear [value] — Edit a list-type setting (events, players, not-players, worlds, environments, biomes, gamemodes, has-permissions, missing-permissions).

Every edit command persists the change to commands.yml on disk and immediately reloads the running configuration.

Permissions

  • commandscheduler.reload — Allows the use of the reload command.
  • commandscheduler.view — Allows the use of the view command.
  • commandscheduler.execute — Allows the use of the execute command.
  • commandscheduler.time — Allows the use of the time command.
  • commandscheduler.list — Allows the use of the list command.
  • commandscheduler.edit — Allows the use of the create, delete, rename, set, command, and list-setting commands.

Scheduled Commands

Each top-level key in commands.yml is one scheduled command configuration.

# This example will say hello to all players every 30 seconds.
hello-players:
  commands:
    - 'message: Hello, {player}!'
  triggers:
    interval-ticks: 600

# This example will broadcast random help messages every 10 minutes.
random-help-message:
  commands:
    - 'broadcast: Remember to read the rules!'
    - 'broadcast: Need help? Ask a staff member!'
    - 'broadcast: Check out our website for more info!'
  only-run-one-random-command: true
  triggers:
    interval-ticks: 12000

# This example will give all players $100 every 5 minutes.
five-minute-cash:
  commands:
    - 'console-for-each-player: eco give {player} 100'
  triggers:
    cron: 0 */5 * * * * * # second, minute, hour, day of month, month, day of week, year

# This example will broadcast a message one minute after the server starts.
one-minute-message:
  commands:
    - 'broadcast: The server has been running for one minute!'
  triggers:
    ticks-from-server-start: 1200

# This example will make all players run /spawn every hour on the hour.
hourly-spawn:
  commands:
    - 'for-each-player: spawn'
  triggers:
    cron: 0 0 * * * * * # second, minute, hour, day of month, month, day of week, year

# This example will stop the server at midnight every day.
midnight-shutdown:
  commands:
    - 'console: stop'
  triggers:
    cron: 0 0 0 * * * * # second, minute, hour, day of month, month, day of week, year

# This example broadcasts a message whenever a player breaks a block.
break-announcer:
  commands:
    - 'broadcast: A block was just broken!'
  triggers:
    events:
      - break-block

Settings

  • commands — Commands to run when the command configuration is executed. Syntax: <commandType>:<command>. See Command Types.
  • triggers — Control when the command configuration is executed. See Triggers.
  • execute-conditions — Conditions checked when the command configuration is triggered. If the conditions are not met, the commands will not execute.
  • player-conditions — Conditions checked for individual players when commands are executed. If the conditions are not met for a player, commands will not run for that player when using console-for-each-player and for-each-player command types.
  • only-run-one-random-command — Only runs one random command instead of all commands when executed.
  • run-chance — The percent chance (0–100) that the command configuration runs each time it is triggered. If not present, it always runs.

Command Types

  • console — Executes the command as the console.
  • console-for-each-player — Executes the command as the console for each online player, replacing {player} with the player's name.
  • for-each-player — Executes the command as each online player, replacing {player} with the player's name.
  • op-for-each-player — Executes the command as each online player as if they were op, replacing {player} with the player's name. The op status is granted only for that command and removed straight after.
  • broadcast — Broadcasts a message to all online players.
  • message — Sends a message to all online players, replacing {player} with the player's name.

Triggers

  • interval-ticks — The number of ticks between each execution of the command configuration.
  • cron — A cron expression to control specific points that the command configuration will execute down to the tick. Syntax: <second> <minute> <hour> <dayOfMonth> <month> <dayOfWeek> <year>. Each field supports *, a single value, a 1-5 range, a */5 step, and a 1,3,5 list. Note that dayOfWeek runs 1 (Monday) to 7 (Sunday), and that dayOfMonth and dayOfWeek must both match, unlike standard cron where either one matching is enough.
  • ticks-from-server-start — The number of ticks from server start when the command should execute. Can have multiple values, comma separated.
  • events — A list of in-game events that trigger the command configuration. Supported events: place-block, break-block, interact-entity, interact-block, player-join, player-quit, player-death, player-respawn, player-chat, drop-item, pickup-item, kill-entity. Event names are parsed case-insensitively and separator-insensitively (e.g. break-block, BREAK_BLOCK, and Break Block are all equivalent).

Execute Conditions

  • min-players-online — Commands will only execute if this many players are online.
  • max-players-online — Commands will only execute if no more than this many players are online.
  • min-players-who-meet-conditions — Commands will only execute if this many players meet the player conditions.
  • max-players-who-meet-conditions — Commands will only execute if fewer than this many players meet the player conditions.
  • all-players-meet-conditions — Commands will only execute if all players meet the player conditions.
  • required-players — Commands will only execute if all of these players are online. Provided as a list of names.
  • blocking-players — Commands will not execute if any of these players are online. Provided as a list of names.
  • execute-on — Which change in a player's condition state triggers the commands. One of conditions-pass (default), conditions-fail, conditions-change, conditions-change-rising-edge, or conditions-change-falling-edge. Only applies when at least one player condition is set.

Player Conditions

Location

  • worlds — Commands will only execute if the player is in one of these worlds.
  • environments — Commands will only execute if the player is in one of these environments.
  • biomes — Commands will only execute if the player is in one of these biomes.
  • min-x — Commands will only execute if the player is above this X value.
  • min-y — Commands will only execute if the player is above this Y value.
  • min-z — Commands will only execute if the player is above this Z value.
  • max-x — Commands will only execute if the player is below this X value.
  • max-y — Commands will only execute if the player is below this Y value.
  • max-z — Commands will only execute if the player is below this Z value.

Player

  • players — Commands will only execute for players whose name is in this list.
  • not-players — Commands will not execute for players whose name is in this list.
  • gamemodes — Commands will only execute if the player is in one of these game modes.
  • has-permissions — Commands will only execute if the player has all of these permissions.
  • missing-permissions — Commands will not execute if the player has any of these permissions.

State

Each of these is a tri-state. Set it to true to require the state, false to require its absence, or leave it out entirely to execute regardless.

  • in-water — Whether the player is in water.
  • sneaking — Whether the player is sneaking.
  • blocking — Whether the player is blocking.
  • climbing — Whether the player is climbing.
  • gliding — Whether the player is gliding.
  • glowing — Whether the player is glowing.
  • riptiding — Whether the player is riptiding.
  • in-vehicle — Whether the player is in a vehicle.
  • sprinting — Whether the player is sprinting.
  • flying — Whether the player is flying.
  • on-fire — Whether the player is on fire.
  • frozen — Whether the player is frozen.

Metrics

Command Scheduler reports anonymous usage statistics to bStats. To opt out, set enabled: false in plugins/bStats/config.yml, which turns off metrics for every plugin on the server.