here is code.

    spawnParams = {
        type = '3DText',
        position          = {x=0, y=3, z=-5},
        rotation          = {x=0, y=90, z=0},
        scale             = {x=2, y=2, z=2},
        sound             = false,
        snap_to_grid      = true,
        callback_function = function(obj) spawn_callback(obj, "Bear", "Green") end
    }
    spawnObject(spawnParams)

function spawn_callback(object_spawned, name, color)
    object_spawned.setName(name)
    object_spawned.setColorTint(color)
end

when type = '3DText', cannot trigger callback correctly.
however, when type = "rpg_BEAR" or other something, can trigger callback.
I don't know why.

The example for getSnapPoints assigns to snapPointList but logs snapPointsList. Note the difference in pluralization. (Also, local should be used!)

In the 'Introduction' section of the documentation, the following description of GUIDs is given:

a GUID is a unique 6-character string

Source: https://api.tabletopsimulator.com/intro/#guid

In practice, all GUIDs I encounter are unsigned, 24-bit hexadecimal values that just happen to be stored as strings. They always pass the regex /[0-9a-f]*/ and never contain any other characters besides the hex digits zero thru 'f'.

Is this an important fact?

For a variety of reasons, I find myself editing and re-writing TTS save files to give things new GUIDs and my practice has always been to ensure they are unique hexadecimal values in the range [0 ffffff]. Is there any reason that I couldn't be throwing in ANY string with any unicode characters in it? If the value isn't a hex value does this matter to TTS?

Suggestion

It might be nice to update the documentation to acknowledge the fact that GUIDs certainly LOOK like hex values (and I'd wager they are, that this is how TTS ensures they are unique) and then explain weather or not this matters. Unacknowledged patterns like this are far too tempting to follow so I would encourage saying SOMETHING about it in the GUID paragraph mentioned above.

Why mess with GUIDs

Why, you may ask, do I need to do rewrite TTS save files and fix non-unique IDs? Well, objects in containers (like cards in decks) often have invalid GUIDs. As far as I'm concerned, any variable named 'GUID' should adhere to the rules of globally unique identifiers and if they don't they are invalid. This leads to a MOUNTAIN of difficulties when you are trying to do things with objects in containers in your scripting, especially if the game you are scripting makes heavy use of cards. The comment at the documentation about GUIDs linked above even talks about this problem and links to a scripting tool that tries to fix the problem.

After spending countless hours trying to both exploit and then eventually fix this problem, I have decided that the only sane thing to do is to FIX it. I have written my own node.js program that will read and REPAIR a TTS json save file and make all the card GUIDs unique (including the ones that are in decks). Trying to associate metadata with cards or generally manage cards in a game when their ID might change during gameplay (e.g. when they are drawn from a deck and spawn into the world) is folly! Don't do it.

I went through most pages of the API and wrote down any "issues" I could see. I talked to benjamin_dobell and he said I should make a couple issues here instead of pull requests to avoid merge conflicts.

/events/#default-events-global-object

• onBlindfold(player, blindfolded) is undocumented
• onload: should this be documented as deprecated?
• onObjectLeaveScriptingZone: enter_object -> leave_object
• onObjectPeek: “Called when a player using peek to look under an object” sounds weird
• onObjectPeek: consistency player->player_color in function handle
• onObjectSearchStart/End: consistency obj->searched_object or object
• onObjectStateChange(object, old_guid) is undocumented
• onPlayerTurnEnd is undocumented (also deprecated I think so it makes sense)
• onPlayerTurnStart is undocumented (also deprecated I think so it makes sense)
• tryObjectRandomize(object, player_color) is undocumented

/events/#default-events-object-only

• onDestroy, onDrop, onPageChange, onPickUp: anObject -> this Object
• filter/tryObjectEnter obj->enter_object: consistency with tryObjectEnterContainer
• onPeek: “Called when a player using peek to look under an object” sounds weird
• onStateChange(old_guid) is undocumented
• tryRandomize(player_color) is undocumented

/events/#function-details-global-object

• tryObjectEnterContainer is out of order from what's listed in the table
• tryObjectEnterContainer: info box says tryObjectEnter
• onObjectFlick: description says flicks twice
• onObjectFlick: info box is broken
• onObjectFlick: info box says onFlick
• onObjectLeaveScriptingZone: info box enter_object->leave_object
• onObjectPeek: “Called when a player using peek to look under an object” sounds weird
• onObjectPeek: consistency player->player_color and “Name of player color that” -> “Player color of the player who”
• onObjectRandomize: info box spawn_object->randomize_object
• onObjectSearchStart/End: info box description feels incomplete
• onSave: JSON doesn’t link to the correct place
• onSave: info box Save & Apply -> Save & Play

/events/#function-details-object-only

• tryObjectEnter is out of order from what's listed in the table
• tryObjectEnter: consistency info box obj->enter_object
• onDrop: is “This doesn’t work in Global.” necessary or should it be on all functions
• onDrop: info box description feels incomplete
• onFlick: info box is broken
• onPeek: “Called when a player using peek to look under an object” sounds weird
• onPeek: consistency player->player_color and “Name of player color that” -> “Player color of the player who”
• onPeek: an Object -> this Object
• onPickUp: info box description feels incomplete
• onPickUp: an Object -> this Object
• onRandomize: an Object -> this Object
• onSearchStart/End: info box description feels incomplete

The documentation on page: https://api.tabletopsimulator.com/intro/ has lists of links links to documentation on Object Classes and Static Classes.

Each link is broken, because it is pointing /intro/<classname> rather than /<classname>.

E.g. the link to Clock is https://api.tabletopsimulator.com/intro/clock rather than the correct link: https://api.tabletopsimulator.com/clock

(Seems trivial to fix, but I haven't even decided to installed the TableTop Simulator as a player, let alone start forking repositories, so I will leave it to someone else.)

According to the documentation, Base.group() "returns an object reference to the deck/stack formed." However, it looks like it's instead returning an empty table. I could loop over the objects on the table to find the deck since there's only one, but that seems kind of silly when I just created the deck in the line above it.

V 12.14.2 was released on 5/25/2020 and lists some new functions in its patch notes that are not yet documented (as far as I can tell):

• Object.getData(): the same thing as getJson() except it works with Lua tables so you don't have to convert to/from JSON
• spawnObjectData(): Similar to spawnObjectJSON(), example spawnObjectData({ data = Object.GetData()})

I am in no position to document these myself but I'm very intrigued by them and I wanted to put it on the radar here to see if someone can offer up official documentation beyond the simplistic mention in the patch notes. I would much rather get the official word than spend time reverse engineering them! ;-)

this happens with a normal toggle button inside of a vertical layout for me.
<Toggle isOn="true" text="Core Set" id = "Core" onValueChanged = "toggleTest"
If you have two players (P1 and P2) and P1 clicks the toggle on his screen turning it to unchecked and runs the onValueChanged function it does not uncheck for P2 thus allowing P2 to uncheck the toggle on their screen running the onValueChanged function again. IDK if this is a bug or a feature because if i add something like
function toggleTest(player,bool,id)
if bool == "False" then
UI.setAttribute(id, "isOn", false)
elseif bool == "True" then
UI.setAttribute(id, "isOn", true)
end
it then updates the toggle for everyone when one person clicks it. Figured I would report it just in case.

Xml on card objects blocks picking up the card, but will not trigger event attributes when interacted with if the card is selectable.

Test Script:

--Card XML
function onLoad(sd)
  flip = -1  -- 1 is face up, -1 is face down.
  scaler = {x=1,y=1,z=1}--o.getScale()
  zpos = -26*flip*scaler.z
  --Cards have always had weird up and foward vectors, making decals and xml function weird.
--]]..tostring(90-90*flip)..[[
  card_xml = [[                                                                             
  <Panel id="Encoder_Card" version='0' active="true" position="0 0 ]]..zpos..[[" rotation="180 0 0">
    <Button id="PropButt" 
      onClick="]]..self.guid..[[/buttonClick(PropList)" 
      position="-104 0 0" 
      width='10' height='300' 
      colors='Black|Grey|White|Red'
      raycastTarget='True'>Properties</Button>
    <Panel id="PropList"  visibility='Safety' position="140 10 0" width="60" height="290" color="rgba(1 1 1 0.5)">
    </Panel>
  </Panel>]]
  Wait.frames(function() self.UI.setXml(card_xml) end, 1)
end
  
function buttonClick(p,val,id)
  print(id..":"..val..":"..p.color)
  if id == 'PropButt' then
    toggleVisibility(val,p.color)
  end 
end

function toggleVisibility(id,pl)
  --XML helper function, takes xml id and player color
  colors, count = string.gsub(self.UI.getAttribute(id,"visibility"),"|?"..pl,"")
  colors = triml(colors,'|')
  if count > 0 then
    self.UI.setAttribute(id,"visibility",colors)
  else
    if colors == "" then
      self.UI.setAttribute(id,"visibility","Safety|"..pl)
    else
      self.UI.setAttribute(id,"visibility",colors.."|"..pl)
    end
  end
  --print(id..':'..self.UI.getAttribute(id,"visibility"))
end
function triml(s,c)
  return string.gsub(s,"^"..c.."*","")
end

--There is a tiny sliver of button that can be clicked without highlighting the card behind it that will function.

Not sure if this is a bug or a feature request, but the filterObjectEnterContainer event does not fire for chip stacks. This seems to be the only container event not fired on chip stacks.

That would be an enhancement (or bug fix) that I would like to see.

Apologies if there is a better place I should have posted this. I'm happy to repost elsewhere if someone has another suggestion.

If you add UI elements to a Notecard, and toggle off the Grid Projection for the card, the UI elements still show the grid on them.

For example, if you take the following UI elements and put it on a Notecard, you'll see the Grid Projection showing up on those buttons.

=========================================

<!-- Background for buttons -->
<Image width="107" height="113.4" color="#000000A0" offsetXY="4 -6.1"></Image>

<!-- Text for Totals -->
<Text width="150" height="30" offsetXY="53.4 0" fontsize="25" fontStyle="Bold" scale="0.25 0.25" rotation="0 0 270" color="#ffffff">0 / 0</Text>

<!-- Buttons on the right: Page up, up, down, and Page Down -->
<Button width="30" height="75" offsetXY="53.7 41.1" padding="2 0 0 5" fontsize="25" fontStyle="Bold" scale="0.25 0.25" tooltip="Previous Page" color="#8080ff" tooltipPosition="Right" tooltipBorderColor="#8080ff" tooltipOffset="-5">▲&#10;▲</Button>
<Button width="30" height="40" offsetXY="53.7 26.1" padding="2 0 0 5" fontsize="25" fontStyle="Bold" scale="0.25 0.25" tooltip="Up One" color="#80ffff" tooltipPosition="Right" tooltipBorderColor="#80ffff" tooltipOffset="-5">▲</Button>
<Button width="30" height="40" offsetXY="53.7 -26.1" padding="2 0 0 5" fontsize="25" fontStyle="Bold" scale="0.25 0.25" tooltip="Down One" color="#80ffff" tooltipPosition="Right" tooltipBorderColor="#80ffff" tooltipOffset="-5">▼</Button>
<Button width="30" height="75" offsetXY="53.7 -41.1" padding="2 0 0 5" fontsize="25" fontStyle="Bold" scale="0.25 0.25" tooltip="Next Page" color="#8080ff" tooltipPosition="Right" tooltipBorderColor="#8080ff" tooltipOffset="-5">▼&#10;▼</Button>

<!-- Buttons on the bottom: Load, Move, Alert, and Next -->
<Button width="120" height="50" offsetXY="-35.5 -56.25" fontsize="22" fontStyle="Bold" scale="0.25 0.25" tooltip="Load Information" colors="#ffffff|#cc0000|#00cc00|#0000cc" tooltipPosition="Below" tooltipOffset="-5" tooltipBorderColor="#ffffff" id="TestButton" grid_projection="false">Load Information</Button>
<Button width="75" height="50" offsetXY="-5 -56.25" fontsize="22" fontStyle="Bold" scale="0.25 0.25" tooltip="Reorder this item" color="#ffffff" tooltipPosition="Below" tooltipOffset="-5" id="bMove" tooltipBorderColor="#ffffff">Move</Button>
<Button width="75" height="50" offsetXY="15 -56.25" fontsize="22" fontStyle="Bold" scale="0.25 0.25" tooltip="Send message" color="#ffffff" tooltipPosition="Below" tooltipOffset="-5" tooltipBorderColor="#ffffff">Alert</Button>
<Button width="75" height="50" offsetXY="41 -56.25" fontsize="22" fontStyle="Bold" scale="0.25 0.25" tooltip="Move item and send a message" color="#ffffff" tooltipPosition="Below" tooltipOffset="-5" tooltipBorderColor="#ffffff">Next</Button>

cannot click any button/link in ingame tablet view when using vr

The new LayoutZone (added in v13.0) needs some documentation for Lua API interaction. I'm just an average joe so I don't know how it works but I wanted to add this here so it's known and make it a place that others might find and could add info to.

Some Reverse Engineering

Spawnable with spawnObject({ type="LayoutZone" }) and appropriate location, rotation, and scale

You can also spawn one with spawnObjectJSON. Check out a saved game with a layout zone in it (or use getJSON() on an existing layout zone) to see what one looks like. Minimal JSON seems to be something like this:

{
  "Name": "LayoutZone",
  "Transform": {
    "posX": 0.0, "posY": 0.0, "posZ": 0.0,
    "rotX": 0.0, "rotY": 0.0, "rotZ": 0.0,
    "scaleX": 1.0, "scaleY": 1.0, "scaleZ": 1.0
  },
  "LayoutZone": {
    "Options": {
      "Direction": 0,
      "MeldDirection": 0,
      "NewObjectFacing": 1,
      "TriggerForFaceUp": true,
      "TriggerForFaceDown": true,
      "TriggerForNonCards": false,
      "AllowSwapping": true,
      "MaxObjectsPerNewGroup": 13,
      "MaxObjectsPerGroup": 0,
      "MeldSort": 3,
      "MeldReverseSort": false,
      "MeldSortExisting": false,
      "StickyCards": false,
      "HorizonalSpread": 0.0,
      "VerticalSpread": 0.0,
      "HorizontalGroupPadding": 1.0,
      "VerticalGroupPadding": 1.0,
      "SplitAddedDecks": true,
      "CombineIntoDecks": false,
      "CardsPerDeck": 0,
      "AlternateDirection": false,
      "Randomize": false,
      "InstantRefill": false,
      "ManualOnly": false
    }
  }
}

returns string XML.encode(table)
returns table XML.decode(string)

Please add these utility functions. Currently am having to mess around with spawning an object, setting the xml string or table in the callback, wait a frame and then call the alternate xml get, just to convert a xml table to string and vice-versa.

Documentation lists highlightedSprite, pressedSprite, etc, but no "sprite" attribute for the base state.

Hello,

About this documentation:
https://github.com/Berserk-Games/Tabletop-Simulator-API/blob/master/docs/event.md

Why onSearchEnd is for "first searches"
And onSearchStart is for "finishes searching" ?

I went through most pages of the API and wrote down any "issues" I could see. I talked to benjamin_dobell and he said I should make a couple issues here instead of pull requests to avoid merge conflicts.

/color

• “Vector and Color are the first classes to be defined in pure Lua. This means you have to use colon operator”: is this still true? Color.setAt(col, “g”, 1) works
• Color.fromHex: I believe this should fix the issue where alpha is not optional and then this can be re-added to the api. For now could just say alpha is required.

/color/#colorblue

• Is the 2 return values still true? I tried the example and name was nil

/color#dump

• Is the 2 return values still true? I tried the example and I couldn’t replicate

/color/#colorlist

• Using => instead of = may be misleading (unless this is syntax I am unaware of)

/color/#coloradd

• Info box says dump instead of Add

/vector

• “Vector and Color are the first classes to be defined in pure Lua. This means you have to use colon operator”: is this still true?

/vector#methods-summary

• Should self in the info box link to types.md or should the return values in the table not link since types.md doesn’t say anything about self or should all selfs link to the box that explains self?

/vector#methods-not-modifying-self

• OrthoNormalize: guranteed -> guaranteed

/vector/#element-access-details

• setAt/set: Should the return tags use self instead of vector?

/vector/#methods-details

• all functions: "and returning self" -> "and returns self"
• sub: info box “to subtracts” -> “to subtract from self”
• scale: info box “The vector to scale”->”The vector to scale by” or something to make it more clear otherVec won't be changed.
• project: info box “The normal vector.” This is not the normal vector that would be perpendicular and the projection would always be 0.

/vector/#methods-not-modifying-self-details

• equals: based on this the default margin is actually 0.001 which makes the example make more sense as currently it is by making the margin smaller they are considered equal.
• string: is the 2 return values still true I can’t replicate it with the examples
• lerp: The value returned is (b-a)*t+a not (b-a)*t
• orthoNormalize: in description it says binormalPlaner in info box it says binormalPlanar

The end result is that it cannot be referred to in Lua code, and any attempts at doing so errors out the script with Error in script [...]: unexpected symbol near 'repeat'.

Can we get a function that returns a players cursor world position converted to screen coords for use with XML; or a function that returns the players current Camera transform.

I went through most pages of the API and wrote down any "issues" I could see. I talked to benjamin_dobell and he said I should make a couple issues here instead of pull requests to avoid merge conflicts.

/object/#transform-functions

• getNearestPointFromObject(other_object) is undocumented
• getNearestPointFromPosition(position) is undocumented

/object/#action-function

• #action-function -> #action-functions
• randomize: consistency color->player_color

/object/#component-functions

• getChildren: return table links to ../types.md which doesn’t exist
• getComponentsInChildren: return table links to ../types.md which doesn’t exist

/object/#global-function

• #global-function -> #global-functions
• setTable: func_name -> table_name
• setVar: func_name -> var_name

/object/#transform-function-details

• should getBounds/getBoundsNormalized say they return a table of vectors instead of a table of tables?

/object/#action-function-details

• unregisterCollisions has 3 dots like it has params but it doesn’t afaik
• unregisterCollisions: info box is empty (pointless)

/object/#hide-function-details

• All functions have the same consistency issues
• (color_name) -> color_name (or player_color preferably)
• Strings of the color name of each player. -> Player colors of the players the object should be hidden from. (or something similar)
• If this is a typo in the API it should be fixed

/object/#global-function-details

• call: should it mention that you can send other things than tables as long as it is a single value? If so then it should mention this
• getDecals: position and rotation params say they are related to the object, are they not related to the image?
• getSnapPoints: consistency, no other function lists its return like this, probably should look like setSnapPoints instead
• setDecals: position and rotation params say they are related to the object, are they not related to the image?

Lua WebRequest:
post(string url, string data, Closure callback)
head(string url, Closure callback)
delete(string url, Closure callback)
WebRequest Members:
response_code
getResponseHeader(string name)
getResponseHeaders()

https://steamcommunity.com/app/286160/eventcomments/1634166237646887286/?ctp=5#c1649918688131721450

onPlayerTurn() fires when Turns.enable is set to true and when Turns.turn_color is set. But if you have a single player seated and that player clicks the turn button at the screen’s top, the event does not fire.

Also reported as https://tabletopsimulator.nolt.io/318

Added in this update:
https://steamcommunity.com/games/TabletopSimulator/announcements/detail/3535809451399020344

The docs for Dropdown claim they have a 'text' attribute that can read the currently selected value from the dropdown.

Either I'm terrible or this documentation is wrong. The description for this field looks like an accidental copy/paste from the InputField.text attribute and the corresponding Unity docs don't mention this either.

1. Does this attribute actually exist?
2. If not, is there any way currently to read the value from a Dropdown, or is handling the event the only option?

i use scripting zone to and getObjectFromGUID to get object.it works when have two or more card ,but if there is only one card in scripting zone ,getObjectFromGUID get nil

I'm trying to start a community project which contains a TTS mod as part of it's output. I've figured out how to build the save file, I determined that the tts saves are actually BSON, and I successfully created a mod using steamcmd. I can't figure out how to update one though. Ideally this would also not require steamcmd since 2faed account are painful in steamcmd

held_position_offset
held_rotation_offset
held_spin_index
held_flip_index
held_reduce_force

All fields for Object

Custom pdfs lack documentation on how to get/set current page and get book length.

As mentioned in the title, the API always returns '1' on Grid.snapping, even if it's set to "center" or "both".

BR Dennis

The onPlayerTurn() function description says the function executes at the end of the player's turn, when it should say it executes at the beginning.

The returned object is also listed incorrectly. It says it will return a string player_color, however it actually returns a reference to the Player. As such the example should also be updated to read as follows:

function onPlayerTurn(player)
    print(player.color .. "'s turn starts now.")
end

Also, I know this repo is only for the documentation, but I also have found a bug in the Turns.getPreviousTurnColor() function. It only returns an empty string, whereas Turns.getNextTurnColor() works as expected. I'll report it on the forums if you want this duplicated over there, but it seems like it'll probably be an easy fix.

https://api.tabletopsimulator.com/event/#onobjectdrop
According to the above documentation, the method signature of onObjectDrop is "onObjectDrop(dropped_object, player_color)"

During debugging, I found that dropped_object and player_color are in the wrong position. For example, running

function onObjectDrop(dropped_object, player_color)
   print(dropped_object)
end

will print "white". Because player is passed into dropped_object. I think they're in the wrong position.

function onObjectDrop(dropped_object, player_color)

should be

function onObjectDrop(player_color, dropped_object)

According the doc:
index: Index of which Object to deal from a container.
Optional, defaults to 0. If not supplied it will deal in regular order.

So is this mean that if index = 5 I will take the fifth card from the deck?

The result ingame is to put the first card in the fifth hand of the player

While not recommended to use, information on deprecated features should remain available on the API, but clearly marked as such. An incomplete list of deprecated features:

• Timer
• filterObjectEnter/filterObjectEnterContainer
• Object.tag
• onload

https://api.tabletopsimulator.com/ui/layoutgrouping/#tablelayout

I'm trying to get a image as background on a TableLayout row, from the docs:

rowBackgroundImage | Image to use as the background for each row. | string

The attribute takes a string value but it doesn't specify where it should point.

I've added a image in the UI Assets and called it test. When I create a image element I can see the image:

{
  tag="Image",
  attributes={
    image="test"
  }
},

I was hoping I could point rowBackGroundImage to that same test asset:

  UI.setXmlTable({
    {
      tag="TableLayout",
      attributes={
        rowBackgroundImage="test"
      },

But that doesn't work. Nothing is happening.

I figured out that cellBackgroundImage="test", does when put on a TableLayout tag, but not on a cell tag with the dontUseTableCellBackground=true, attribute set:

      tag="TableLayout",
      attributes={
      },
      children={
        {
          tag="Row",
          attributes={
            childForceExpandWidth=false,
          },
          children={
            {
              tag="Cell",
              attributes={
                cellBackgroundImage="test",
                dontUseTableCellBackground=true,
              },
              children={
                {
                  tag="Text",
                  attributes={
                    fontSize=15,
                    color="white",
                    text="X"
                  },
                },

The documentation pertaining to onSave shows the value manually being set on an Object's script_state:

https://github.com/Berserk-Games/Tabletop-Simulator-API/blame/master/docs/event.md#L467

The documentation for onLoad includes example code that also shows onSave in use. However, it indicates that a string should be returned, rather than setting the script_state property directly on the Object:

https://github.com/Berserk-Games/Tabletop-Simulator-API/blame/master/docs/event.md#L149

Which is correct?

I'd be inclined think saving state via return value makes more sense, particularly if the object is about to be destroyed, it gives you guys flexibility with your engine internals. However, that's just a guess.

Actually, most of the documentation seems to be missing return values. If we could get types added in a similar fashion to how it's indicated for parameters then that would be a huge help. I'd happily submit PRs myself, however I'm new to TTS and genuinely don't know the expected return values. EDIT: Worked out there's only two methods with return values, PR submitted.