Roll20 Wiki

{{script overview
|name=cron
|author={{user profile|503018|manveti}}
|version=0.4
|lastmodified=2015-05-11}}

'''Cron''' allows a user to schedule commands to run at some point in the future.  Jobs can be scheduled based on the turn tracker or clock time (relative to now or at some specific time in the future), and can optionally recur at a specified interval.  Each job is given a unique ID, which can be used to remove it at a later time.

It is recommended that this script be used in conjunction with the [[Script:CommandShell|CommandShell]] module, which will improve output formatting and command discovery.


=== Syntax ===
{{syntaxbox top|cron|formal=true}}
{{API command|cron}} {{API parameter|name=options|optional=true}} {{API parameter|name=command}}<br>
{{API command|cron}} -l<br>
{{API command|cron}} -R {{API parameter|name=job ID}}<br>
{{Formal API command|
{{token|S}} {{rarr}} cron {{token|options}} {{string|-}}
{{token|S}} {{rarr}} cron -l<br>
{{token|S}} {{rarr}} cron -R {{token|job ids}}
{{token|options}} {{rarr}} -{{string|-}}
{{token|options}} {{rarr}} --{{string|-}}
{{token|options}} {{rarr}} -{{string}} {{string|-}}
{{token|options}} {{rarr}} --{{string}} {{string|-}}
{{token|job ids}} {{rarr}} {{string|-}}
{{token|job ids}} {{rarr}} {{token|job ids}} {{string|-}}
}}
{{syntaxbox end}}

{{param description top}}
{{param description|name=options|value=The <code>!cron</code> command accepts the following options:
* '''-h''', '''--help''': Displays a help message and exits.
* '''-r''' ''N'', '''--rounds''' ''N'': The first execution of the command will be in ''N ''rounds.  If an initiative count is not specified (see below), the current count will be used (or 0, if none is available).  Cannot be used with time-based arguments.
* '''-c''' ''N'', '''--count''' ''N'': The command will execute on initiative count ''N''.  If the number of rounds in the future is not specified (see above), it will default to the next time the specified count comes up.  Cannot be used with time-based arguments.
* '''-t''' ''T'', '''--time''' ''T'': The first execution of the command will be at time ''T'' (HH:MM:SS).  If not all values are given, zeroes will be added to the smaller end (e.g. "1:23" will be interpreted as "1:23:00").  Times are in GMT and will be interpreted to be within the next 24 hours.  Cannot be used with initiative-based arguments.
* '''-a''' ''T'', '''--after''' ''T'': The first execution of this command will be after interval ''T'' (HH:MM:SS).  If not all values are given, zeroes will be added to the larger end (e.g. "1:23" will be interpreted as "00:01:23").  Cannot be used with initiative-based arguments.
* '''-i''' ''I'', '''--interval''' ''I'': The command will be repeated ever ''I'' rounds or ''I'' time (HH:MM:SS).  If rounds or count is given, or if ''I'' is a single number, ''I'' will be considered a number of rounds.  Otherwise, ''I'' will be considered a time interval, with zeroes added to the larger end to fill missing values (e.g. "1:23" will represent 1 minute and 23 seconds).  If no first execution time is specified, the first execution will be ''I'' rounds or seconds in the future.
* '''-f''' ''USER'', '''--from''' ''USER'': The command will be executed as ''USER''.  This need not be a player or character in the game.
* '''-l''', '''--list''': List all scheduled jobs.
* '''-R''', '''--remove''': Remove all specified jobs.  All other arguments will be considered job IDs (so multiple jobs can be removed with one command like "!cron -R 1 5 8").}}
{{param description bottom}}

=== Examples ===

:!cron -r 10 The bomb's timer reaches zero!  It explodes for <nowiki>[[10d10]]</nowiki> damage.
::Called on the initiative count in which the bomb's timer is set, it will explode in 10 rounds.
:!cron -c 12 -i 1 -f "Hey, eejit!" /w gm Don't forget the spider's turn
::A forgetful GM might use this subtle reminder that the party's mage summoned a spider which acts on the mage's initiative count (12, in this example).
:!cron -f "Acid Rain" -i 1 The acid burns for <nowiki>[[2d6]]</nowiki> damage.
::Inline roll results are stripped from the command and replaced with the original roll expression.  Long story short: the above gives a new damage roll each round.
:!cron -f Nanny -t 23:00 Bedtime for sleepy-head.  Time to wrap things up.
::Be aware that the time zone is based on the API server, not the client who runs the command.
:!cron -a 30 Hey!  It's 30 seconds later than when I typed this.
::Probably more useful with larger delay amounts.
:!cron -t 0:00:00 -i 1:00:00 /desc The clock chimes.
::This will fire every hour, on the hour.  (Can also just do "-t 0").

=== Changelog ===
{{changelog version|0.4|2015-05-11|* Use GMT instead of API server timezone}}
{{changelog version|0.3|2015-05-11|* Fix broken firing of count-based jobs}}
{{changelog version|0.2|2015-05-08|* Add workaround for roll templates}}
{{changelog version|0.1|2015-04-28|* Initial release}}