There are many ways and strategies of scheduling game turns and/or actors. The ROT.Scheduler API is meant as a general scheduling abstraction; there are also three distinct implementations for commonly used scheduling approaches.
All available schedulers share these common methods:
add(item, repeat) to add a new schedulable item. There are no specific requirements for the item argument. The second argument specifies whether the scheduler shall treat the item as a repeated actor (such as a being or player), or a one-time event (such as an earthquake or a messenger appearing from nowhere).remove(item) to remove a previously added itemclear() to remove all itemsgetTime() to retrieve the elapsed time from the (internally) used Event queuenext() to get an item that should act (this is the most important part of a scheduler)The easiest scheduler is called ROT.Scheduler.Simple – it rotates all items evenly in a round-robin fashion.
In a more realistic game, your actors might want to act based on their speed. Due to the turn-based nature of the game, the speed is more accurately described as a frequency in which turns happen for a particular actor. ROT.Scheduler.Speed plans turns based on this fact: your actors must implement the getSpeed() method, which returns the relative actor speed (an actor with speed=100 will get twice as many turns as actor with speed=50).
The most complex scheduling strategy expects individual actors to perform time-dependent actions. Every action takes a different amount of time, so the "speed" of an actor varies from action to action. Every time an actor is picked, the scheduler needs to be told about the current action's duration – to properly schedule a next turn for this actor.
To use the ROT.Scheduler.Action, make sure you call its setDuration() method after calling next(): this sets the delay for current actor's next turn.
Finally, you can specify the initial scheduling delay as an optional third argument to add(). The default value is "1".