This section forms a reference document that describes every defined network command in Verse. For each command, it's complete network representation is given, and all included parameters are described. Also described is the command's semantics, of course.
There are two categories of network commands: system and node commands. System commands are sent to the host itself, and are used to manage connections, and other administrative things. Node commands are sent to actual node instances, and are used to describe the data contents.
As noted earlier, Verse commands are used both between client and host to request something, and then in the reply from host to client to authoritatively state something. Often the thing that is stated, the host's response, is the exact same thing that was requested but with one or more values filled in that only the host knows about.
The descriptive texts for the commands in the following sections are written from the client's perspective almost always. This means that e.g. the g_vertex_set_xyz_real32 command is described as "setting the position of the vertex", rather than "informing a client about the position of a vertex", and so on.
This distinction is sometimes subtle, and well worth remembering when reading the command descriptions.
All node commands contain an absolute "address", in the form of node-dependent hierarchical ID numbers, of the data being read or written. Most such node commands can be executed in any order, which makes the protocol as a whole fairly free of command dependencies and the associated latencies. Because of the addressing, most commands can also be executed multiple times without any harmful side effects except (possibly) excessive network traffic. This latter property is sometimes referred to by saying that the commands are idempotent.
While most commands are order-independent and idempotent, some commands can not be. For these commands, there is a special transmission mode called "ordered". Ordered commands must be delivered to the receiving application in the order sent. This introduces latency, but is the only acceptable way to deal with certain kinds of data.
One area of interest is the distinction between commands that create something, and those that merely set something. This distinction is not very clear-cut, and the command naming is in some cases historical or traditional.
In general, commands have addresses. It might make sense to just look at the address when classifying (if such classification is even necessary) a command as a create or a set:
If the address points to something that is unknown, it is a request to create a new instance of whatever type is relevant.
If, on the other hand, the addressed item exists, it should be re-set according to the rest of the parameters in the command.
There are some specific cases where it might be valuable with some discussion about why the commands have been named the way they have:
This is perhaps one of the more clear-cut command names. It is not possible to create an individual bitmap tile; all tiles are implicitly "created" as soon as the bitmap's dimensions are set (using b_dimensions_set).
Again, this is fairly clear-cut. There is no addressing involved; each object node has exactly one "slot" that can be used to store light values, and this command always sets precisely those values.
These commands (all the g_vertex_set_ and g_polygon_set variants) are perhaps a bit dubious, as they obviously can both create and change (set) the value of a vertex (or polygon) definition. One possible way to justify the naming is that individual vertices and polygons are not subscribable objects, they are lower-level, "second class citizens" if you will. Often, the naming leans towards setting un-subscribable objects with "set", while the higher-level, subscribable, entities are set using a "create"-command.
Another aspect with the geometry data is that is really meant to be stored in an array, with the "id" of a vertex (or polygon) being simply its index in that array. This makes it simpler, and thus less worthy of a "create" command, perhaps.
This command, perhaps, is the exception that proves the rule given above. Bones are not subscribable entities, yet they are created (or modified) by a command named "create". One explanation here might be that bones contain references to each other, for hierarchy, so the numerical identifiers used to address them have slightly more significance than the plain indexes used with vertex and polygon data.
Verse data transmissions can never be known to be "complete", since even if your particular client is a passive receiver only, you can never be sure that there isn't some other client connected that is adding, editing, or deleting data.
This means clients can rarely be designed with some kind of hard separation into stages; i.e. you can't say "first I download the geometry, then I...", because there is no way of knowing when e.g. the geometry has been "fully" downloaded. Indeed, the concept isn't even defined since it can change at any moment.
This property means that any processing (for instance subdivision of geometry for rendering as triangles) done on Verse data needs to be able to restart when data changes, and be ready to do so at any time.