View source for LuaAPI/wesnoth/schedule


The <tt>schedule</tt> module contains functions to query and manipulate the time of day schedule. In addition to the functions in this module, the [[../#wesnoth.current|wesnoth.current.schedule]] object represents the active schedule itself.

== Functions ==

=== wesnoth.schedule.get_time_of_day ===

* {{LuaGameOnly}} '''wesnoth.schedule.get_time_of_day'''(''reference'', [''for turn'']) &rarr; ''time of day info''

Returns the schedule information. The ''reference'' can be any of the following:

* a location - returns the information for that hex, accounting for any time areas
* a time area ID - returns the information for that time area
* nil - returns the information for the global scenario schedule

The second parameter is the turn number for which to return the information, which defaults to the current turn. This function does not account for any illumination type effects (either unit abilities or terrain lighting) that might alter the effective time of day - use [[#wesnoth.schedule.get_illumination|get_illumination]] instead if you need that.

The function returns a table with these named fields:

* ''time_of_day''.'''id''' &rarr; ''ID''

The ID of the [time] tag.

* ''time_of_day''.'''lawful_bonus''' &rarr; ''bonus''

The lawful bonus on this hex.

* ''time_of_day''.'''bonus_modified''' &rarr; ''bonus''

The difference between '''lawful_bonus''' and the base lawful bonus from the [time] tag. For '''get_time_of_day''', this is always 0, but for '''get_illumination''', it may be non-zero.

* ''time_of_day''.'''red''' &rarr; ''integer''
* ''time_of_day''.'''green''' &rarr; ''integer''
* ''time_of_day''.'''blue''' &rarr; ''integer''
* ''time_of_day''.'''image''' &rarr; ''image path''
* ''time_of_day''.'''mask''' &rarr; ''image path''
* ''time_of_day''.'''sound''' &rarr; ''sound path''
* ''time_of_day''.'''name''' &rarr; ''visible name''

All the information on how the time of day is shown to the player.

=== wesnoth.schedule.get_illumination ===

* {{LuaGameOnly}} '''wesnoth.schedule.get_illumination'''(''location'', [''for turn'']) &rarr; ''time of day info''

Like '''get_time_of_day''', but also accounts for modifiers from unit illumination or terrain lighting on the passed hex. The parameters accepted are the same, but if passed nil or a time area ID, it will return the exact same information that '''get_time_of_day''' returns.

This only considers modifiers based on the current state of the map. If you wanted to perform a "what if" check to determine what the illumination would become after a unit moves, you would need to move the unit, call this function, and then move it back where it started. Similarly, if you wanted to consider the illumination after a hypothetical terrain change, you would need to change the terrain, call the function, and then change it back.

=== wesnoth.schedule.replace ===

* {{LuaGameOnly}} '''wesnoth.schedule.replace'''(''new schedule'')

Replaces the global scenario schedule with a new schedule.

[[Category:Lua Reference]]