last modified 2004-02-25

Framsticks Network Client/Server Specification

These applications are in development. Please contact capstone at kagi.com if you need the linux/windows server executable for testing or developing your own clients. Some clients are already available.

Framsticks Network Server is a powerful simulation engine, with all capabilities of the Framsticks command-line interface. Its application depends only on network clients, which can use the server for research, remote simulation, presentation of evolutionary processes and phenomena, distributed evolution, modeling of ecosystems and migration, real-time interaction in mixed realities, and much more.

1. Assumptions

2. Commands, data and messages flow

The server is able to support different protocols for different clients. Client must send the required protocol version using the "version" directive (currently "version 1" and "version 2" are supported). The "ok" answer means that the protocol is supported and can be used, otherwise "error" is returned. (For compatibility, the "client_v1" directive is also supported). Interactive clients could also support the "telnet" mode (which means just passing user-typed commands to the server), which exposes many internal details of the simulator and can be used even if the higher level negotiation failed.

Each object can be accessed using its path. Path sections are separated by the / char.

A command is a single line of text (which is a call of a macro, usually with parameters) ended with \n or \r\n.
After this command is executed, it is acknowledged by messages
ok [optional_text]
If the command could not be completed, the server feedback is
error [optional_error_description]
Further, the server sends event objects for the registered event sources. Handler type 0 emit events immediately, type 1 events are sent in response of "send" or "sendall" method. Both handlers use the following format:
event [eventpath] [eventname]
file
....(event data)...
eof
For some commands, the client needs to send a file (formatted in a special way, as most Framsticks files). For some commands, the server sends a file (formatted as above). The files are sent before the command execution acknowledgement "ok". This acknowledgement means that the data transmission related to the command is finished.
File sending mode is initialized by the sender, which sends the directive:
file [filename] [file_description]
The parameters are optional. From now on, data is treated as file contents, until the end-of-file marker is received. This marker is exactly three chars in a single line:
eof
If the "eof" exists in the file sent, it must be "quoted" as \eof (\eof must be quoted as \\eof etc.)
The server tells that it needs a file to complete some command by sending request
needfile [suggested_name] [file_description]

3. Commands

In examples below, the following underline convention is used:
data sent by the client to the server 
data sent by the server to the client

version

version [number]
Returns "ok" if the requested protocol version is supported or "error" otherwise.
Note: The current protocol version 2 no longer requires the [id] argument. (If you don't know what [id] is, you don't need it. The previous behavior is restored when the old protocol is negotiated - "version 1" or "client_v1").

info

info [path]
Returns information related to the object referred as "path". The result is a file with definitions of properties (objects of the "prop" class, just as can be found in many Framsticks files, like *.expdef, *.style, *.neuro, etc.)

The file may contain the name of the object's class, given as the "id" property of the object "class". This class name can be used by the client to check if the object is of known type, for example, to use specialized methods of wisualization and interaction.

If the last element of the path is a property of list type, then the result is the definition of properties of objects which the list contains. Analogously, the event class definition is returned from the event source query.
The classname is usually contained in the "l" and "e" type description ("l ClassName" and "e ClassName") so you only need to issue the info command on "l" and "e" if you need more details.

Example:

info x /
file x
class:
id:Server

prop:
id:version
name:Version
type:s
help:Server version

prop:
id:start
name:Start
type:p
help:Start simulation

eof
ok x

set

Two variants:
set [path]
(requires sending a file)
Will set properties of the object according to the file sent.
set [path] [property] [value]
Will set (only one) value - thus there is no need to send a file.

Examples:

set /someobject
needfile
file
field:value
field2:value2
eof
ok

set /badobject
error "invalid path for set"

set /someobject field value
ok

get

get [path] [attributes]
(returns a file)

Sends a file with attributes of the given object. Optionally, you can provide a list of names (comma-separated). If there is no list, all attributes will be sent.

For attributes of type list, the number of list elements is returned as the attribute value. If the path refers to a property of type list, the resulting file will contain data for all objects on the list. Sends a file with attributes of the given object. Optionally, you can provide a list of names (comma-separated). If there is no list, all attributes will be sent.

Examples:

call

call [path] [function] [parameter1] [parameter1] [parameter3] ...
(may require files)
(may return files)

Calls a function of an object referred as path. The behavior of this function and its parameters depend on the object. The information about function parameters is available in the property description. The information about whether some files are involved will be indicated as usual (file, needfile). The network interface provides access to all functions available in FramScript, even if their call'ing is not useful. This may change in the future - some commands may be restricted for network use, e.g. by some flag.

The return value is returned inside the "Result" object (see examples).

Examples:

call /simulator netsave
file experiment.expt "current experiment state"
...contents of the file sent by the server...
eof
ok

call /simulator netload
needfile "*.expt" "Experiment"
file
...contents of the file sent to the server...
eof
ok

call /simulator/genepools worst
file
Result:
value:-1
eof
ok

reg

reg [path] [type] [event_id]

Registers for a specified event. Event handlers are visible in the objects hierarchy as fields of type "e".
reg returns the following message on the successfull registration:

ok registered_event_path
The returned path can be used to modify the handler properties and unregister from the event source (it is the regular network object).
[type] and [event_id] are optional (will replace the default values when used)
Registered events can be managed through the /cli/events collection (you gen the actual path from the reg confirmation, don't rely on the /cli/events constant). Each event handler has the following properties: "sendone" and "sendall" actions are used for requesting the stored events from the type 1 handlers.
Stored events are returned before the "ok" confirmation for the "call" command so you always know when the event stream is finished.
call /cli/events/e0 sendall
....(multiple events)...
ok

Each event sent to client contain the header (event event_id event_name) and the event file. The file contains event specific data sent in the usual object format. The info command can be used to read the event class details (see the ListChange examples).

Examples:

reg /cli/messages 1
ok /cli/events/e0
get /cli/events
file
Event:
id:e0
name:/cli/messages
type:1
count:0

eof
ok
call /simulator/print "test"
ok
- doesn't output anything because of the type=1 handling
call /cli/events/e0 sendall
event e0 /cli/messages
file
Msg:
class:Script
function:Message
message:test
level:0

eof
ok

4. Some details

File format and object contents

A file may contain any number of objects of various classes. Objects contain fields with names and values.
ClassName:
fieldname:value
fieldname2:value2
...etc

  <-( empty line ends the object contents )

ClassName2:
somefieldname:somevalue
...etc

If a field value contains \n, then the whole value is embedded in ~ signs:

fieldname:~
a multi-line value here, there may be
many lines of
text~
If there is a ~ sign within the field value, it must be quoted as \~

Objects of class "prop"

Descriptions of object fields are used in many script files in Framsticks, and contain 5 sections:

Objects of the "class" class

These are small quasi-objects which have only one attribute named "id", which contains the class name. It is used for sending object description.

ListChange event

A client can register for this event to get notifications when the list contents changes. The event source named "LISTNAME_changed" with type "e ListChange" is the event source for the list "LISTNAME". The following example gets the event class description from the server:
info /simulator/populations/groups/0/creatures_changed
file
class:
id:ListChange

prop:
id:type
name:type
type:d 0 2 ~Add~Remove~Modify

prop:
id:pos
name:position
type:d
help:modify position<0 means 'all items modified'

eof
ok
The "pos" field contains 0-based index of the added, removed or modified list item. For the "Modify" event, a negative position can be specified, which means "all items were modified".

Example: (monitoring of the creatures list)

reg /simulator/populations/groups/0/creatures_changed
ok  /cli/events/e0
call /simulator/populations/groups/0 createFromString X
event e0 /simulator/populations/groups/0/creatures_changed
file
ListChange:
type:0
pos:0

eof

file
Result:
value:<Creature object at 0x8128ee8>
eof
ok

5. Server implementation remarks

6. Some examples

To test the server, you can also use the command-line interface (v2.9). Useful options: -e disables the default error message printing, -s disable "newshell" (console handling) under linux (required when piping commands from files).

frams -e -s -inet.ini "info x /" -q
frams -e -s -inet.ini "get x /simulator/world" -q
frams -e -s -inet.ini "info x /simulator/populations/groups/0/creatures" -q
frams -e -s -inet.ini "call 1 /simulator/populations/groups/0 createFromString X[G:1]X" "get 2 /simulator/populations/groups/0/creatures/0/mechparts x,y,z" -q
more examples:
# create a simple creature for the subsequent queries
call 1 /simulator/populations/groups/0 createFromString XX[G:1]

# get populations count
get 2 /simulator/populations groups

# get population names
get 3 /simulator/populations/groups name

# get gene pools names
get 4 /simulator/genepools/groups name

# get all populations properties
get 5 /simulator/populations/groups

# get first population count
get 6 /simulator/populations/groups/0 creatures

# get all creature properties from the first population
get 7 /simulator/populations/groups/0/creatures

# get some properties from the first creature
get 8 /simulator/populations/groups/0/creatures/0 name,genotype,info,parts,joints,neurons

# get parts details (static model) from the first creature
get 9 /simulator/populations/groups/0/creatures/0/parts

# get joint connections from the first creature
get 10 /simulator/populations/groups/0/creatures/0/joints p1,p2

# get the first mech parts details (current simulation data) from the first creature
get 11 /simulator/populations/groups/0/creatures/0/mechparts/0

# get all mech part coordinates from the first creature
get 12 /simulator/populations/groups/0/creatures/0/mechparts x,y,z

# get current neuron states from the first creature
get 13 /simulator/populations/groups/0/creatures/0/neurons state

To control a neuron/muscle, set its "hold" property to 1. To set (force) the neuron value, use the "currState" field.
call 1 /simulator/populations/groups/0 createFromString XXX[G:1]
set 2 /simulator/populations/groups/0/creatures/0/neurons/0 hold 1
set 3 /simulator/populations/groups/0/creatures/0/neurons/0 currState 0.44
get 4 /simulator/populations/groups/0/creatures/0/neurons/0

7. Further development

Appendix A. Format of the 'faces' property which stores world height field

A sample with comments:

p 
0 0 0
1 0 0
1 0 1
.......
f      
0 1 2  
2 1 3  
2 3 4 2
...... 
beginning of points list
point #0 (three coordinates)
point #1
etc... more points

beginning of faces list
face with three vertices
numbes here are point indexes, points were defined above
in general, there may be more vertices
(but net.ini uses only three-point and four-point faces)

Appendix B. Hierarchy of objects - a sample generated for server version 2.9rc

  /
  +-cli
  +-simulator
    +-world
    +-genepools
    | +-groups
    |   +-0
    |   | +-genotypes
    |   |   +-0
    |   |   +-1
    |   |   +-2
    |   ...
    +-populations
      +-groups
        +-0
        | +-creatures
        |   +-0
        |   | +-parts
        |   | | +-0
        |   | | +-1
        |   | +-joints
        |   | | +-0
        |   | | +-1
        |   | +-neurodefs
        |   | | +-0
        |   | | +-1
        |   | +-mechparts
        |   | | +-0
        |   | | +-1
        |   | +-mechjoints
        |   | | +-0
        |   | | +-1
        |   | +-neurons
        |   |   +-0
        |   |   +-1
        |   +-1
        |   | ...
        |   +-2
        |     ...
        +-1
        | +-creatures
        |   +-0
        |   | ...
        |   +-1
        |   ...
        ...