search

tts-community / api

Tabletop Simulator scripting API documentation.
https://tts-community.github.io/api
9 stars 2 forks source link

spawnObject() types vs. spawnObjectJSON() names #30

Open Benjamin-Dobell opened 4 years ago

Benjamin-Dobell commented 4 years ago

In addition to resource names, spawnObject() accepts user friendly names as well:

Where as spawnObjectJSON() takes a name within the JSON i.e. object.name. The following list was obtained by spawning the above objects, however this list is non-exhaustive:

Currently the Spawn Objects documentation has the latter only. This may be confusing for users who wish to consume the simpler (albeit more constrained) spawnObject() API.

You may have noticed two things about the above lists:

  1. Despite one list being generated from the other, there are more spawnObject() "user friendly names" than there are spawnObjectJSON() names. This is because some "user friendly names" map to the same resource, but have had additional configuration changes made such that they look different.
  2. The list above is missing plenty of spawnable resource names that are already documented e.g. rpg_DARKNESS_WARLORD. That's because these objects simply don't have a "user friendly name". You must use their "resource name" instead.

The mappings between between "resource names" and "user friendly names" (as per point 1 above) are available here.

Ideally we should add something to API docs to explain all this.

Benjamin-Dobell commented 4 years ago

Just looking into this some more, and amended the above with some corrections.

Perhaps Berserk's intention is that the "user friendly names" for spawnObject() are supposed to be deprecated?

However, objects like "Pink Pawn" can't be spawned with a resource name alone, because the corresponding resource ("PlayerPawn") must have its colour set to pink (by default it's white). That means without documenting the above friendly names it's impossible to spawn a pink pawn using spawnObject(). Instead you must use spawnObjectJSON()and specify the ColorDiffuse and MaterialIndex = 7.

Basically, we should probably either document the friendly names (as they can be useful, as above), or we should mark spawnObject() as deprecated, because users may rightfully be confused about how to spawn a Pink Pawn etc.

Essentially, without this friendly name list, spawnObject() is fairly useless.