Schedules🔗

API State: Unfinished

Unfinished

This part of the API is brand-new. It will be changed if there are any bugs, missing features or usability improvements.

It is not recommended relying on this part of the API, it will most likely change.

Draft

Our own usage and testing has shown that this part of the API is complete and seems bug free. However, other plugins may have other use cases which are not covered by our testing. Therefore, please go ahead and use this API part. Let us know if there are missing features or bugs. This API part will be changed if there are more bugs, missing features or usability improvements.

Please use this part of the API and give us feedback!

Stable

Both our own and third party testing showed that this part of the API is complete. Only bugs and major conceptual problems would lead to more changes.

This part of the API should be safe to use. We try to keep it compatible with previous versions if changes are needed.

If the native schedule types are not enough for you, this API enables you to create your own type.

API Overview🔗

Creating a new schedule type🔗

To implement a new schedule type you have to create both the Schedule and the Scheduler class.

About this guide

This guide will show you how to create a custom schedule that runs every x ticks, just like a redstone clock.
While this does not make that much sense, it is a super simple example to show the principle.

Schedule Class🔗

The schedule class must hold all the schedules' data. When reloading BetonQuest will try to parse all packages and construct new instances of this class.

Have a look at this example to see how to implement your own schedule.

Example Schedule


public class MyCustomSchedule extends Schedule
You can extend either Schedule or CronSchedule. 

    The latter has already implemented all cron parsing logic.
 {

    private final int ticks, rebootSleep;

    
You need to define a Constructor that matches exactly this one.

Otherwise BetonQuest can't parse your schedule!

    public MyCustomSchedule(ScheduleID scheduleID, ConfigurationSection instruction) throws InstructionParseException { 
        super(scheduleID, instruction);
        try {
            ticks = Integer.parseInt(getTime()
getTime()/super.time provides the raw time string.

    You'll need to parse it and add your own logic.

In this example we just use it as interval of ticks.
);
        } catch (NumberFormatException e) {
            throw new InstructionParseException("Time is not a number");
Make sure to handle all parsing errors & thrown exceptions!

   If a schedule can't be loaded due to an invalid instruction,
   you should throw a InstructionParseException that describes
   the error.

        }

        if (getCatchup() != CatchupStrategy.NONE) {
You'll have to implement your own handling of catchup strategies
    in the Scheduler class.

If you don't want that, you can add this check if a CatchupStrategy
    was defined and throw an Exception.

            throw new InstructionParseException("Catchup " + getCatchup() + " is not supported by this schedule type");
        }

        rebootSleep = instruction.getInt("options.rebootSleep");
This is how you add custom options, if needed.

    }

    public int getTicks() { return ticks; }
    public int getRebootSleep() { return rebootSleep; }
}

Scheduler Class🔗

The scheduler will receive parsed schedules using addSchedule(S) and hold them in the schedules map.
It should contain all the scheduling & schedule execution logic.
It is also responsible for catching up missed schedules, if they have a catchup strategy other than NONE defined.

Here is a pretty basic example, that does not provide any catchup logic:

Example Scheduler


public class MyCustomScheduler extends Scheduler<MyCustomSchedule>
Your scheduler must extend Scheduler class.

    Between <> you have to put the name of your Schedule class.
 {

    private List<BukkitTask> tasks;

    @Override
    public void start() {
        super.start();
Always remember to call super.start() in your start() method!


        tasks = new ArrayList<>();
        for (MyCustomSchedule schedule : schedules.values()
An easy way to iterate over all loaded schedules.
) {
            
Schedule your events to run when their time instruction says.

            BukkitTask task = new BukkitRunnable() {
                @Override
                public void run() {
                    executeEvents(schedule);
                }
            }.runTaskTimer(MyPlugin.getInstance()
Pass your plugin instance for the Bukkit-Scheduler.
, schedule.getRebootSleep(), schedule.getTicks());

            tasks.add(task);
Keep a list of all your active schedules somewhere, so you can easily cancel them.

        }
    }

    @Override
    public void stop() {
        super.stop();
Always remember to call super.stop() in your stop() method!


        for (BukkitTask task : tasks) {
            task.cancel();
Make sure to cancel all active schedules in stop() method.

        }
    }
}

Register the type🔗

To register the new schedule type to BetonQuest, use the following method:


BetonQuest.getInstance().registerScheduleType("redstoneScheduler"
The name of your new schedule type to use in configs.
,
  MyCustomSchedule.class
Your Schedule class.
,new MyCustomScheduler()
A new instance of your Scheduler.
);

You'll need to call it after BetonQuest was enabled.