Home
Games
Marketplace
Compendium Character Vault Roll20 for iPad and Android
Character Vault
Any Concept / Any System
Compendium
Your System Come To Life
Roll20 for Android
Streamlined for your Tablet
Roll20 for iPad
Streamlined for your Tablet

Personal tools

Difference between revisions of "Script:cron"

From Roll20 Wiki

Jump to: navigation, search
m
(tagged as "discontinued API")
 
(15 intermediate revisions by one user not shown)
Line 2: Line 2:
 
|name=cron
 
|name=cron
 
|author={{user profile|503018|manveti}}
 
|author={{user profile|503018|manveti}}
−
|version=0.4
+
|version=0.11
−
|lastmodified=2015-05-11}}
+
|lastmodified=2015-08-10}}
  
 
'''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.
 
'''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.
+
It is recommended that this script be used in conjunction with the [[Script:CommandShell|CommandShell]] module, which will improve output formatting and command discovery, as well as enabling the scheduling and execution of '''CommandShell'''-aware commands.
  
  
Line 18: Line 18:
 
{{token|S}} {{rarr}} cron {{token|options}} {{string|-}}
 
{{token|S}} {{rarr}} cron {{token|options}} {{string|-}}
 
{{token|S}} {{rarr}} cron -l<br>
 
{{token|S}} {{rarr}} cron -l<br>
−
{{token|S}} {{rarr}} cron -R {{token|job ids}}
+
{{token|S}} {{rarr}} cron -R {{token|job ids}}<br>
−
{{token|options}} {{rarr}} -{{string|-}}
+
{{token|options}} {{rarr}} {{token|option}} {{token|options}}<br>
−
{{token|options}} {{rarr}} --{{string|-}}
+
{{token|options}} {{rarr}} {{epsilon}}
−
{{token|options}} {{rarr}} -{{string}} {{string|-}}
+
{{token|option}} {{rarr}} -{{string|-}}
−
{{token|options}} {{rarr}} --{{string}} {{string|-}}
+
{{token|option}} {{rarr}} --{{string|-}}
 +
{{token|option}} {{rarr}} -{{string}} {{string|-}}
 +
{{token|option}} {{rarr}} --{{string}} {{string|-}}
 
{{token|job ids}} {{rarr}} {{string|-}}
 
{{token|job ids}} {{rarr}} {{string|-}}
 
{{token|job ids}} {{rarr}} {{token|job ids}} {{string|-}}
 
{{token|job ids}} {{rarr}} {{token|job ids}} {{string|-}}
Line 37: Line 39:
 
* '''-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.
 
* '''-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.
 
* '''-f''' ''USER'', '''--from''' ''USER'': The command will be executed as ''USER''.  This need not be a player or character in the game.
 +
* '''-A''' ''N'', '''--advance''' ''N'': Advance the round counter by ''N'' rounds.  This will cause initiative-based jobs to advance as if the tracker had been advanced through ''N'' full rounds.
 
* '''-l''', '''--list''': List all scheduled jobs.
 
* '''-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").}}
 
* '''-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").}}
Line 50: Line 53:
 
::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.
 
::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.
 
:!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.
+
::Be aware that the time zone is GMT, not local time of the client who runs the command.
 
:!cron -a 30 Hey!  It's 30 seconds later than when I typed this.
 
:!cron -a 30 Hey!  It's 30 seconds later than when I typed this.
 
::Probably more useful with larger delay amounts.
 
::Probably more useful with larger delay amounts.
 
:!cron -t 0:00:00 -i 1:00:00 /desc The clock chimes.
 
:!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").
 
::This will fire every hour, on the hour.  (Can also just do "-t 0").
 +
:!cron -r 10 "!cron -R 42"
 +
::This will remove job 42 after 10 rounds.  Note that the quotes are required around commands which contain tokens which are valid !cron arguments (e.g. "-R").  Without the quotes, this will immediately remove job 42.
  
 
=== Changelog ===
 
=== Changelog ===
 +
{{changelog version|0.11|2015-08-10|* Fix typo which broke -f behavior}}
 +
{{changelog version|0.10|2015-08-07|* Add -A/--advance argument to advance initiative-based jobs N rounds.
 +
* Improve support for jobs on counts outside the range present in the tracker.}}
 +
{{changelog version|0.9|2015-08-05|* Add -n/--runs argument to auto-prune job after N executions}}
 +
{{changelog version|0.8|2015-07-23|* Add support for inline rolls in arguments}}
 +
{{changelog version|0.7|2015-07-09|* By default, execute commands as user who scheduled them}}
 +
{{changelog version|0.6|2015-06-11|* Add support for executing CommandShell-aware API commands}}
 +
{{changelog version|0.5|2015-05-26|* Add seamless roll template handling}}
 
{{changelog version|0.4|2015-05-11|* Use GMT instead of API server timezone}}
 
{{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.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.2|2015-05-08|* Add workaround for roll templates}}
 
{{changelog version|0.1|2015-04-28|* Initial release}}
 
{{changelog version|0.1|2015-04-28|* Initial release}}
 +
[[Category:Discontinued API Scripts]]

Latest revision as of 13:08, 17 June 2020

API ScriptAuthor: manveti
Version: 0.11
Last Modified: 2015-08-10
Code: cron
Dependencies: None
Conflicts: None

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 CommandShell module, which will improve output formatting and command discovery, as well as enabling the scheduling and execution of CommandShell-aware commands.


[edit] Syntax

!cron [options] <command>
!cron -l
!cron -R <job ID>
Formally:

S 

→ cron options

string

S 

→ cron -l

S 

→ cron -R job ids


options 

→ option

options


options 

→ ε

option 

→ -string

option 

→ --string

option 

→ -string string

option 

→ --string string

job ids 

→ string

job ids 

→ job ids

string
Parameter Values
options The !cron 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.
  • -A N, --advance N: Advance the round counter by N rounds. This will cause initiative-based jobs to advance as if the tracker had been advanced through N full rounds.
  • -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").

[edit] Examples

!cron -r 10 The bomb's timer reaches zero! It explodes for [[10d10]] 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 [[2d6]] 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 GMT, not local time of 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").
!cron -r 10 "!cron -R 42"
This will remove job 42 after 10 rounds. Note that the quotes are required around commands which contain tokens which are valid !cron arguments (e.g. "-R"). Without the quotes, this will immediately remove job 42.

[edit] Changelog

v0.11 (2015-08-10)

  • Fix typo which broke -f behavior


v0.10 (2015-08-07)

  • Add -A/--advance argument to advance initiative-based jobs N rounds.
  • Improve support for jobs on counts outside the range present in the tracker.


v0.9 (2015-08-05)

  • Add -n/--runs argument to auto-prune job after N executions


v0.8 (2015-07-23)

  • Add support for inline rolls in arguments


v0.7 (2015-07-09)

  • By default, execute commands as user who scheduled them


v0.6 (2015-06-11)

  • Add support for executing CommandShell-aware API commands


v0.5 (2015-05-26)

  • Add seamless roll template handling


v0.4 (2015-05-11)

  • Use GMT instead of API server timezone


v0.3 (2015-05-11)

  • Fix broken firing of count-based jobs


v0.2 (2015-05-08)

  • Add workaround for roll templates


v0.1 (2015-04-28)

  • Initial release
Retrieved from "https://wiki.roll20.net/index.php?title=Script:cron&oldid=20680"