Index: java/Framclipse/com.framsticks.framclipse/res/framscript.xml
===================================================================
--- java/Framclipse/com.framsticks.framclipse/res/framscript.xml	(revision 693)
+++ java/Framclipse/com.framsticks.framclipse/res/framscript.xml	(revision 699)
@@ -128,4 +128,8 @@
 			<description><![CDATA[Note that the index changes depending on the current creature position in the population. Use Creature.uid if you need a permanent identifier that persists through the entire object lifetime.]]></description>
 		</element>
+		<element name="num" type="integer">
+			<description><![CDATA[Acts as a unique identifier, but less strict than "uid". Unlike "uid", "num" can be changed and therefore can be saved and restored, providing persistence and continuity beyond a single application run. "num" is only guaranteed to be unique if it is autogenerated and not changed by the user, otherwise it is user's responsibility to manage the proper values of "num". Autogenerated "num" is always equal to the largest previously used "num" + 1. The largest previously used value is stored in Simulator.last_creature_num and can be changed as well (and is automatically saved and restored as a part of the Simulator state). Limitation: being a 32-bit integer, "num" overflows at about 2 billion counts.
+See also: uid]]></description>
+		</element>
 		<element name="gnum" type="integer"/>
 		<element name="buildproblems" type="integer" flags="34"/>
@@ -365,5 +369,6 @@
 		</element>
 		<element name="uid" type="string" flags="1">
-			<description><![CDATA[Unique identifier]]></description>
+			<description><![CDATA[Unique identifier that is generated on object creation. "uid" is only unique during a single application run. Subsequent runs generate the same sequence of uid values.
+See also: num]]></description>
 		</element>
 		<element name="signals" type="CreatureSignals" flags="35"/>
@@ -479,5 +484,10 @@
 	</type>
 	<type name="CreatureSnapshot" context="Global context">
-<description><![CDATA[A data object consisting of the same fields as the serialized Creature. Typically used for reading a Creature back from a file, then Population.add(snapshot_object) creates the Creature object from the snapshot.]]></description>
+<description><![CDATA[A data object consisting of the same fields as the serialized Creature. Typically used for reading a Creature back from a file; Population.add(snapshot_object) recreates the Creature object from the snapshot. When the creature is added to a population and it happens to collide with the terrain, the creature will be automatically moved upwards just enough to avoid the collision.
+Serialized Creature preserves most of its data fields (including the 'data' dictionary) but only keeps aggregated information about its physical state, which is body orientation and location of the bounding box center. Individual physical body parts' locations, states and neuron states are lost.
+Restoring the state of a formerly living, serialized creature using its CreatureSnapshot is not perfect. Apart from losing information about individual body and brain parts and their states, the usual flow of calculating performance may be disturbed, which is related to the 'performance sampling period' being interrupted as well as the specifics of the 'freezing period' mechanism. In consequence, the intended behavior of 'lifespan', 'steps_in_lifespan', and performance fields may be broken. For example, when period=100, after every 100 'steps_in_lifespan', the 'lifespan' increases by 100 and the new performance data is calculated. When the period is interrupted by saving/restoring, 'steps_in_lifespan' continues to increase from the saved value, but performance counters will be waiting another full 100 steps before the next update, losing the information from the unfinished period. The resulting 'lifespan' will be lower than it would have been without interruptions, and will be inconsistent with 'steps_in_lifespan'. Because of these issues, it is strongly advised to thoroughly inspect and test the behavior of the restored Creatures in various moments in their lifepspan, and use CreatureSnapshot only when necessary.
+See also: scripts/standard_exploadsave.inc
+See also: Population.add()
+]]></description>
 		<element name="new" function="true" type="Creature"><arguments/></element>
 		<element name="name" type="string" max="40"/>
@@ -485,4 +495,8 @@
 		<element name="info" type="string">
 			<description><![CDATA[Additional info or comments]]></description>
+		</element>
+		<element name="num" type="integer">
+			<description><![CDATA[Acts as a unique identifier, but less strict than "uid". Unlike "uid", "num" can be changed and therefore can be saved and restored, providing persistence and continuity beyond a single application run. "num" is only guaranteed to be unique if it is autogenerated and not changed by the user, otherwise it is user's responsibility to manage the proper values of "num". Autogenerated "num" is always equal to the largest previously used "num" + 1. The largest previously used value is stored in Simulator.last_creature_num and can be changed as well (and is automatically saved and restored as a part of the Simulator state). Limitation: being a 32-bit integer, "num" overflows at about 2 billion counts.
+See also: uid]]></description>
 		</element>
 		<element name="gnum" type="integer"/>
@@ -544,5 +558,6 @@
 		</element>
 		<element name="uid" type="string">
-			<description><![CDATA[Unique identifier]]></description>
+			<description><![CDATA[Unique identifier that is generated on object creation. "uid" is only unique during a single application run. Subsequent runs generate the same sequence of uid values.
+See also: num]]></description>
 		</element>
 	</type>
@@ -1704,5 +1719,8 @@
 		<element name="numneurons" type="integer" flags="16"/>
 		<element name="numconnections" type="integer" flags="16"/>
-		<element name="num" type="integer"/>
+		<element name="num" type="integer">
+			<description><![CDATA[Acts as a unique identifier, but less strict than "uid". Unlike "uid", "num" can be changed and therefore can be saved and restored, providing persistence and continuity beyond a single application run. "num" is only guaranteed to be unique if it is autogenerated and not changed by the user, otherwise it is user's responsibility to manage the proper values of "num". "Genotype.num" is generated on adding a Genotype object to a group, unless it already has a non-zero "num" (previously autogenerated or user-assigned). Autogenerated "num" is always equal to the largest previously used "num" + 1. The largest previously used value is stored in Simulator.last_genotype_num and can be changed as well (and is automatically saved and restored as a part of the Simulator state). Limitation: being a 32-bit integer, "num" overflows at about 2 billion counts.
+See also: uid]]></description>
+		</element>
 		<element name="gnum" type="integer"/>
 		<element name="popsiz" type="integer" deprecated="true" flags="8226">
@@ -1751,5 +1769,6 @@
 		</element>
 		<element name="uid" type="string" flags="1">
-			<description><![CDATA[Unique identifier]]></description>
+			<description><![CDATA[Unique identifier that is generated on object creation. "uid" is only unique during a single application run. Subsequent runs generate the same sequence of uid values.
+See also: num]]></description>
 		</element>
 		<element name="getModel" function="true" type="Model" flags="32"><arguments/></element>
@@ -3073,6 +3092,8 @@
 		</element>
 		<element name="add" function="true" type="Creature" flags="34">
-			<arguments>
-				<argument name="genotype object or geno object or string genotype" type="untyped"/>
+			<description><![CDATA[Adding CreatureSnapshot object automatically copies the CreatureSnapshot fields into the Creature, including creature location (the center of the bounding box is preserved) and orientation.
+See also: CreatureSnapshot]]></description>
+			<arguments>
+				<argument name="Genotype object or Geno object or string genotype or CreatureSnapshot object" type="untyped"/>
 			</arguments>
 		</element>
@@ -3480,4 +3501,10 @@
 		<element name="time" type="integer" deprecated="true" flags="8226">
 			<description><![CDATA[Simulator.time will be removed because of its misleading name, please use Simulator.stepNumber instead.]]></description>
+		</element>
+		<element name="last_genotype_num" type="integer" min="0" max="-1" default="0" flags="32">
+			<description><![CDATA[See: Genotype.num]]></description>
+		</element>
+		<element name="last_creature_num" type="integer" min="0" max="-1" default="0" flags="32">
+			<description><![CDATA[See: Creature.num]]></description>
 		</element>
 		<element name="stepNumber" type="integer" flags="34"/>
@@ -4658,4 +4685,10 @@
 		<element name="time" type="integer" deprecated="true" flags="8226">
 			<description><![CDATA[Simulator.time will be removed because of its misleading name, please use Simulator.stepNumber instead.]]></description>
+		</element>
+		<element name="last_genotype_num" type="integer" min="0" max="-1" default="0" flags="32">
+			<description><![CDATA[See: Genotype.num]]></description>
+		</element>
+		<element name="last_creature_num" type="integer" min="0" max="-1" default="0" flags="32">
+			<description><![CDATA[See: Creature.num]]></description>
 		</element>
 		<element name="stepNumber" type="integer" flags="34"/>
@@ -5650,5 +5683,8 @@
 		<element name="numneurons" type="integer" flags="16"/>
 		<element name="numconnections" type="integer" flags="16"/>
-		<element name="num" type="integer"/>
+		<element name="num" type="integer">
+			<description><![CDATA[Acts as a unique identifier, but less strict than "uid". Unlike "uid", "num" can be changed and therefore can be saved and restored, providing persistence and continuity beyond a single application run. "num" is only guaranteed to be unique if it is autogenerated and not changed by the user, otherwise it is user's responsibility to manage the proper values of "num". "Genotype.num" is generated on adding a Genotype object to a group, unless it already has a non-zero "num" (previously autogenerated or user-assigned). Autogenerated "num" is always equal to the largest previously used "num" + 1. The largest previously used value is stored in Simulator.last_genotype_num and can be changed as well (and is automatically saved and restored as a part of the Simulator state). Limitation: being a 32-bit integer, "num" overflows at about 2 billion counts.
+See also: uid]]></description>
+		</element>
 		<element name="gnum" type="integer"/>
 		<element name="popsiz" type="integer" deprecated="true" flags="8226">
@@ -5697,5 +5733,6 @@
 		</element>
 		<element name="uid" type="string" flags="1">
-			<description><![CDATA[Unique identifier]]></description>
+			<description><![CDATA[Unique identifier that is generated on object creation. "uid" is only unique during a single application run. Subsequent runs generate the same sequence of uid values.
+See also: num]]></description>
 		</element>
 		<element name="getModel" function="true" type="Model" flags="32"><arguments/></element>
@@ -5761,4 +5798,8 @@
 		<element name="index" type="integer" flags="35">
 			<description><![CDATA[Note that the index changes depending on the current creature position in the population. Use Creature.uid if you need a permanent identifier that persists through the entire object lifetime.]]></description>
+		</element>
+		<element name="num" type="integer">
+			<description><![CDATA[Acts as a unique identifier, but less strict than "uid". Unlike "uid", "num" can be changed and therefore can be saved and restored, providing persistence and continuity beyond a single application run. "num" is only guaranteed to be unique if it is autogenerated and not changed by the user, otherwise it is user's responsibility to manage the proper values of "num". Autogenerated "num" is always equal to the largest previously used "num" + 1. The largest previously used value is stored in Simulator.last_creature_num and can be changed as well (and is automatically saved and restored as a part of the Simulator state). Limitation: being a 32-bit integer, "num" overflows at about 2 billion counts.
+See also: uid]]></description>
 		</element>
 		<element name="gnum" type="integer"/>
@@ -5999,5 +6040,6 @@
 		</element>
 		<element name="uid" type="string" flags="1">
-			<description><![CDATA[Unique identifier]]></description>
+			<description><![CDATA[Unique identifier that is generated on object creation. "uid" is only unique during a single application run. Subsequent runs generate the same sequence of uid values.
+See also: num]]></description>
 		</element>
 		<element name="signals" type="CreatureSignals" flags="35"/>
