runTaskTimer

Schedules a repeating task to run at fixed intervals on the main server thread.

This extension function provides a simplified way to schedule repeating tasks without manually creating BukkitRunnable instances. Both the initial delay and repeat period are specified in seconds and automatically converted to Minecraft ticks (20 ticks = 1 second).

The task executes repeatedly at the specified interval until cancelled or the plugin is disabled. All code within the task lambda runs synchronously on the main server thread, making it safe to interact with the Bukkit API and modify game state.

Usage Example

class MyPlugin : JavaPlugin() {
    override fun onEnable() {
        // Announce server time every 10 seconds, starting after 5 seconds
        runTaskTimer(delay = 5.0, period = 10.0) {
            server.broadcastMessage("Current time: ${System.currentTimeMillis()}")
        }

        // Heal all players every 30 seconds with cancellation
        val healTask = runTaskTimer(delay = 0.0, period = 30.0) {
            server.onlinePlayers.forEach { player ->
                player.health = player.maxHealth
            }
        }

        // Cancel after certain condition
        runTaskTimer(delay = 1.0, period = 1.0) {
            if (someCondition) {
                cancel() // Stop the repeating task
            }
        }

        // Countdown timer
        var counter = 10
        runTaskTimer(delay = 0.0, period = 1.0) {
            server.broadcastMessage("Time remaining: $counter")
            counter--
            if (counter <= 0) {
                server.broadcastMessage("Time's up!")
                cancel()
            }
        }
    }
}

Tick Conversion

Both delay and period parameters are in seconds and converted to ticks:

• Ticks = seconds × 20

• Example: delay = 2.0, period = 1.0 → waits 40 ticks, then runs every 20 ticks

• Example: delay = 0.0, period = 0.5 → starts immediately, runs every 10 ticks

Execution Timeline

1. Initial delay period elapses (delay × 20 ticks)

2. Task executes for the first time

3. Period interval elapses (period × 20 ticks)

4. Task executes again

5. Repeat steps 3-4 until cancelled or plugin disabled

Important Notes

• The task runs synchronously on the main server thread

• First execution occurs after the delay, then repeats every period

• Setting delay to 0.0 causes immediate first execution

• Minimum practical period is 0.05 seconds (1 tick)

• Fractional ticks are truncated (e.g., 1.51 seconds = 30 ticks)

• The task has access to BukkitRunnable methods like cancel() and isCancelled()

• Tasks are automatically cancelled when the plugin is disabled

• For one-time delayed execution, use runTaskLater() instead

Thread Safety

Since this runs on the main thread, it's safe to:

• Modify blocks, entities, and inventory

• Send messages to players

• Interact with any Bukkit/Paper API

• Schedule additional tasks

For asynchronous repeating operations, consider using Bukkit's async timer methods instead.

Performance Considerations

• Keep task execution time minimal to avoid server lag

• Avoid heavy computations in repeating tasks

• Use appropriate period intervals (very short periods may impact performance)

• Always cancel tasks when no longer needed to free resources

Parameters

See also