Framsticks

This file describes the format of files used by the Framsticks simulator. The same basic format is used for storing genotypes, scripting extensions and settings. Some constants are also documented here.

General rules for all files

All files used by Framsticks are text-only files, which means that they can be easily viewed (or edited by advanced users) using your favourite text viewer/editor.

A file may contain any number of objects of various classes. Objects contain fields with names and values. Unlike XML there is no hierarchy nor relation between objects, however the application can interpret the sequence of objects in this way (eg. "GenotypeGroup:" contains "org:").

ClassName:
fieldname:value
fieldname2:value2
...etc

  ← empty line ends the object contents

ClassName2:
somefieldname:somevalue
...etc

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

fieldname:~     ← note that the value starts in the next line
a multi-line value here, there may be
many lines of
text~

In the above example, the value will be "a multi-line value here, there may be\nmany lines of\ntext".

If there is a ~ sign within the field value, it must be quoted as \~

Lines starting with "#" (hash) are comments (but not inside multiline fields).
The special #include comment includes the contents of another file at the point where this directive is placed. (This feature is provided to facilitate creating Framsticks script files by users. The Framsticks application itself never generates files with #include, so you can ignore this directive when reading genotype files).

There is an official C++ source for parsing the Framsticks file format: see MultiParamLoader, MiniGenotypeLoader and loadertest.cpp from GDK (Genotype Developer Kit).

Examples of some popular classes:

Defining properties

Properties are very common in Framsticks. You see them in the GUI, you can access them in scripts. A property can be treated as a variable or attribute of some object. In *.expdef, *.show, *.neuro and *.style files you can create properties by adding the "prop" objects.

Example:

prop:
id:cr_c
name:Constant
type:f -10000 10000
help:Constant value added to total fitness
group:Fitness

• id – internal field name (for scripting)
• name – user-friendly name (displayed in the user interface where appropriate)
• type – data type (see below)
• flags – additional information
• help – additional description (for a tooltip, or documentation)
• group – properties with the same group will be displayed together, if feasible.

Property types

• type[subtype] [min max [default] [~enum1~enum2~enum3]]
  
  
• type is one of the following letters:
  • d (for 32-bit signed integers)
  • f (for 64-bit signed floating points – "double")
  • s (for strings of characters of any length)
  • x (universal type for values of any type)
  • o (objects)
  • p (procedures and functions)
  • l (lists of elements) and e (event source) are only used in the Framsticks server and are not described here
• subtype (optional) is 'b' or 'c' and can only be used for type 'd'. 'b' is a hint for the GUI to present the property as a binary value (i.e. a list of binary on/off switches). 'c' informs that this integer property describes a color as 0x00RRGGBB (for colors, you can also define min and max as "0 16777215"). A subtype can be safely ignored, it is only for presentation/editing purposes.

Minimum, maximum and default values have the usual meaning for 'd' and 'f' types. If you wanted to define the default value without introducing restrictions on min and max, use "0 -1" for min and max.

For 's' type, the default value is not implemented and is ignored (for now). For 's' type, the min and max values have a special meaning. The minimum value tells if the string is multiline (put 0 for single line, 1 for multiline). The maximum value defines the maximum allowed length (in characters) of the string (put 0 or do not give any value to allow any length).

The "enum..." optional part can only be used for types 'd' and 's'. For 's', the enum list can be used by the GUI as a list of suggested string values (but it does not limit in any way strings entered by a user). For 'd', it can be used by the GUI as a list of string choices that are associated with integer values, starting from zero.

Some examples:

• "d" – an integer property
• "f −2.3 5.5" – a floating point property, allowed range -2.3..5.5
• "s" – a single-line string, any length
• "s 1 500" – a multiline string, up to 500 chars
• "d 0 3 2 ~very low~low~medium~high" – an integer of value 0, 1, 2 (default) or 3, with symbolic labels assigned (and shown by a smart GUI)
• "dc 0 16777215 255" – a color, blue as default

The 'o' type is used for object values. The syntax is "o [ClassName]".

The 'p' type is used for procedures and functions. The syntax is

Property flags

A flag is a number that is converted to a binary form, and each bit has its own meaning. Therefore you can encode many options in a single number (e.g. 41=32+8+1=binary 101001, so three options are set).
The default value is 0, which means "public".

For properties, the following bits are used:

• 1 – readonly
• 16 – user readonly (user should not modify this field)
• 32 – private (user should not see this field)
  This flag is commonly used in neuron definitions. Neuron properties are by default accessible from genotype level and visible to genetic operators. If you need a private internal variable you should set its flag to "32" (see "delay.neuro" example).

Specific file types and their contents

Neuron definitions (*.neuro)

Contains one "class:" object (which defines the neuron class) and any number of "prop:" objects (which define neuron properties).

"class:" has the following properties:

• name, longname, description – neuron class name (used in genotypes), friendly name (used in hints), long description (optional)
• code – contains the neuron script source.
  • function init() – invoked once for each neuron instance (so that you can e.g. initialize some internal state)
  • function go() – called in each simulation step. Should contain the neuron logic (i.e. assign a new output value to Neuro.state)
• prefinputs is the preferred number of inputs of the neuron. −1 means "any number of inputs is OK".
• prefoutput should be 1 if the neuron provides meaningful output value, 0 otherwise.
• preflocation should be 0 if the neuron is not embodied, 1 if it is located on a Part, 2 if it is located on a Joint.
• vhints (visual hints) is a bit-field. Construct the value by adding the following bits:
  • 1 = Invisible – don't draw neurons of this class
  • 2 = No label – don't draw classname label for this neuron class (below neuron symbol)
  • 4 = First Part – draw the neuron at the first part when attached to a joint (default is in the middle)
  • 8 = Second Part – draw the neuron at the second part when attached to a joint (default is in the middle)
  • 16 = Muscle – use muscle color when drawing this neuron
  • 32 = Receptor – use receptor color when drawing this neuron

Experiment definitions (*.expdef)

Contains one "expdef:" object (the experiment definition), any number of "prop:" objects (which define experiment parameters, ExpParams), and any number of "state:" objects (which are internal state items, ExpState).

"expdef:" has the following properties:

• name – experiment title (single line)
• info – experiment description (multiline)
• neurons – specifies which neuron classes will be available in this experiment. If you developed neurons that require a specific experiment definition, you can put these neuron files in a dedicated directory and declare their location using the neurons property. This way you avoid cluttering other experiment definitions with these neurons (if they require a specific expdef, they would not work with other expdef's anyway).
  Neurons that you want to be available are specified by:
  • neuron file name (relative to the scripts directory)
  • file pattern (as above, but can refer to more files at once by using a single asterisk *)
  • a special word std meaning "standard neurons" (i.e. all built-in neurons)
  Multiple neuron specifications must be separated by a comma (,)
  The default setting is "std,*.neuro" which means "use standard neurons and all scripting neurons from *.neuro files". The default setting illustrates how to use a comma to separate two specifications, and how to use a file pattern to specify all file names ending with .neuro.
• code – contains the experiment script source.