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.
  • cancel-event — Cancels the event that triggered the command configuration. Only has an effect when the configuration is triggered by an events trigger and the triggering event is cancellable. Non-cancellable events (such as player-join, player-quit, death, break-block-drop-item, throw-egg, break-item) and non-event triggers (interval-ticks, cron, ticks-from-server-start) are ignored with a warning in the console. Because chat is handled asynchronously, player-chat cannot be cancelled by this type. The text after the colon is ignored.
  • connect-server — Transfers each target player to the named BungeeCord/Velocity backend server (e.g. connect-server: lobby). Requires the server to run behind a BungeeCord or Velocity proxy; on Velocity, bungee-plugin-message-channels must be enabled (the default). Also accepts the alias transfer.

Placeholders

Commands may include placeholders that are substituted before the command runs.

  • {player} — Replaced with the player's name, for the per-player command types above (console-for-each-player, for-each-player, op-for-each-player, message).
  • {amount} — Replaced with the amount carried by the triggering event — for example the number of items dropped, crafted, or smelted. Defaults to 1 for the non-event triggers (interval-ticks, cron, ticks-from-server-start) and for events that carry no natural amount.

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, harvest-block, break-block-drop-item, take-lectern-book, interact-entity, interact-block, player-join, player-quit, death, respawn, player-chat, enter-bed, leave-bed, riptide, teleport-to, teleport-from, portal-to, portal-from, drop-item, pickup-item, pickup-arrow, craft-item, enchant-item, consume-item, harvest-item, smelt-item, break-item, damage-item, mend-item, throw-egg, fill-bucket, empty-bucket, kill-entity, kill-entity-drop-item, damage-entity, bucket-entity, shear-entity, tame-entity, manipulate-armorstand. Event names are parsed case-insensitively and separator-insensitively (e.g. break-block, BREAK_BLOCK, and Break Block are all equivalent). The older player-death and player-respawn names are kept as aliases for death and respawn, so existing configurations keep working.

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.

Event Conditions

Event conditions filter whether an in-game event actually triggers the command configuration, based on the context of the event itself — its location, and the entity, item, or block involved. This is separate from and independent of the online-player Player Conditions: event conditions decide whether the event fires the job at all, while player conditions decide which online players the commands then run for. If no event conditions are set, events impose no filtering.

The nine location keys carry an event- prefix to distinguish them from the identically-purposed player-conditions keys, so both sections stay independently editable from the /commandscheduler command surface.

  • event-worlds — The event only triggers if it occurs in one of these worlds.
  • event-environments — The event only triggers if it occurs in one of these environments (normal, nether, the_end).
  • event-biomes — The event only triggers if it occurs in one of these biomes.
  • event-min-x — The event only triggers if its X coordinate is at or above this value.
  • event-max-x — The event only triggers if its X coordinate is at or below this value.
  • event-min-y — The event only triggers if its Y coordinate is at or above this value.
  • event-max-y — The event only triggers if its Y coordinate is at or below this value.
  • event-min-z — The event only triggers if its Z coordinate is at or above this value.
  • event-max-z — The event only triggers if its Z coordinate is at or below this value.
  • entity-in-water — Whether the event's entity is in water. A tri-state, like the player conditions above: true requires it, false requires its absence, and leaving it out imposes no filtering.
  • entity-on-ground — Whether the event's entity is on the ground. Tri-state, as above.
  • entity-names — The event only triggers if the event's entity has one of these names.
  • entity-types — The event only triggers if the event's entity is one of these entity types.
  • entity-categories — The event only triggers if the event's entity is in one of these spawn categories (e.g. monster, animal, water_animal).
  • item-names — The event only triggers if the event's item has one of these display names.
  • item-materials — The event only triggers if the event's item is one of these materials.
  • block-materials — The event only triggers if the event's block is one of these materials.

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.