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/<sc
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 type=one_click restart=1 menu=my_script icon=one_click_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.
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.
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.
- is_valid_pos() cannot return error messages. It can only return state number.