Jabber-RPC

As much as possible, Volity uses the Jabber protocol -- both its core XMPP and several standard extensions. Many key activities are so specific to game-playing, though, that Volity components need their own command set, defining game-related functions they can call on one another. These commands are made possible through Jabber-RPC, a JEP-defined protocol that allows some entity on a Jabber network to call a function on another, and receive a return value (or an error message) back from it.

Jabber-RPC is defined in [JEP-0009] of the full Jabber protocol. Since it's the only kind of remote procedure calling that happens in the context of Volity, we often refer to it as simply "RPC".

Numeric Data Types

Jabber-RPC specifies two numeric types which can be used (in RPC method arguments or in replies): <int> (aka <i4>), and <double>.

However, for the foreseeable future, Volity clients all use ECMAScript as their internal scripting language. That is, RPCs are received and sent out by ECMAScript functions embedded in the UI file.

The funny angle here is that ECMAScript does not distinguish integer from floating-point numeric types. It is therefore possible that a client will send a <double> Jabber-RPC value even when the numeric value is a whole number. (In fact, Gamut always does this, for RPCs in the game namespace.)

Therefore, any Volity entity (referee or bookkeeper) which communicates with a client must be prepared to accept <double> values in this way.

How Jabber-RPC is used within Volity

Jabber-RPC activity within Volity happens in two distinct varieties.

Game-specific

All official game-level communication between a player and a referee happens over RPC. Each ruleset defines the functions that a referee playing its game might expect to receive from a player, as well as the functions that a player might get from a referee. For example, the rock, paper, scissors ruleset defines a player-to-referee "select" method, used to specify which hand to throw.

(I put official in scare-quotes because it's quite possible for unofficial communication to happen between a ref and a player, such as over standard Jabber messaging. However, the Volity protocol defines that any information relevant to the game must occur over RPC.)

These game-specific RPC functions happen in the game namespace, which is prepended to the function name. So, if a client wishes to call the ruleset's "draw_card" function on the referee, it will actually send a game.draw_card function.

System-level

Volity defines a small set of commands necessary to set up and start games. Unlike the game-specific RPC requests, which differ by ruleset, these system-level requests are rigidly defined, and work the same no matter what game they might apply to.

These function all occur in the volity namespace. Examples include volity.new_table, sent from a player to a parlor in order to request that it create a new game table, and volity.add_bot, which requests that the receiving referee create a new bot player and seat it at the tabe. See RPC requests for a list of these requests.