These functions are intended to quickly return a result. In network games, it is not allowed to call any map-altering tools from within such a function, see the section on Functions to alter the state of the game and map.
◆ exit()
Exits the tool. Do cleanup here.
- Returns
- true upon success.
- Parameters
-
| pl | player instance to use this tool. |
◆ get_api_version()
| string get_api_version |
( |
| ) |
|
Returns string containing the version of the api that the scenario supports. By default returns the string scenario::api.
If it returns "*" then this indicates that the scenario works in the most current api version. Currently "112.3" and "120.1" are supported.
◆ get_map_file()
Called before starting the scenario. Should return filename of the savegame to be used for this scenario. If it returns "<attach>" the scenario is started with the currently running world. By default returns the string map::file.
- Returns
- filename or "<attach>"
◆ init()
Initializes the tool.
- Returns
- true upon success.
- Parameters
-
| pl | player instance to use this tool. |
◆ is_convoy_allowed()
Called when user wants to start convoy.
- Warning
- Function will NOT be called in network games.
- Parameters
-
| pl | player number |
| convoy | convoy to start |
| depot | convoy is in this depot |
- Returns
- null if allowed, an error message otherwise
◆ is_schedule_allowed()
| string is_schedule_allowed |
( |
integer |
pl, |
|
|
schedule_x |
schedule |
|
) |
| |
Called when user changed a schedule (closes schedule window).
- Warning
- Function will NOT be called in network games.
- Parameters
-
| pl | player number |
| schedule | the schedule |
- Returns
- null if allowed, an error message otherwise
◆ is_tool_allowed()
| bool is_tool_allowed |
( |
integer |
pl, |
|
|
integer |
tool_id, |
|
|
way_types |
wt |
|
) |
| |
Function is called when toolbars are filled with icons or when a tool should be activated.
There is a default implementation, which forbids map-editing tools.
- Attention
- Results are not transfered over network, use the functions provided in rules in this case.
- Parameters
-
| pl | player number |
| tool_id | see tool_ids |
| wt | waytype of tool |
- Returns
- true if tool is allowed.
◆ is_valid_pos()
Can the tool start/end on pos? If it is the second click, start is the position of the first click. Possible return values: 0 = no 1 = This tool can work on this tile (with single click) 2 = On this tile can dragging start/end 3 = Both (1 and 2)
- Parameters
-
| pl | player instance to use this tool. |
| pos | position to test |
| start | first tile clicked by user |
◆ is_work_allowed_here()
| string is_work_allowed_here |
( |
integer |
pl, |
|
|
integer |
tool_id, |
|
|
coord3d |
pos |
|
) |
| |
Called when user clicks on a tile to build or remove something.
This function is network-aware: Error messages are sent back over network to clients.
The error message can contain a coordinate, which is used to show a location on the map. In order to show the right place, use coord_to_string. The must be enclosed in parentheses or prefixed with @ .
return "You cannot do this. The guy living at (" +
coord_to_string({x=47, y=11}) +
") does not like you!" - Attention
- Does not work with waybuilding and all tools that need path-finding, use the functions provided in rules in this case.
- Parameters
-
| pl | player number |
| tool_id | see tool_ids |
| pos | coordinate |
- Returns
- null if allowed, an error message otherwise
◆ jump_to_link_executed()
| string jump_to_link_executed |
( |
coord3d |
pos | ) |
|
Called when player click link in scenario windows.
- Parameters
-
| pos | coordinate go to in link |
- Returns
- null if allowed, an error message otherwise
◆ resume_game()
This function is called when a savegame with active scenario is loaded. Do all the initializations and post-processing here.
