Script Tools

Squirrel Script Tool for one or two clickslink

Simutrans 122.0 and higher

Directory Structurelink

A scripted tool consists of two files, tool.nut and description.tab. tool.nut is required and description.tab is optional, although it is highly recommended. They are put at pakXXX/tool/<script_name>/ . Attached pak128.zip has this directory structure, where script_names are test_tool and test_two_click.

Please note that script/tool_base.nut at the simutrans executable directory must be placed to make tools work properly. The code patch contains this file tool.

The code below is a sample of description.tab.

title=tool for test

  • title: The title of this scripted tool. It is used as the tooltip text.
  • type: It defines the tool type. one_click means one click tool, and two_click means two click tool. The default is one_click.
  • restart: restart=1 means the tool always reloads the script when the tool is exited. If restart=0, the tool vm is not disposed and the state of the tool is preserved until simutrans is terminated.
  • menu: The key to call this tool in menuconf.tab. The value does inot/i have to be unique across scripted tool definitions.
  • icon: It defines the cursor and icon image. For this example, cursor image is image0 of cursor.one_click_test.pak, and icon image is image1 of that pak.


How to call the scripted toolslink

There are two ways to call scripted tools. The first one is using the script loading window, which is assigned to dialog_tool34. When the tool is called with this dialog, the script is always reloaded regardless of “restart” value which is defined in description.tab.

The second way is using toolbars. The toolbar definition in menuconf.tab is required. For example, adding


in menuconf.tab shows all scripted tools whose “menu” value is “my_script” at toolbar410. Please note that “icon” value needs to be properly set to show the designated icon of the scripted tools.


Script interfaces for scripted toolslink

When “type” value is one_click, the tool is one click mode and following interfaces are available. The meaning of arguments and return values are same as those of the c++ code.

  • bool init (player_x player)
  • bool exit (player_x player)
  • string work (player_x player, coord3d pos)
  • string check_pos (player_x player, coord3d pos)

When “type” value is two_click, the tool is two click mode and following interfaces are available. The meaning of arguments and return values are same as those of the c++ code.

  • int is_valid_pos (player_x player, coord3d pos, coord3d start)
  • string do_work (player_x player, coord3d start, coord3d end)
  • void mark_tiles (player_x, player, coord3d start, coord3d end)

These functions are called when the scripted tool is launched, exited, clicked, and so on. Implementing any of these functions is optional.


Known issueslink

  • is_valid_pos() cannot return error messages. It can only return state number.


Rate this page:

Contributors to this page: Andarix .
Page last modified on Sunday December 20, 2020 18:14:13 CET by Andarix.

Online Users

17 online users

Newest Forum Posts

No records to display