last modified 2004-02-25
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.
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.
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)... eofFor 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 [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:
eofIf the "eof" exists in the file sent, it must be "quoted" as \eof (\eof must be quoted as \\eof etc.)
needfile [suggested_name] [file_description]
data sent by the client to the server data sent by the server to the client
version [number]Returns "ok" if the requested protocol version is supported or "error" otherwise.
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 [path](requires sending a file)
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 [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:
get / version file server: version:1.0 eof ok
get / somelist file server: lista:2 eof ok
get /somelist file object: id:id1 prop:123 object: id:id2 prop:456 eof ok
get /somelist id file object: id:id1 object: id:id2 eof ok
get /somelist/0 prop file object: prop:123 eof
get /somelist/id1 ok file object: id:id1 prop:123 eof ok
call [path] [function] [parameter1] [parameter1] [parameter3] ...(may require 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 [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_pathThe returned path can be used to modify the handler properties and unregister from the event source (it is the regular network object).
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
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 \~
p [[return_type] (argument1_type [argument1_name], argument2_type [argument2_name])]
where return_type and argument_type is one of the forementioned letters (d,f,s,o,x).
procedures without the return value have empty return type. procedure definition can omit argument names.
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 okThe "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
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" -qmore 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 stateTo 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
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) |
/ +-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 | ... ...