Skip to main content

Scheduler

Version History

Build VersionChange DateChange TypeDescription
6760422025-06-21stableCurrent version

Overview

The scheduler module provides a comprehensive coroutine-based task scheduling system for Don't Starve Together. It manages thread execution, task timing, and periodic operations through two main schedulers: a regular scheduler for game-time operations and a static scheduler for real-time operations.

Usage Example

-- Start a simple thread
local task = StartThread(function()
print("Thread started")
Sleep(5) -- Sleep for 5 seconds
print("Thread resumed after 5 seconds")
end, "example_thread")

-- Execute a function after delay
scheduler:ExecuteInTime(2.0, function()
print("Executed after 2 seconds")
end, "delayed_execution")

-- Execute periodic function
local periodic = scheduler:ExecutePeriodic(1.0, function()
print("Executed every second")
end, 5, nil, "periodic_task") -- Run 5 times

Global Functions

StartThread(fn, id, param)

Status: stable

Description: Creates and starts a new thread in the main scheduler.

Parameters:

  • fn (function): The function to execute in the thread
  • id (string): Optional identifier for the thread
  • param (any): Optional parameter passed to the function

Returns:

  • (Task): The created task object

Example:

local task = StartThread(function(param)
print("Thread parameter:", param)
Sleep(1)
print("Thread completed")
end, "my_thread", "hello")

StartStaticThread(fn, id, param)

Status: stable

Description: Creates and starts a new thread in the static scheduler (real-time based).

Parameters:

  • fn (function): The function to execute in the thread
  • id (string): Optional identifier for the thread
  • param (any): Optional parameter passed to the function

Returns:

  • (Task): The created task object

Example:

local static_task = StartStaticThread(function()
print("Static thread running")
Sleep(2)
print("Static thread finished")
end, "static_thread")

Sleep(time)

Status: stable

Description: Suspends the current thread for the specified time duration.

Parameters:

  • time (number): Time to sleep in seconds

Example:

StartThread(function()
print("Before sleep")
Sleep(3.5) -- Sleep for 3.5 seconds
print("After sleep")
end, "sleep_example")

Hibernate()

Status: stable

Description: Puts the current thread into hibernation state until explicitly woken.

Example:

local hibernating_task = StartThread(function()
print("Going to hibernate")
Hibernate()
print("Woken from hibernation")
end, "hibernate_example")

-- Wake the task later
WakeTask(hibernating_task)

Wake()

Status: stable

Description: Wakes the current hibernating thread and moves it to running state.

Example:

StartThread(function()
Hibernate()
Wake() -- Wake self
print("Self-woken thread")
end, "self_wake")

WakeTask(task)

Status: stable

Description: Wakes a specific hibernating task.

Parameters:

  • task (Task): The task to wake up

Example:

local sleeping_task = StartThread(function()
print("Going to hibernate")
Hibernate()
print("I've been woken up!")
end, "sleeping_task")

-- Wake it after 2 seconds
scheduler:ExecuteInTime(2.0, function()
WakeTask(sleeping_task)
end, "wake_caller")

KillThread(task)

Status: stable

Description: Forcibly terminates a running task.

Parameters:

  • task (Task): The task to terminate

Example:

local long_task = StartThread(function()
while true do
print("Running...")
Sleep(1)
end
end, "long_running")

-- Kill it after 5 seconds
scheduler:ExecuteInTime(5.0, function()
KillThread(long_task)
print("Long task terminated")
end, "killer")

KillThreadsWithID(id)

Status: stable

Description: Terminates all threads with the specified ID.

Parameters:

  • id (string): The ID of threads to terminate

Example:

-- Start multiple threads with same ID
for i = 1, 3 do
StartThread(function()
while true do
print("Worker", i)
Sleep(1)
end
end, "worker_threads")
end

-- Kill all worker threads
KillThreadsWithID("worker_threads")

Yield()

Status: stable

Description: Yields execution to allow other threads to run, resuming on the next tick.

Example:

StartThread(function()
for i = 1, 5 do
print("Iteration", i)
Yield() -- Let other threads run
end
end, "yielding_thread")

Global Objects

scheduler

Type: Scheduler

Status: stable

Description: The main game-time scheduler instance.

staticScheduler

Type: Scheduler

Status: stable

Description: The static real-time scheduler instance.

Classes

Task

Status: stable

Description: Represents a single threaded task with coroutine execution.

Properties

  • guid (number): Unique identifier for the task
  • id (string): User-defined task identifier
  • fn (function): The function being executed
  • co (coroutine): The coroutine object
  • param (any): Parameter passed to the function
  • list (table): Current list containing this task

Methods

task:SetList(list)

Description: Moves the task to a different execution list.

Parameters:

  • list (table): The target list or nil to remove from current list

Periodic

Status: stable

Description: Represents a periodic task that executes at regular intervals.

Properties

  • fn (function): Function to execute periodically
  • period (number): Time interval between executions
  • limit (number): Maximum number of executions (nil for infinite)
  • nexttick (number): Next tick when the function will execute
  • onfinish (function): Callback when periodic task completes

Methods

periodic:Cancel()

Description: Cancels the periodic task and removes it from scheduling.

Example:

local periodic = scheduler:ExecutePeriodic(1.0, function()
print("Periodic task")
end, nil, nil, "cancelable_task")

-- Cancel after 5 seconds
scheduler:ExecuteInTime(5.0, function()
periodic:Cancel()
print("Periodic task cancelled")
end, "canceller")
periodic:NextTime()

Description: Returns the game time when this periodic task will next execute.

Returns:

  • (number): Next execution time in game seconds

Scheduler

Status: stable

Description: The main scheduler class that manages task execution and timing.

Methods

scheduler:AddTask(fn, id, param)

Description: Creates and adds a new task to the scheduler.

Parameters:

  • fn (function): Function to execute
  • id (string): Task identifier
  • param (any): Parameter for the function

Returns:

  • (Task): The created task
scheduler:ExecuteInTime(timefromnow, fn, id, ...)

Description: Executes a function once after the specified delay.

Parameters:

  • timefromnow (number): Delay in seconds
  • fn (function): Function to execute
  • id (string): Optional identifier
  • ...: Additional arguments for the function

Returns:

  • (Periodic): Periodic object representing the scheduled execution

Example:

scheduler:ExecuteInTime(3.0, function(message)
print("Delayed message:", message)
end, "delayed_print", "Hello World!")
scheduler:ExecutePeriodic(period, fn, limit, initialdelay, id, ...)

Description: Executes a function periodically at specified intervals.

Parameters:

  • period (number): Time between executions in seconds
  • fn (function): Function to execute
  • limit (number): Maximum executions (nil for infinite)
  • initialdelay (number): Delay before first execution (defaults to period)
  • id (string): Optional identifier
  • ...: Additional arguments for the function

Returns:

  • (Periodic): Periodic object for controlling the execution

Example:

local counter = 0
local periodic = scheduler:ExecutePeriodic(1.0, function()
counter = counter + 1
print("Count:", counter)
end, 10, 0.5, "counter_task") -- Run 10 times, start after 0.5 seconds
scheduler:KillTasksWithID(id)

Description: Terminates all tasks with the specified identifier.

Parameters:

  • id (string): The identifier of tasks to kill
scheduler:GetCurrentTask()

Description: Returns the currently executing task within a thread context.

Returns:

  • (Task): The current task or nil if not in a thread

Example:

StartThread(function()
local current = scheduler:GetCurrentTask()
print("Current task ID:", current.id)
end, "self_aware_task")

Constants

HIBERNATE

Value: "hibernate"

Status: stable

Description: Yield type constant for hibernating threads.

SLEEP

Value: "sleep"

Status: stable

Description: Yield type constant for sleeping threads.

Common Usage Patterns

Delayed Execution

-- Execute something after a delay
scheduler:ExecuteInTime(5.0, function()
print("5 seconds have passed")
end, "timer")

Periodic Tasks

-- Health regeneration every 2 seconds, 10 times
local regen = scheduler:ExecutePeriodic(2.0, function(inst)
if inst.components.health then
inst.components.health:DoDelta(5)
end
end, 10, nil, "health_regen", inst)

Thread Communication

local worker_task = StartThread(function()
print("Worker starting")
Hibernate() -- Wait for signal
print("Worker received signal")
end, "worker")

-- Signal the worker after some condition
scheduler:ExecuteInTime(3.0, function()
WakeTask(worker_task)
end, "signaler")

Cleanup Pattern

local cleanup_tasks = {}

-- Start multiple tasks
for i = 1, 5 do
cleanup_tasks[i] = StartThread(function()
-- Do work
while true do
print("Working", i)
Sleep(1)
end
end, "cleanup_example")
end

-- Clean them all up later
scheduler:ExecuteInTime(10.0, function()
for _, task in ipairs(cleanup_tasks) do
KillThread(task)
end
end, "cleanup")
  • Class: Base class system used by scheduler components
  • Main Functions: Core game loop that drives scheduler execution