The tools API contains methods for creating and reading properties of custom tools and built-in tools.

"Tools" in a general sense refers to any selectable tool in the game, including elements, tools, walls, and decoration tools. If you can select it and it gets a red border around it, it's a tool, and you can read its properties with this API.

Most of the usefulness of the API comes from creating custom tools. Custom tools receive the same callbacks as everything in the Tools menu. They interact with locations the user is drawing the brush at.

Methods

tools.allocate

Create a new tool.

toolIndex = tools.allocate(group, name)

• group: string without underscores (_), the group the tool belongs to; gets uppercased by the function
• name: string without underscores (_), the internal name of the tool; gets uppercased by the function
• toolIndex: the number of the tool index allocated for this tool

group should be something unique to your script, and should be the same across the entire script. It is common to use a simpler version of your username or the script’s name. If your script has any custom elements, you should use the same group as those. You can never create custom tools in the DEFAULT group, trying to do so results in an error.

name should be unique to the tool within your script, and ideally should resemble the Name property of your tool.

The resulting tool identifier must be unique across all scripts in use at any point in time.

The new tool is created with all the default properties, and will not be visible until you modify it to show up in the menu.

tools.free

Free a previously allocated tool.

tools.free(toolIndex)

• toolIndex: tool index of the tool to be freed

This function will ONLY free custom Lua tools. Built-in tools, i.e. tools in the group DEFAULT, and custom elements from other scripts cannot be freed.

tools.property

Query or update a property of a tool.

propValue = tools.property(toolIndex, propName) -- query variant
tools.property(toolIndex, propName, propValue) -- update variant

• toolIndex: tool index of the tool whose property is to be queried or updated
• propName: string, name of the property to be queried or updated
• propValue: various types, value of the property to be queried or updated

For more information on what properties there are to use in elements.property, and how to use them, see Tool properties.

Several event callback functions are implemented, such as "Perform" and "Select". These are critical for making your tool actually do anything when used. To set these, use a function for propValue. For more info on all the callbacks, see Tool callback functions.

tools.exists

Check whether a number is a real tool index

exists = tools.exists(toolIndex)

• toolIndex: number of the tool to be checked
• exists: boolean, true if toolIndex refers to a valid tool

If a tool exists, there exists a corresponding tools.index.[group]_PT_[name] constant, and conversely, if there exists such a constant, there exists a corresponding tool.

tools.isCustom

Checks whether a number is a real tool index that refers to a custom Lua tool

custom = tools.isCustom(toolIndex)

• toolIndex: number of the tool to be checked
• custom: boolean, true if toolIndex refers to a valid tool, for a tool that was previously allocated with tools.allocate.

Constants

tools.index

A table that maps Identifiers to their tool indices.

airTool = tools.index.DEFAULT_TOOL_AIR

Tool indices are arbitrary and not guaranteed to be constant for any particular tool between versions.

The identifiers for all built-in and custom tools are in this table. The format for an Identifier depends on the type of tool. It is roughly [group]_[type]_[name], where [group] is DEFAULT for built-in tools, and [type] could be PT, TOOL, WL, or more depending on the type.

You can get an identifier by selecting it and checking ui.activeTool(0). Every selectable tool is available in tools.index for lookup.

Tool properties

Tool callback functions

TODO: Perform, Click, Drag, Draw, DrawLine, DrawRect, DrawFill, Select