ThereScript

ThereScript is a language used to add scripting to objects. The most visible places where ThereScript appears are in TsFiles and AconfFiles downloaded to the ThereClient to set parameters for specific objects. For example, each designer add-on kit object is associated with a TsFile that sets such attributes as one-sided or two-sided for each material in the object.

Speculation: ThereScript is Lua, described as “a powerful light-weight programming language designed for extending applications”. The current version of Lua is 5.0; you can read the reference manual on-line. Lua is free software. I have done some comparisons between the Lua reference manual and some example files, and it seems to correspond very closely. What this means is that if you want to process ThereScript files, you can download Lua and bind it into your own (C) applications. -- IanYoung

My intention is to try and waffle about the grammar of ThereScript here, inasmuch as I can guess what it might be. I think it makes sense to separate this from the pages for TsFiles and AconfFiles, where we can instead restrict discussion to the particular uses of ThereScript. -- IanYoung

Here is an example TsFile for a designer object, specifically Resources\gamekit\epobs\fu\92552851.ts (my own free-standing picture add-on):

PIECE
{
  name = "Winter Trees, Livingston",
  id = "dev92552851",
  model = "fl/92552851.model",
  modelSettings = {
  [ "pic" ] = {
    colormap = "fl/92552851_1.jpg",
    lit = 0,
    twosided = 0,
  },
  [ "frame" ] = {
    colormap = "fl/92552851_2.jpg",
    lit = 0,
    twosided = 0,
  },
  [ "tape" ] = {
    colormap = "fl/92552851_3.jpg",
    lit = 1,
    twosided = 0,
  },
  [ "back" ] = {
    colormap = "fl/92552851_4.jpg",
    lit = 1,
    twosided = 0,
  },
},
  layoutClass = "Structures",
  sinkToGround = dropOnTop,
}

CONTENTS
{
  { "dev92552851", 1 },
}

What I read into this is as follows:

• Identifiers, integer constants and string constants are what you’d expect.
• The basic operation seems to be the construction of what looks like an associative array or map, which is to say a collection of named values. An array is specified by the ‘{‘ and ‘}’ characters, and within that we have a sequence of name = value pairs separated by commas (but also allowing an ignored trailing comma for ease of machine generation).
• The ‘[’ and ‘]’ characters are used to make an arbitrary string constant value into an identifier for a map. This is kind of similar to its use in some database languages. In this example file it wasn’t required, but material names can have funny characters like ‘#’ in them so it is probably there for safety’s sake.
• Certain identifiers in a value context represent constants imported from somewhere else. dropOnTop is an example of this. My guess would be that the validity of such identifiers isn’t truly global but depends on the context in which the ThereScript is imported.
• You can nest arrays as values within other arrays.
• PIECE is followed by an array specification.
• CONTENTS works slightly differently, obviously, and it isn’t so obvious how to map this second syntax onto the first. It may be that missing out the name = part of the syntax simply gives an integer indexed array instead of an associative (string-named) map. This would be like PHP, for example.

This seems to explain everything in the above TsFile. My next step will to formalise that as an Antlr grammar and try verifying that all TsFiles in my client installation match such a grammar.

20040423: The capitalised words PIECE and CONTENTS look to me like they are actually in-line function calls to functions defined in the file \gamekit\gamekitsystem.ts. There also seems to be some relevant code in gamekit\gamekitframework.rs which includes the former. Speculation: these files are the context in which the add-on kit TsFiles are executed.

Some other observation from the gamekit framework files:

• Variables have the value nil until a value is assigned to them.
• Comparison operators: ==, ~=
• String concatenation operator: ..
• Sequential operators: or
• Unary operators: not, ~, -
• Table iteration: for name,entry in t do … end
• Functions: function name(args) … end
• One statement per line.
• Table index by name: table["name"] or table.name
• Function locals: local fred = value
• Variables are untyped, values can be integer, string or table
• return statement has optional value
• Comments start with -- to end of line
• Assert(boolean)
• Require(string)
• Log(integer, string) or Log(string)
• nil in boolean context means false
• isTable(x) is just (typeof(x) == “table”)
• The function isDefaultPieceForLayout returns NIL rather than nil at one point. This might mean:
  • The language is not case sensitive
  • The word nil is not case sensitive but other words are
  • The programmer made a mistake, but because undefined variables have the value nil anyway, no harm is done.
• if boolean then … end
• Sometimes, statements have ; at the end, but usually not.
• The array passed to CONTENTS is indeed integer indexed. It looks like integer indices start from 1.