The API is described by a version number. (The UI can read this version number from info.version -- see below. This may allow you to write UI code that runs on old interpreters.)
The UI should specify the API version (or versions) it requires in metadata. This allows the interpreter to sort out which UIs will run upon it.
The version number follows the version matching definition. A backwards-compatible change (such as adding a new info field or API function) will be noted by incrementing the minor version number. A compatibility-breaking change (like removing or changing the behavior of an API function) will be noted by incrementing the major version number.
This page describes API version 3.2.
A seat can be annotated with one (no more than one at a time) of the following marks. Each mark has a (string) name, which should be taken as a general guide to the mark's use.
turnwinfirstotherA call to the seatmark() function defines a new set of marks. (The state of the marks depend solely on the last seatmark() call; calls are not cumulative.) Marks are not automatically reset at the beginning or end of a game. They are reset (all unmarked) when the UI is loaded in or reloaded.
seatid gets the turn mark. All other seats become unmarked.
other is assumed.
This is a blank object. The UI must add properties to it; these are used as function handlers for the volity RPC requests which arrive from the referee.
For example, if you added a volity.start_game property, it would be called when the game started.
You do not have to assign a property for every volity RPC in the list. If a property is not found for a given RPC, then nothing happens.
Note: Earlier versions of Gamut called game.START and game.END instead of volity.start_game and volity.end_game. This old configuration still works, but it is deprecated. One day it will be withdrawn.
This is a blank object. The UI must add properties to it; these are used as function handlers for the game RPC requests which arrive from the referee.
For example, if a game.win(true) RPC arrived, the client would look up the game.win property, and call it with one boolean argument (true). If the property was not found, or if it was not a function, this would be reported as an error back to the referee.
Warning about array and struct arguments: These are translated into ECMAScript objects which act like arrays and structs; but they are not full-fledged ECMAScript arrays. You should not store these objects long-term in your UI code; read them in place and then discard them. If you need to store their information, copy it into new ECMAScript arrays.
This object contains fields holding meta-information about the table that can be useful to UI files.
Object properties:
setup, active, or suspended. (The disrupted and abandoned states are not visible to the client -- they will appear as active.)
Add the global config properties (show_table, record_games, language, kill_game)?
Your script code can call one of the following functions to extract metadata, either from itself or from one of the resource files it loads:
xml:lang attribute matches the client's language setting). If there are none, returns null.
The URI is a resource URI (see above). If null, undefined, or the empty string, this will return the metadata from the UI file itself.
The key is a label, optionally preceded by a namespace and a period. (Rather like translation tokens.) If you don't give a namespace, game. is assumed.
The namespaces for these keys are:
Note that a namespace is not the same as an XML qualifier prefix. The call
Returned by info methods. (See above.)
Seat objects may be compared by equality
Object properties:
Allows construction of audio objects. Returned by the audio() function.
What do we say about supported audio formats? AIFF and MP3 work. (MP3 by virtue of a library that Gamut includes.) I don't know what else Java can handle, or be made to handle.
Object methods:
Possible future expansion: a stopall() method? Properties to adjust volume, pitch, pan? A way to create an instance which is not yet started, so that you can adjust its properties and then start it? Pause and unpause?
Returned by an Audio object's play() method.
Unlike the Audio object, all the instance object's fields are read-only.
metadata.get(URI, "ui_file.html" class=wikipagelink>UI file as a <dc:title> element, but this is not required -- the XML could assign any prefix to the "http://purl.org/dc/elements/1.1/" namespace.
Classes
Seat
(seat1 == seat2). They evaluate as strings in expressions, so you can also test (seat1 == "seatid").
Audio
Audio Instance