Time Utilities

Overview

Citrine provides utilities for converting real-world time units into Minecraft ticks, as well as scheduling delayed and repeating tasks.

Packages:

• org.carpentry.citrine.api.util
• org.carpentry.citrine.api.util.schedule

TimeUtils

TimeUtils provides static methods for converting seconds, minutes, and hours into ticks.

Unit	Ticks
1 second	20
1 minute	1,200
1 hour	72,000

Available conversions

Each conversion is overloaded to support four numeric types:

• int
• float
• long
• double

Method	Conversion
seconds(value)	Seconds × 20
minutes(value)	Minutes × 1,200
hours(value)	Hours × 72,000

Examples

// Integer conversions
int cooldown = TimeUtils.seconds(5); // 100 ticks
int duration = TimeUtils.minutes(2); // 2400 ticks

// Float conversions
float delay = TimeUtils.seconds(1.5f); // 30 ticks

// Long conversions
long longDuration = TimeUtils.hours(2L); // 144000 ticks

// Double conversions
double preciseDuration = TimeUtils.seconds(0.25); // 5 ticks

These methods only perform unit conversion. They do not schedule tasks or track elapsed time.

Tick Scheduler

Citrine provides two tick schedulers:

• TickSchedulerClient for client-side tasks.
• TickSchedulerServer for server-side tasks.

Both schedulers support delayed execution and repeating execution.

Tasks are processed at the end of their respective tick events.

TickSchedulerClient

TickSchedulerClient schedules tasks to execute on the client.

It automatically registers its tick handler through ClientTickEvents.END_CLIENT_TICK when the class is initialized.

schedule()

Schedules a Runnable to execute after a specified delay.

TickSchedulerClient.schedule(
    TimeUtils.seconds(2),
    () -> {
        // Executed after the delay
    }
);

Parameter	Description
delayTicks	Number of ticks to wait before executing the task.
action	Runnable executed when the delay expires.

The task is removed after execution.

scheduleRepeating()

Schedules an action to execute once per client tick for a specified number of executions.

TickSchedulerClient.scheduleRepeating(
    20,
    iteration -> {
        // Executed once per tick
        // iteration starts at 0
    }
);

Parameter	Description
times	Number of executions.
action	IntConsumer receiving the current iteration number.

The iteration counter starts at 0 and increments with each execution.

For example, scheduling 5 executions produces iteration values 0, 1, 2, 3, and 4.

TickSchedulerServer

TickSchedulerServer provides the same scheduling functionality on the server.

It automatically registers its tick handler through ServerTickEvents.END_SERVER_TICK when the class is initialized.

schedule()

Schedules a Runnable to execute after a specified server tick delay.

TickSchedulerServer.schedule(
    TimeUtils.seconds(3),
    () -> {
        // Executed after the delay
    }
);

Unlike the client scheduler, this method returns a ScheduledTask instance.

scheduleRepeating()

Schedules an action to execute once per server tick for a specified number of executions.

TickSchedulerServer.scheduleRepeating(
    10,
    iteration -> {
        // Executed once per tick
    }
);

This method returns a RepeatingTask instance.

Task cancellation

The server scheduler exposes task handles that provide a cancel() method.

TickSchedulerServer.ScheduledTask task =
    TickSchedulerServer.schedule(
        TimeUtils.seconds(10),
        () -> {
            // This task can be cancelled before execution
        }
    );

task.cancel();

Repeating tasks can also be cancelled:

TickSchedulerServer.RepeatingTask task =
    TickSchedulerServer.scheduleRepeating(
        100,
        iteration -> {
            // Repeating action
        }
    );

task.cancel();

Cancellation prevents the task from continuing to execute.

Choosing a scheduler

Scheduler	Execution side	Delayed tasks	Repeating tasks	Cancellation handles
TickSchedulerClient	Client	Yes	Yes	No
TickSchedulerServer	Server	Yes	Yes	Yes

Use the client scheduler for client-side behavior, such as visual effects and local animations.

Use the server scheduler for gameplay logic, such as delayed damage, timed entity behavior, and server-controlled effects.

Important: These schedulers operate in ticks, not real-world seconds. At the normal 20 TPS, 20 ticks take approximately one second. If the server is running below 20 TPS, scheduled tasks will also take longer in real-world time.