The UI Finder is a system of of service discovery ("parlor.html" class=wikipagelink>parlors that help clients find UI files for games they wish to play.
This documentation assumes knowledge of the shape and function of disco items and info requests and responses.
Before the client can ask the bookkeeper about some ruleset's UI files, it must first have that ruleset's URI in hand. If it doesn't already have this URI, it can obtain it from the parlor to which its user wishes to connect.
To do this, the client sends a disco info request to the parlor. The resulting disco information will include a jabber data form (as allowed by Jabber JEP-0128), which will contain the following relevant fields (as well as a few others:
Once the ruleset URI is in hand, the client can follow up with some disco queries to the bookkeeper. First, it can get a list of all the available UI files for that ruleset. It sends a disco items request to the bookkeeper, with a node matching the ruleset URI, suffixed with "rock,_paper,_scissors.html" class=wikipagelink>rock, paper, scissors UI files, it sends a disco info request to bookkeeper@volity.net/volity, node http://volity.org/games/rps|uis.
Each item returned will represent a single UI file that the bookkeeper knows about, located somewhere on the public Internet and accessible by URL. Indeed, each item is simply a pointer to another node in the bookkeeper's disco network, with a node matching the file's URL. The client can then send disco info requests to each of these nodes, receiving a response in every case of another [data form]? describing the file. It will contain the following pertinent fields:
Upon receipt of all these file-describing forms, a client should initially narrow down the candidates by tossing out all files whose "client-type" values don't match the client's own type.
If the number of choices remaining number one or zero, the client's next action should be pretty clear -- either silently download and use the file, or display an apologetic message to the user, respectively. If more than one file is available, though, it becomes less obvious what a client should do. Two of the many possible user-interface paths it could take include displaying a dialog to the user that lists the possible files and prompts to choose one, or downloading the one with the highest reputation and then allowing the player to manually choose a different UI file through a separate command.
Once it has selected a single file to download, a client should be able to simply fetch the file at its stated URL via HTTP. It will be in one of two formats:
main.
In either case, the end result will be a single file suitable for immediate feeding to the client's UI interpreter. The nature and format of this file will differ according to the client type. Text clients will end up with a simple ECMAScript file, for example, while SVG clients will have an SVG file. In this latter case, the file may (an indeed probably will) contain entity references pointing to external resources, allowing the UI file to load images, symbol libraries, and ECMAScript code libraries as needed.