Simutrans-Squirrel-API Documentation

Table of Contents

• Scripted scenarios
  • How to create a scenario.
  • Example scenario scripts
  • Recommended directory structure
• Scripted AI players
• Scripted tools
  • Recommended directory structure
  • The file description.tab
• General scripting advice
  • Squirrel data types
  • Coordinates
  • Network play
  • Logging and error handling
  • Load-Save support

Simutrans offers to possibility to add scripted scenarios and computer-controlled players.

Scripting language

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'.

Scripted scenarios

See also Scenario interface and Scenario only functions.

How to create a scenario.

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.

Example scenario scripts

There are several commented examples.

1. A simple example script
2. A script showing translatable texts.

Recommended directory structure

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/

Scripted AI players

See also AI interface.

Recommended directory structure

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/

Scripted tools

See also Tool interface and Tool only functions.

Recommended directory structure

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.

The file description.tab

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


General scripting advice

Check out the sections on the Modules page. See also Common pitfalls.

Squirrel data types

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.

Coordinates

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.

Network play

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.

Logging and error handling

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.

Load-Save support

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.