====== Time based python scripts ======

===== Common conventions =====
The folder [[http://crossfire.svn.sourceforge.net/viewvc/crossfire/maps/trunk/python/tod|python/tod]] in crossfire maps contains several scripts \\
ready to be linked to //event_xxxx// object in a [[:crossfireeditor|map editor]] . \\
All those scripts use common naming and parameters conventions. 

==== JSON parameters ====
All parameters are passed as arguments in //Message// of event, using JSON (JavaScript Object Notation). \\
Basically, it takes the forms of "key" : "value" list enclosed in braces. \\
Example:<code javascript>
{
  "key1" : "value1",
  "key2" : "value2",

  "key3" : "value3"
}</code>
For a boolean type, the possible values are ''True'' and ''False'', other type are, for now, only String between double quotes. \\
Some script parameters accept list of value. \\
A list uses square bracket and separate it's value by comas. \\
Example:<code javascript>
{
    "key"   : "skeleton kills"
    "when"  : ["Dawn","Morning","Noon","Evening","Dusk"]
    "from"  : ["skeleton","generator"],
    "to"    : ["bones1","bones2","bones3"],
    "match" : "one"
}
</code>
I hope to see the [[:Gridarta]] editor be able to edit such structure for you, but until then you will have to do it by hand. It's not very complex to understand anyway.

==== Period type parameter values ====
All time based scripts use the notion of period name, as can be found in following table. The names are case sensitive. 

^ name of period ^ description ^
|The Season of New Year| Starting 1st month of the year, ending 3rd month|
|The Season of Growth| Starting 4th month of the year, ending 6st month|
|The Season of Harvest| Starting 7th month of the year, ending 9th month|
|The Season of Decay| Starting 10th month of the year, ending 12th month|
|The Season of the Blizzard| Starting 13th month of the year, ending 17th month|
|Month of Winter| |
|Month of the Ice Dragon| |
|Month of the Frost Giant| |
|Month of Valriel| |
|Month of Lythander| |
|Month of the Harvest| |
|Month of Gaea| |
|Month of Futility| |
|Month of the Dragon| |
|Month of the Sun| |
|Month of the Great Infernus| |
|Month of Ruggilli| |
|Month of the Dark Shades| |
|Month of the Devourers| |
|Month of Sorig| |
|Month of the Ancient Darkness| |
|Month of Gorokh| |
|the Day of the Moon| First day of the week|
|the Day of the Bull| Second day of the week|
|the Day of the Deception| Third day of the week |
|the Day of Thunder| Fourth day of the week |
|the Day of Freedom| Fifth day of the week|
|the Day of the Great Gods| Sixth day of the week |
|the Day of the Sun| Last day of the week|
|Night| Between 9:00 pm and 5:00 am |
|Dawn| Between 5:00 am and 8:00 am |
|Morning| Between 8:00 am and 13:00am |
|Noon| Between 13:00 am and 1:00 pm |
|Evening| Between 1:00 pm and 6:00 pm |
|Dusk| Between 6:00 pm and 9:00 pm |

For demonstration of the scripts, mapmakers are invited to take a look at the demo maps \\ 
at [[http://crossfire.svn.sourceforge.net/viewvc/crossfire/maps/trunk/test/tod|/test/tod]] and [[http://crossfire.svn.sourceforge.net/viewvc/crossfire/maps/trunk/test/tod2|/test/tod2]] \\
in the default crossfire maps.

===== Available scripts =====

==== Filtering ====
**Script** /python/tod/filter.py

**Description** Prevent the event this filter is attached to to occurs at specific period of the day. This can stop a lever (event_apply) from working, prevent a magic hear (event_say) from hearing anything, prevent a gate (event_trigger) from opening.

**Parameters**
  * **when**(list): periods of day when this filter lets event it is attached to happen.
  * **match**: "one" or "all", whenever only one match in list is needed or all must match current time
  * **inverse**: if true, a match is seen as a non-match and a non-match is seen as a match. See that as a "every time except when ...." rule




==== Pushing ====
**Script** /python/tod/push.py

**Description**: Schedules a map trigger at a specific period of time. It runs a "connected" list inside the current map, at a specific time. This script could be used by any event, however it is typical to use it in the EVENT_TIME of a living object, so as to ensure the script is run often enough to react on time. However you could, without trouble, use it in EVEN_DEATH or a monster, EVENT_APPLY of a button, etc. Just keep in mind the script can't do anything unless it gets called ;) This script keep information on it's current push state, so it won't push twice the connected list and will release the connected list when needed. That way, it will behave nicely with map swapping and when connected to non regular events.

**Parameters**
  * **when**(list): periods of day when this script will stay "pushed".
  * **match**: one or all, whenever only one match in list is needed or all list must match current time
  * **inverse**: if true, a match is seen as a non-match and vice version. See that as a "every time except when ...." rule
  * **connected**: connection number to push/release in map

==== Object transforming ====
**Script** /python/tod/replace.py

**Description**:  Makes the object is is attached to swap at given periods of day with a specific object in the event's inventory. To use it, give this event's parameters a period an a match rule. Put also in the inventory the swapped object (owner of event) the object that will replace it. The swap is reversed when leaving the swap matching period. This work both on map items and on inventory items. Typically this script would be attached to the event_time of the object to transform.

**Parameters**
  * **when**(list): periods when this script's owner will stay transformed.
  * **match**: one or all, whenever only one match in list is needed or all list must match current time
  * **inverse**: if true, a match is seen as a non-match and vice version. See that as a "every time except when ...." rule


==== Map transforming ====

**Script** /python/tod/replace_in_map.py

**Description**:  Scan the current map of objects matching some criteria and transform them into another specific object. Like for Object Transforming, the transformation is reverted at end of specified period. This works only on map items. Typically this script would be attached to the event_time of guardian object.

**Parameters**
  * **when**(list): periods when this script's owner will stay transformed.
  * **match**: one or all, whenever only one match in list is needed or all list must match current time
  * **inverse**: if true, a match is seen as a non-match and vice version. See that as a "every time except when ...." rule
  * **from**(list): possible names a map object can match to be transformed. This is the name as given by [[:cfpython:#object|the Name field]]
  * **to**(list): name of objects that will be created to replace transformed object. The newly created objects will be made unpickable so they stay on the map. If more than one, a random is chosen for each transformed object.
  * **key**: a keyword used to keep track of transformed object when time comes to untransform them. This is used to prevent clash if several transformation script are working on same map