Tabletop Simulator – Use Description to Show Objects Beneath an Object

When a player hovers the mouse over an object, its description will update to show the names of the objects that are beneath that object.

This intermediate guide assumes basic knowledge of lua scripting.

It can be useful to know what is beneath an object, without moving the object to check. على سبيل المثال, a stack of counters in a wargame, or any other stack of tiles.

This function uses the onObjectHover() function in the TTS API. When the player hovers the mouse over an object, this function updates that object’s description to list the names of the objects underneath that object. The list is added to the end of any description that is already attached to the object.

This function calls functions from the lua string library, which includes many interesting features. You can read more about them in the string library tutorial on the lua-users wiki.

This function works best if you have a way of identifying the objects in your game, such as the Tag functions in the TTS API. أيضًا, the objects need to have names or some other information that can be added to the description.

The Function

function onObjectHover(player, obj)
  if obj and obj.hasTag("Hover") then
    local descrip  = obj.getDescription() or ''
    local start = descrip:find('stacked with')
    if start then
      descrip = descrip:sub(1, start-1)
    end
    local hitObjects = { }
    local stackObjects = { }
    local pos = obj.getPosition()
    pos.y = pos.y + 2
    hitObjects = Physics.cast({origin = pos, direction = {0,-1,0}})
    for _, hitobj in ipairs(hitObjects) do
      if obj ~= hitobj.hit_object and
        hitobj.hit_object.hasMatchingTag(obj) then
        table.insert(stackObjects, hitobj.hit_object)
      end
    end
    if #stackObjects>0 then
      if descrip ~=  '' and not descrip:endsWith('\n') then
        descrip = descrip..'\n'
      end
      descrip = descrip..'stacked with\n'
      for _, stackobj in ipairs(stackObjects) do
        local name = stackobj.getName() or ''
        descrip = descrip .. اسم .. '\n'
      end
    end
    if descrip:endsWith('\n') then
      descrip = descrip:sub(1, -2)
    end
    obj.setDescription(descrip)
  end
end

What the Function Does

The function:

• Checks that the mouse is currently hovering over an object (“if obj …”). Without this, the function may throw an error.
• Checks that the object has a certain tag. You should use some test here, because this function is probably useful for only some of the objects in your game.
• Gets the description of the object, or an empty string if the object does not have a description.
• Checks if the description contains the key phrase “stacked with”. You could use any phrase here, but the function works by checking for this key phrase, so the phrase has to be consistent, and has to be something that would not otherwise appear in an object’s description.
• If the description contains the key phrase “stacked with”, deletes that phrase and everything that comes after it. (That information will be added back later.)
• Gets the position of the object.
• Identifies every other object downwards from a point slightly above the object, and puts those objects in a table called hitObjects.
• Checks each object in hitObjects. If the object is not the first object and if the object has a tag that matches the first object, then the object is added to a table called stackObjects.
• Checks if anything is in the stackObjects table, and if so:
  adds a new line to the first object’s description (if there is already text in the description),
  adds the key phrase “stacked with” to the first object’s description, و
  gets the name of each object in stackObjects, adds it to the first object’s description, and adds a new line.
• Deletes the new line from the end of the first object’s description, إن وجدت.
• Sets the text of the first object’s description.

The String Library Functions

In brief, this is what the functions from the string library do.

start = descrip:find(‘stacked with’) checks whether a string variable, descrip, contains the phrase “stacked with”, and if so it returns the index of the beginning of that phrase. في هذه الحالة, the index is the nth letter in descrip at which the “ق” في “stacked with” appears. This number is assigned to the variable start.

descrip = descrip:sub(1, start-1) If start is not nil (أي., if the phrase “stacked with” does appear in descrip), then return a new string that includes everything in descrip up to but not including the index start. One is subtracted at the end so that the first letter of “stacked with” is not included. This new string is assigned to and replaces the variable descrip.

not descrip:endsWith(‘\n’) The endsWith() function is not in the lua string library but rather is part of the Moonsharp library that TTS uses. It returns true if a string ends with a specified phrase. هنا, it checks if descrip already has a new line at the end, before adding one.

descrip:sub(1, -2) The function sometimes ends with an extra new line at the end of the object’s description, which looks strange. لذا, if descrip ends with a new line (and nothing after), descrip:sub(1, -2) returns a new string that includes everything in descrip up to but not including the last two letters in the string (أي., ‘\n’), and assigns it to the variable descrip.

Note that lua does not delete anything from a string, but rather returns a new string that does not have what you want to delete.

Physics.cast()

This function from the TTS API returns a table of all the objects that exist in a certain area or direction. It can do many things.

هنا, it uses mainly the default parameters to cast a line downwards from the object over which the mouse is hovering. For this purpose, it helps to set the origin of the line a value of 2 above the object itself. This seems to work best to capture everything in the stack.

Physics.cast() is fully described in the TTS API reference. It probably could be used to identify objects surrounding (rather than beneath) a certain object, but this Guide is limited to lines cast downward from an object.

Note that Physics.cast() will identify every object it intercepts, including the game table and other incidental objects.

Because of this, the function checks that obj ~= hitobj.hit_object, to avoid including obj in its own description.

أيضًا, it is necessary to include some test to include only certain objects in the stackObjects table. هنا, the object is included if it has a tag that matches the first object.

استكشاف الأخطاء وإصلاحها

This function adds the names of the other objects to the first object’s description. If the objects in your game do not have names, then use some other information and replace the call to the getName() function.

This function leaves (أي., does not delete) the list of objects in the first object’s description.

This should not normally be a problem, because the description only appears when the mouse hovers over the object. And the first thing the function does (when the mouse hovers over an object in the relevant group) is to check if the description contains the key phrase “stacked with”. If so, the function deletes that phrase and anything that comes after it.

So if the mouse ever hovers over an object in the relevant group, and no relevant object is beneath it, then the function will reset the object’s description.

If this does become a problem, please leave a comment and perhaps the function can be corrected to avoid it.