|
Simutrans-Squirrel-API
|
Simutrans offers to possibility to add scripted scenarios and computer-controlled players.
The scripts have to be written in squirrel. The manual can be found at Squirrel main page. As squirrels like to crack nuts, understandably the script files get the extension '.nut'.
See also Scenario interface and Scenario only functions.
You first need an idea - a vision what a scenario may look like. Then you have to cast this idea into a savegame. That is, create the world in which your scenario will live. You are the ruler of this toy universe, you are in charge of the rules, which go into the script.
There are several commented examples.
The scenario plays in a savegame. This savegame is tied to the pak-set you are using (e.g. pak64, pak128.Britain). Hence, the scenario files have to go into a sub-folder of the pak-set. The pak-set is found in a directory named pak-something, which is in the same directory, where the program itself is located.
Your scenario file goes into the folder
pak-something/scenario/myscenario/
The scenario script must be in the file
pak-something/scenario/myscenario/scenario.nut
Translation files go into the scenario sub-directory with the same name as your file (just without extension)
pak-something/scenario/myscenario/
If you need more complex texts, these go into sub-directories named after the language, in which they are written.
pak-something/scenario/myscenario/en/ <- English files go here.
pak-something/scenario/myscenario/de/ <- German files go here.
Scenarios can also be put into the addons folder:
addons/pak-something/scenario/myscenario/
See also AI interface.
Your script file goes into the folder
ai/myai/
The main script file must be
ai/myai/ai.nut
The ai scripts can also be put into
addons/ai/myai/
See also Tool interface and Tool only functions.
The script file (tool.nut) as well as the configuration file (description.tab) go into
pak-something/tool/mytool/
Related pak-files have to be placed in
pak-something/
directly.
This is a plain text file with the following entries:
title=Name of tool to be shown in tool selection dialog
type=one_click or two_click
tooltip=Tooltip for the icon in the toolbar
restart=Set to 1 if the virtual machine has to be restarted after each call to the work functions.
menu=Parameter that can be used to load tools with menuconf.tab
icon=Name of cursor object (loaded from some pak-file), used images: 0 = cursor, 1 = icon, 2 = marker image
Check out the sections on the Modules page. See also Common pitfalls.
Squirrel has some built-in data types: among them integer, string, tables, and arrays. These are widely used throughout this documentation in the function declarations.
If tables or arrays carry template parameters, this indicates the expected type of elements of the array or table. See factory_x::input for an example.
All coordinates in the script are with respect to the initial rotation of the map. If a player rotates a map, then all coordinates are translated to the original rotation. This affects the classes coord and coord3d as well as any functions that expect coordinates as input, as for instance factory_x::factory_x or rules::forbid_way_tool_rect.
A lot of stuff is possible for network play. There are some limitations of course. These are due to the fact, that the scripts are solely run on the server, the client does not need to have the script available at all. This implies for instance that all scenario texts are translated to the server's language.
If simutrans is started with '-debug 2', all errors and warnings are logged to standard output (i.e. terminal). If simutrans is started in addition with '-log', all the output is written to the file script.log. In particular, everything that is print-ed by the script, goes into this file.
In case of error, an error window pops up showing the call stack and the values of local variables. You can then repair your script, and restart the scenario via New Game - Scenario. You do not need to restart simutrans to reload your script.
Such support is available of course. If a running scenario is saved, the information about the scenario is saved within the savegame. Upon loading, the scenario is resumed, by calling the function resume_game.
You can save data in the savegame. In order to do so, you have to keep these data in the global table persistent. This table is saved and loaded.
1.8.14