Chrono API

This mod was extracted from Deus Chrono-Machina to separate its reusable time-control engine from the original mod’s gameplay content. It provides a standalone foundation for controlling the flow of time through commands and Java APIs, without requiring Deus Chrono-Machina itself.

Features

• Set supported tick rates from 0.0001 to 100 TPS. Normal speed is 20 TPS.
• Pause and resume time globally or around an entity owner.
• Create named time fields targeting entities, blocks, regions, chunks, or loaded dimensions.
• Advance paused named fields by a specified number of logical ticks.
• Configure field priorities, lifetime, target categories, and exclusions.
• Record loaded world history and rewind supported entity, block, item, projectile, inventory, and player state.
• Preview rewind readiness and available history before starting playback.
• Provide Java interfaces for time control, custom recording rules, state restoration, and client presentation.

Commands

All commands require permission level 2. Command names are case-sensitive, including rewindTime.

In the templates below, <...> represents a required argument and [...] represents an optional argument. Do not type the brackets.

Basic Time Control

/chrono settickrate <TPS> [radius <blocks>]
/chrono pausetime <true|false> [radius <blocks>]
/chrono clearfield

When executed by a player, these commands control a field that follows that player. The default radius is 40 blocks, and an explicit radius accepts 1–128 blocks.

When executed by the server console or a command block, settickrate and pausetime control the global field. The optional radius requires a player owner.

clearfield releases only the executing entity’s owned field. Resuming time preserves the previously selected rate.

Examples:

/chrono settickrate 5 radius 32
/chrono pausetime true
/chrono pausetime false
/chrono clearfield

Area Rewind

/chrono rewindTime <seconds>
/chrono rewindTime <seconds> at <x> <y> <z>
/chrono rewindTime <seconds> near <entity>
/chrono rewindTime <seconds> in <dimension> at <x> <y> <z>

These commands request 0.1–100 seconds of recorded history within the ordinary 32-block-radius rewind area.

near <entity> places the rewind center at that entity’s current location; it still rewinds an area. Use a named UUID or entity scope for a specific entity selection.

Examples:

/chrono rewindTime 5
/chrono rewindTime 3 at 100 64 100
/chrono rewindTime 5 near @e[type=minecraft:zombie,sort=nearest,limit=1]
/chrono rewindTime 5 in minecraft:the_nether at 0 64 0

Whitelist and Diagnostics

/chrono whitelist add <targets>
/chrono whitelist remove <targets>
/chrono whitelist clear
/chrono whitelist list
/chrono diagnostics
/chrono diagnostics entity <target>

The whitelist exempts entities from the shared time-field pause and rate scheduler. Named fields also provide their own exclusions.

Create a Named Field

/chrono field create <id> <scope>

Available scope templates:

global
dimension <dimension>
entities <targets>
uuid <uuid>
block <x> <y> <z>
blocks <fromX> <fromY> <fromZ> <toX> <toY> <toZ>
blocks <fromX> <fromY> <fromZ> <toX> <toY> <toZ> matching <predicate>
sphere <x> <y> <z> <radius>
box <fromX> <fromY> <fromZ> <toX> <toY> <toZ>
cylinder <x> <y> <z> <radius> <minY> <maxY>
follow <entity> <radius>
chunk <chunkX> <chunkZ>
chunks <fromChunkX> <fromChunkZ> <toChunkX> <toChunkZ>

For coordinate-based scopes, choose a loaded dimension explicitly with:

/chrono field create <id> in <dimension> <scope>

Entity selectors resolve to a fixed set of UUIDs when selected. Geometric fields evaluate spatial membership, and following fields move with their target. Named spherical and following fields accept radii of 0.5–256 blocks.

Examples:

/chrono field create workshop box 0 60 0 15 80 15
/chrono field create duel entities @e[type=minecraft:zombie,sort=nearest,limit=1]
/chrono field create aura follow @s 32
/chrono field create kilns blocks 0 64 0 15 70 15 matching minecraft:furnace
/chrono field create nether_zone in minecraft:the_nether sphere 0 64 0 32

Control a Named Field

Command template	Function
/chrono field rate <id> <TPS>	Set the field’s rate to 0.0001–100 TPS.
/chrono field pause <id> <true|false>	Pause or resume while preserving its rate.
/chrono field step <id> <ticks>	Advance a paused field by 1–1200 logical ticks.
/chrono field lifetime <id> <ticks>	Set expiry in server ticks; 0 disables timed expiry.
/chrono field priority <id> <value>	Set overlap priority from −1000 to 1000. Higher priority wins.
/chrono field affects <id> <categories>	Choose applicable target categories.
/chrono field scope <id> <scope>	Replace the field’s selection.
/chrono field inspect <id>	View field state.
/chrono field preview <id> rewind <seconds>	Check rewind readiness without starting playback.
/chrono field rewind <id> <seconds>	Start a recorded rewind for the selection.
/chrono field stop <id>	Request a safe stop of that field’s active rewind.
/chrono field clear <id>	Reset controls while retaining its selection and ownership.
/chrono field remove <id>	Remove the field.
/chrono field list	List registered fields.

Target categories are entities, blocks, effects, and world, combined with +, or selected with all. World-clock control requires a global or dimension scope.

Exclusion templates:

/chrono field exclude <id> entities <targets>
/chrono field exclude <id> uuid <uuid>
/chrono field exclude <id> block <x> <y> <z>

/chrono field include entities /chrono field include uuid /chrono field include block

`include` removes an exclusion; it does not add objects outside the original scope.

Example workflow:

```mcfunction
/chrono field create workshop box 0 60 0 15 80 15
/chrono field affects workshop entities+blocks+effects
/chrono field exclude workshop entities @a
/chrono field rate workshop 5
/chrono field pause workshop true
/chrono field step workshop 1
/chrono field inspect workshop

After sufficient history has accumulated:

/chrono field preview workshop rewind 2
/chrono field rewind workshop 2

Player-created fields are owner-controlled. The server console can manage all named fields.

Java API

Run mutations on the logical server thread.

Basic API: ChronoTime

Use ChronoTime for owner-following fields, global control, and ordinary area rewind.

import chrono_api.api.ChronoTime;
import net.minecraft.server.level.ServerPlayer;

public final class TimeAbilities {
    private TimeAbilities() {}

    public static void slowTime(ServerPlayer owner) {
        // 8 TPS, with a 32-block owner-following radius.
        ChronoTime.setTickrate(8.0F, owner, 32.0D);
    }

    public static void stopTime(ServerPlayer owner) {
        ChronoTime.pause(true, owner, 32.0D);
    }

    public static void resumeTime(ServerPlayer owner) {
        // Keeps the previously selected rate.
        ChronoTime.pause(false, owner);
    }

    public static void releaseField(ServerPlayer owner) {
        ChronoTime.clear(owner);
    }

    public static boolean rewind(ServerPlayer caster) {
        return ChronoTime.rewind(
                caster.serverLevel(),
                caster.position(),
                5.0D,
                caster
        );
    }

    public static void resetGlobalTime() {
        ChronoTime.clear(null);
    }
}

Passing null as the owner selects global control:

ChronoTime.setTickrate(40.0F, null);
ChronoTime.pause(true, null);
ChronoTime.clear(null);

Query an entity’s effective state:

boolean paused = ChronoTime.isPaused(entity);
float rate = ChronoTime.tickrate(entity);
boolean rewinding = ChronoTime.isRewinding(entity);

ChronoTime.rewind(...) returns whether the request was accepted. Check this result before applying an ability cooldown. This ordinary rewind excludes its caster from restoration.

Named Fields: TimeScope and TimeControl

Use TimeScope to define a selection and TimeControl to operate on its named field.

import chrono_api.api.ChronoTime;
import chrono_api.api.TimeControl;
import chrono_api.api.TimeOperationResult;
import chrono_api.api.TimeScope;
import net.minecraft.server.MinecraftServer;
import net.minecraft.server.level.ServerPlayer;

public final class NamedTimeFields {
    private static final String FIELD_ID = "example:temporal_zone";

    private NamedTimeFields() {}

    public static TimeOperationResult create(ServerPlayer owner) {
        MinecraftServer server = owner.serverLevel().getServer();

        TimeScope scope = TimeScope.sphere(
                owner.serverLevel().dimension(),
                owner.position(),
                32.0D
        ).withTargets(TimeScope.ENTITIES | TimeScope.EFFECTS);

        TimeOperationResult created = ChronoTime.createField(
                server, FIELD_ID, owner.getUUID(), scope
        );

        if (!created.successful()) {
            return created;
        }

        return TimeControl.rate(
                server, FIELD_ID, owner.getUUID(), 5.0F
        );
    }

    public static TimeOperationResult pause(ServerPlayer owner) {
        return TimeControl.pause(
                owner.serverLevel().getServer(),
                FIELD_ID, owner.getUUID(), true
        );
    }

    public static TimeOperationResult rewind(ServerPlayer owner) {
        return TimeControl.rewind(
                owner.serverLevel().getServer(),
                FIELD_ID, owner.getUUID(), 5.0D, owner
        );
    }

    public static TimeOperationResult remove(ServerPlayer owner) {
        return TimeControl.remove(
                owner.serverLevel().getServer(),
                FIELD_ID, owner.getUUID()
        );
    }
}

Other available scope factories include:

TimeScope.global()
TimeScope.dimension(level.dimension())
TimeScope.entities(level.dimension(), entityUUIDs)
TimeScope.blocks(level.dimension(), blockPositions)
TimeScope.box(level.dimension(), from, to)
TimeScope.cylinder(level.dimension(), center, radius, minY, maxY)
TimeScope.follow(entity, radius)
TimeScope.chunks(level.dimension(), packedChunkPositions)

Named-field operations follow this calling pattern:

TimeControl.rate(server, id, actorUUID, ticksPerSecond);
TimeControl.pause(server, id, actorUUID, paused);
TimeControl.step(server, id, actorUUID, logicalTicks);
TimeControl.lifetime(server, id, actorUUID, serverTicks);
TimeControl.priority(server, id, actorUUID, priority);
TimeControl.scope(server, id, actorUUID, newScope);
TimeControl.affects(server, id, actorUUID, targetMask);
TimeControl.preview(server, id, actorUUID, seconds);
TimeControl.rewind(server, id, actorUUID, seconds, caster);
TimeControl.stop(server, id, actorUUID);
TimeControl.clear(server, id, actorUUID);
TimeControl.remove(server, id, actorUUID);

actorUUID identifies the responsible owner. A null actor is reserved for trusted server integrations.

Operations return TimeOperationResult, including successful(), code(), and message(). For rewind previews, inspect preview().accepted() to determine readiness; a successful preview query does not itself mean playback can start.

Integration Hooks

Interface	Purpose
TickratePolicy	Field radius, lifetime policy, immunity, automatic exemptions, and freeze state.
RewindIntegration	Recording eligibility, protected content, custom player snapshots, and rewind lifecycle callbacks.
TimeEventPolicy	Freeze snapshots, damage rules, and server event callbacks.
TimeRuntimeHooks.Extension	Entity-control and block-mutation rules.
ClientTimeHooks.Extension	Client interpolation, entity holds, sound callbacks, and rewind presentation.

Recording and Rewind Limits

Rewind uses available recorded history in loaded areas. The ordinary recorder captures history around eligible players after an 80-player-tick warm-up; named scopes also require time to accumulate their own history coverage.

History is held in memory for the server session. Only one rewind task runs at a time. Requests may be rejected when history is incomplete or restoring the selection would create an unsafe partial interaction.

Coverage depends on the mechanisms used by other mods. Custom storage, animation, and external state may require integration hooks.

Requirements

• Minecraft 1.20.1
• Minecraft Forge 47 or newer
• Java 17

Install Chrono API on both the server and connecting clients. Single-player is supported.