This page 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:
|Class||Description||Most important fields||Used in files|
|org||Genotype with recorded performance data||name, genotype, info||*.gen, *.expt|
|prop||Property definition (for scripting)||id, name, type||*.neuro, *.expdef, *.show, *.style|
|sim_params||Simulator settings||expdef||*.sim, *.expt|
|GenotypeGroup||Genotype group settings. The "org" objects following a GenotypeGroup object are considered members of the group||name, fitness||*.gen, *.expt|
|class||Neuron definition||name, code||*.neuro|
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.
prop: id:cr_c name:Constant type:f -10000 10000 help:Constant value added to total fitness group:Fitness"prop" has 6 fields:
- 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 typesThe type of a property is defined by a string of the format
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.
- "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
p[[ return_type](argument1_type[ argument1_name],argument2_type[ argument2_name])]
where return_type and argument_type is one of the previously mentioned types (d,f,s,o,x), shortened to single letters, except for "o", which can still declare the class name by appending it to "o" (without a space), eg. "oClassName". Argument names are optional.
For maximal compatiblity the parser could assume the following:
- the word after "p" but before "(" is the return type (if present)
- anything between "(" and ")" is arguments
- everything else can be ignored
- "p" means "a procedure with unknown arguments and unknown return type". This is the only valid form of "limited-information-p", any other syntax always define the return value and all argument types.
- "p()" means "a procedure without arguments that does not return anything". Lack of the return type declaration and argument types no longer means they are undefined - they are just defined as empty. It's the presence of "(" that makes the procedure fully defined.
- "p o Something()" is a procedure returning an unknown object (and this syntax is technically incorrect because there are 3 words before "(")
- "p oSomething()" is a procedure returning the Something class object
- "p(o Something)" procedure accepting a single object argument named Something
- "p(oSomething)" procedure accepting a single unnamed argument of class Something
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 – neuron class name. It is used in genotypes and it must start with the capital letter
- longname – friendly name (displayed in hints)
- description – 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. Create the value by adding the following bits:
- 1 = Invisible – don't draw neurons of this class
- 2 = No label – don't draw classname label (below the neuron symbol) for this neuron class
- 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 = Effector – use muscle color when drawing this neuron
- 32 = Sensor – use receptor color when drawing this neuron
- icon is a neuron icon for use in NN diagrams, encoded as a coma-separated sequence of integer numbers.
- N = the total number of all numbers following this one
- NS = the number of line sequences
- repeated NS times:
- NL = number of line segments (creating a polyline)
- X,Y (repeated NL+1 times) - subsequent line segment coordinates, each line should fit in a 100x100 square
- neuron input connections will be drawn at X=25 (varying Y for multiple inputs, Y=50 for a single input)
- neuron output connection will be drawn at (X=75,Y=50)
16, 2, 3, 25,50, 40,30, 60,30, 75,50, 1, 40,50, 60,50 N = 16 numbers following this one NS = 2 line sequences NL = the first sequence has 3 segments coordinates for 3 line segments = 4 endpoints = 8 numbers NL = the second sequence has 1 segment coordinates for 1 line segment
See also: a script for creating *.neuro icon from SVG.
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,
"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)
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.