Use the TTS Game Keys feature to select objects and group them for counting or other purposes.
 
 
This intermediate guide assumes basic knowledge of lua scripting.
 
 
A scripted game may need to count objects selected by the players, or take another action on a group of objects they select.
 
 
MrStump created a mod called the Counting Bowl that serves this purpose. When players put objects in the bowl, they are automatically counted.
 
 
But it can be awkward to move a lot of objects. And there is the matter of putting them back.
 
 
This script uses the Game Keys that are configured in-game under the Options menu. It allows the players to hover over an object and press an assigned key. The script puts that object in a table. Another function can take some action on the selected objects.
 
 

The Script

 
 

addHotkey("Name in Game Keys Menu",
 function(player, obj)
 if obj then
 onKeyPress(player, obj)
 end
 end)

SelectedObjs = { }

function onKeyPress(player, obj)
 local guid = obj.getGUID()
 if sometest == true then
 if SelectedObjs[guid] then
 obj.removeTag('Selected')
 obj.highlightOff('Red')
 SelectedObjs[guid] = nil
 else
 obj.addTag('Selected')
 obj.highlightOn('Red')
 SelectedObjs[guid] = true
 end
 end
end

function actOnSelectedObjs()
 for guid, _ in pairs(SelectedObjs) do
 local obj = getObjectFromGUID(guid)
 -- action to take on object
 obj.removeTag('Selected')
 obj.highlightOff('Red')
 end
 SelectedObjs = { }
end

 
 
 

AddHotKey()

The addHotkey() function is in the TTS API. To set up this feature, this function must be included in the onLoad() function in the Global script (it will not work if you put it somewhere else).
 
 
The first parameter sets the name that will appear for this action in-game, in the Options | Game Keys menu.
 
 
The second parameter is the function that will be called when the assigned key is pressed while the mouse is hovering over the object. You could define the entire function here, but you can also refer to a function defined elsewhere, as shown.
 
 
The addHotkey() function passes the color of the player pressing the key and a reference to the object. There are other features described in the API.
 
 
You must use the “if obj then …” test here. If not, then if the player presses the key while the mouse is not hovering over an object, TTS may throw an error.
 
 
 

OnKeyPress()

The onKeyPress() function is a function you write. It will happen when the assigned key is pressed.
 
 
In this example, the onKeyPress() function will work as a toggle. If an object has not been selected, the function will add the guid of the object to a globally defined table called SelectedObjs. (Adding the guid as the key in the table makes it easier to test whether that guid is already present). If the guid of the object is already in the table, the function will remove it from the table by making its value nil.
 
 
As shown, you could include other tests to apply before adding the object to the SelectedObjs table. You do this using an if … then test.
 
 
The script also shows how to use the Tag feature in TTS for the selected objects. And for visual flair, it highlights the selected objects in red. The tags and highlighting are optional; the function would still work without them.
 
 
 

ActOnSelectedObjs()

The actOnSelectedObjs() function is a function you write to do whatever needs to be done with the selected objects.
 
 
You could set this up in various ways. This example shows a globally-defined table that the function iterates through.
 
 
Although many say that global variables should be avoided, one is useful here. It allows the onKeyPress() function to work as a toggle.
 
 
To make this work, the script should call the actOnSelectedObjs() function only when the player has finished adding or removing objects from the selection. That way, the player can change the selection up until a certain point. When that point is reached, the action can occur on all the objects in the selection.
 
 
In this example, the table is set to empty after the action occurs. Alternatively, the table could be copied to another variable or passed to another function.
 
 
Note that because the table uses guids as the keys to the table, you must use pairs and not ipairs to iterate through the table.
 
 
 

Other Considerations

You could use the getSelectedObjects() function in the TTS API in a similar way. However, that would cause all the selected objects to be grouped for other purposes. For example, they would move around together.
 
 
The benefit of the approach here is that the selection can stay in place indefinitely, until the actOnSelectedObjs() function is called. The objects could move around or be used in other ways without changing the selection.
 
 
One point of caution is that the key assigned should not conflict with other hotkeys in the game. For example, if you assign a number key it could conflict with drawing cards from a deck. To avoid this, you could include an if … then test to not trigger the function if the object is a deck (e.g., if obj.tag == “Deck” then return end).
 
 

 
 
Hope you enjoy the Guide about Tabletop Simulator – How to Select Objects Using Game Keys, if you think we should add extra information or forget something, please let us know via comment below, and we will do our best to fix or update as soon as possible!