Simutrans-Squirrel-API
Functions
Functions that should return quickly.

Functions

void resume_game ()
 
string get_map_file ()
 
string get_api_version ()
 
bool is_tool_allowed (integer pl, integer tool_id, way_types wt)
 
string is_work_allowed_here (integer pl, integer tool_id, coord3d pos)
 
string is_schedule_allowed (integer pl, schedule_x schedule)
 
string is_convoy_allowed (integer pl, convoy_x convoy, depot_x depot)
 

Detailed Description

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.

Function Documentation

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.

string 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>"
string is_convoy_allowed ( integer  pl,
convoy_x  convoy,
depot_x  depot 
)

Called when user wants to start convoy.

Warning
Function will NOT be called in network games.
Parameters
plplayer number
convoyconvoy to start
depotconvoy is in this depot
Returns
null if allowed, an error message otherwise
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
plplayer number
schedulethe schedule
Returns
null if allowed, an error message otherwise
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
plplayer number
tool_idsee tool_ids
wtwaytype of tool
Returns
true if tool is allowed.
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 @ .

1 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
plplayer number
tool_idsee tool_ids
poscoordinate
Returns
null if allowed, an error message otherwise
void resume_game ( )

This function is called when a savegame with active scenario is loaded. Do all the initializations and post-processing here.