Catenation

Catenation

@since 1.11.0

A catenation is a series of tasks that run each other after ticks. It replaces the old DelayManager with a clearer syntax and more features.

Catenation is not serialized. This means catenation is not persisted. All catenation will stop when the server stops, but it won't restart when the server restarts. Check PersistedCatenation to get catenation can be saved and restart when the server starts next time.

Example

events.onPlayerLoggedIn(function(event as PlayerLoggedInEvent) {
    val player as IPlayer = event.player;
    if (event.player.world.remote) return;
    event.player.world.catenation() // builds a new catenation
        // first, prints a debug message to the log
        // the context is a data holder that catenation tasks share
        .run(function(world, context) {
            print("the start of catenation");
            context.data = world.time; // the data is an `IData`, int/long should be implicitly cast to IData
        })
        // then, sleeps for 200 ticks
        .sleep(200)
        // then, after 200 ticks, sends a message to the player
        // 'then' method is equivalent to 'run' method, but it could be easier to read
        .then(function(world, context) {
            player.sendMessage("The message is shown 10 seconds after the player logs in");
            player.sendMessage("You logged at world time" ~ context.data.asString());
        })
        // sleeps until the world is raining
        .sleepUntil(function(world, context) {
            return world.raining;
        })
        .then(function(world, context) {
            player.sendMessage("It is raining!");
        })
        // stop the catenation if the player is dead, to prevent potential memory leak
        // if a catenation is stopped, subsequent tasks will not be ran.
        .stopWhen(function(world, context) {
            return !player.alive;
        })
        // the code that executed when the catenation is stopped
        // @since 1.12.7
        .onStop(function(world, context) {
            print(context.status.name);
        })
        // start the catenation
        .start();
});

The start method returns a catenation object. You can save it to a variable, and call catenation.stop() to stop the catenation manually. Although stopWhen method is suggested.

Method List

Catenation

the core object of the catenation system. Use ICatenationBuilder to build one.

Package: mods.zenutils.Catenation

void stop()

stops the catenation

boolean isStopped() or stopped getter

check if the catenation is stopped

void pause()

pauses the catenation. (since 1.12.8)

void play()

starts the catenation if it is paused. (since 1.12.8)

CatenationContext

The data holder that catenation tasks share.

Package: mods.zenutils.CatenationContext

CatenationContext contains an IData to save data between catenation tasks. Call data getter/setter or getData/setData methods to access it. And hasData method to check whether it has a custom data or not.

CatenationStatus getStatus() or status getter

Gets the status of the catenation.

void stop()

stops the catenation

catenation getter to get Catenation

CatenationStatus

@since 1.12.7

Package: mods.zenutils.CatenationStatus

You can use name getter to gets the name of the status (All capital letters), == operator to check if two CatenationStatus objects are equal, and isStop getter to check if it is stop.

Enumerations

The CatenationStatus is an enumeration. It has 8 enum constants. The methods below can get one.

// the catenation is working properly
CatenationStatus.working();

// the catenation is paused
CatenationStatus.pause();

// the catenation is stopped since all catenation tasks are completed
CatenationStatus.finish();

// the catenation is stopped by stop method call
CatenationStatus.stopManual();

// the catenation is stopped by stopWhen function
CatenationStatus.stopInternal();

// the catenation is stopped due to an exception in a catenation task or stopWhen function
CatenationStatus.error();

// the catenation is stopped since the linked world is unloaded. (for example, server stop)
CatenationStatus.unload();

// the catenation is waiting to serialize
// @since 1.13.0
CatenationStatus.serial();

IWorldFunction

Package: mods.zenutils.IWorldFunction

The IWorldFunction function is a function with the following parameters (in this order):

• IWorld world: the world where catenation command is executed
• CatenationContext context: the data holder that catenation tasks share

The function doesn't have return value.

IWorldCondition

Package: mods.zenutils.IWorldCondition

The IWorldFunction function is a function with the following parameters (in this order):

• IWorld world: the world where catenation command is executed
• CatenationContext context: the data holder that catenation tasks share

The function should return a boolean.

ICatenationBuilder

The builder of catenation. Use world.catenation() to create one.

Package: mods.zenutils.ICatenationBuilder

The return value is the builder itself to chain calling.

Runs the function immediately as a part of the catenation.

ICatenationBuilder run(IWorldFunction function);

Sleeps some ticks.

ICatenationBuilder sleep(long ticks);

Sleeps until the condition is met.

ICatenationBuilder sleepUntil(IWorldCondition condition);

Stops the catenation (subsequent tasks) if the condition is met.

ICatenationBuilder stopWhen(IWorldCondition condition);

Equivalent to run method.

ICatenationBuilder then(IWorldFunction function)

Builds and starts the catenation.

Catenation start();