Index: java/Framclipse/com.framsticks.framclipse/res/framscript.xml
===================================================================
--- java/Framclipse/com.framsticks.framclipse/res/framscript.xml	(revision 699)
+++ java/Framclipse/com.framsticks.framclipse/res/framscript.xml	(revision 717)
@@ -37,4 +37,5 @@
 		<element name="neurons" type="integer" min="0" max="1" default="1"/>
 		<element name="dust" type="integer" min="0" max="1" default="1"/>
+		<element name="energy" type="integer" min="0" max="1" default="1"/>
 	</type>
 	<type name="show" context="show file">
@@ -401,7 +402,24 @@
   recipient.energy += amount;
   this.energy -= amount;
-}]]></description>
+}
+
+Calling this function from inside the collision handler to transfer energy between colliding parts automatically adds the relevant MechPart references, as if transferEnergyToPart was called, i.e.
+	Collision.Creature1.transferEnergyTo(Collision.Creature2, e);
+is equivalent to:
+	Collision.Creature1.transferEnergyToPart(Collision.Part1, Collision.Creature2, Collision.Part2, e);
+When this behavior is not intended, explicit nulls in transferEnergyToPart() can be used to avoid associating the energy transfer with the currently colliding parts, like this:
+	Collision.Creature1.transferEnergyToPart(null, Collision.Creature2, null, e);]]></description>
 			<arguments>
 				<argument name="recipient" type="Creature"/>
+				<argument name="requested_amount_of_energy" type="float"/>
+			</arguments>
+		</element>
+		<element name="transferEnergyToPart" function="true" type="float" flags="32">
+			<description><![CDATA[Transfer energy between specific parts of two creatures. Part arguments are only used for visualization and can be null, which would mean "the entire creature".
+See also: transferEnergyTo()]]></description>
+			<arguments>
+				<argument name="source part" type="MechPart"/>
+				<argument name="recipient creature" type="Creature"/>
+				<argument name="recipient part" type="MechPart"/>
 				<argument name="requested_amount_of_energy" type="float"/>
 			</arguments>
@@ -628,4 +646,36 @@
 				<argument type="untyped"/>
 			</arguments>
+		</element>
+	</type>
+	<type name="EnergyParticles" context="Global context">
+		<element name="lifespan_min" type="integer" min="1" max="100" default="20">
+			<description><![CDATA[Particle's lifespan is a random number taken from the specified range [min,max]]]></description>
+		</element>
+		<element name="lifespan_max" type="integer" min="1" max="100" default="30">
+			<description><![CDATA[Particle's lifespan is a random number taken from the specified range [min,max]]]></description>
+		</element>
+		<element name="amount_min" type="float" min="0" max="1000" default="0.5">
+			<description><![CDATA[A particle is emitted if the amount of energy transferred in a single step exceeds this threshold]]></description>
+		</element>
+		<element name="amount_max" type="float" min="0.01" max="1000" default="5.0">
+			<description><![CDATA[A maximum amount of energy a single particle can represent. If energy transferred in a single simulation step exceeds this amount, more particles are created.]]></description>
+		</element>
+		<element name="step_maxparticles" type="integer" min="1" max="100" default="5">
+			<description><![CDATA[Limit the number of particles created in a single step for each energy transfer]]></description>
+		</element>
+		<element name="random_pos" type="float" min="0" max="1" default="0.3">
+			<description><![CDATA[The amount of random shift used for individual particles (uniform distribution)]]></description>
+		</element>
+		<element name="turn" type="float" min="0" max="1" default="0.15">
+			<description><![CDATA[Ignore (0) or directly follow (1) the potentially moving target of a particle. Intermediate values create momentum effect as if the target was gradually adjusted.]]></description>
+		</element>
+		<element name="speedup" type="float" min="0" max="1" default="0.05">
+			<description><![CDATA[Increase particle speed by this factor in each simulation step. This can help reach moving targets (along with "Turn towards target").]]></description>
+		</element>
+		<element name="fade" type="float" min="0" max="1" default="0.9">
+			<description><![CDATA[Gradually decrease particle size before it disappears when its energy transfer has ended while the particle was on its way. The remaining energy amount is multiplied by this factor in each step. 0 means: disappear immediately, 1 means: don't decrease the size at all. Note that these parameters only concern visualization and the actual energy was already transferred.]]></description>
+		</element>
+		<element name="total_limit" type="integer" min="10" max="10000" default="1000">
+			<description><![CDATA[Limit the total number of existing energy particles (to save performance)]]></description>
 		</element>
 	</type>
@@ -3346,5 +3396,5 @@
 			<description><![CDATA[Removes custom display settings that might have been defined by various scripts (expdef or show).]]></description>
 		</element>
-		<element name="mode" type="integer" min="0" max="2">
+		<element name="mode" type="integer" min="0" max="2" default="2">
 			<description><![CDATA["Automatic" labels all signal sources in all channels and shows the intensity map of the first channel. This is sufficient for many simple setups, but as the number of signals and channels grows, the display becomes cluttered. In such cases, the experiment definition can define "Custom" signal visualization tailored for the particular experiment.]]></description>
 		</element>
@@ -3450,4 +3500,5 @@
 	32 - new groups will be created for imported genepools and populations
 	64 - allow switching to a different expdef while importing parameters (4)
+	256 - creatures
 
 The standard behavior (without the second argument) is to import genotypes, parameters, and genepool and population settings (2+4+8+16). Note that "64" is not included by default, because the expdef change resets all simulator parameters, which contradicts the usual meaning of "import" in Framsticks ("add data", as opposed to "load" meaning "replace data"). Moreover, using the "64" option in scripts can be dengerous, especially all expdef and show scripts should always declare the proper expdef name in their header rather than change the expdef directly. Without the "64" option, it is always safe to "import" any file in a script regardless of the current simulator state.]]></description>
@@ -3480,4 +3531,5 @@
 	32 - population settings
 	64 - do autosave
+	256 - creatures
 - selected genepool, -1 means all genepools
 - selected population, -1 means all populations]]></description>
@@ -3563,9 +3615,10 @@
 		</element>
 		<element name="createrr" type="integer" min="0" max="2" default="1"/>
+		<element name="groupchk" type="integer" min="0" max="1" default="1">
+			<description><![CDATA[Warnings will be printed when invalid genotypes are added to a gene pool.]]></description>
+		</element>
 		<element name="creatwarnfail" type="integer" min="0" max="1">
-			<description><![CDATA[Creatures grown with warnings will not be simulated.]]></description>
-		</element>
-		<element name="groupchk" type="integer" min="0" max="1" default="1"/>
-		<element name="vmdebug" type="integer" min="0" max="1"/>
+			<description><![CDATA[Creatures grown with warnings will not be simulated. This helps prevent the propagation of faulty genes, because genotypes that cause warnings when interpreted will not reproduce.]]></description>
+		</element>
 		<element name="resetToDefaults" function="true" type="void">
 			<description><![CDATA[Clears groups and loads default values for simulator parameters, then calls onExpDefLoad() of the current experiment definition.]]></description>
@@ -3638,4 +3691,7 @@
 			<description><![CDATA[Number of neural network simulation steps in each physics simulation step]]></description>
 		</element>
+		<element name="rndcollisions" type="integer" min="0" max="1" default="1">
+			<description><![CDATA[When enabled, custom collision handlers are invoked in random order. This can help remove unfair bias in some experiments - for example where the same collision order in each simulation step would cause some creatures colliding with food to consume energy while other colliding creatures would starve.]]></description>
+		</element>
 		<element name="signals" type="WorldSignals" flags="35"/>
 		<element name="odeshape" type="integer" min="0" max="1"/>
@@ -4634,4 +4690,5 @@
 	32 - new groups will be created for imported genepools and populations
 	64 - allow switching to a different expdef while importing parameters (4)
+	256 - creatures
 
 The standard behavior (without the second argument) is to import genotypes, parameters, and genepool and population settings (2+4+8+16). Note that "64" is not included by default, because the expdef change resets all simulator parameters, which contradicts the usual meaning of "import" in Framsticks ("add data", as opposed to "load" meaning "replace data"). Moreover, using the "64" option in scripts can be dengerous, especially all expdef and show scripts should always declare the proper expdef name in their header rather than change the expdef directly. Without the "64" option, it is always safe to "import" any file in a script regardless of the current simulator state.]]></description>
@@ -4664,4 +4721,5 @@
 	32 - population settings
 	64 - do autosave
+	256 - creatures
 - selected genepool, -1 means all genepools
 - selected population, -1 means all populations]]></description>
@@ -4747,9 +4805,10 @@
 		</element>
 		<element name="createrr" type="integer" min="0" max="2" default="1"/>
+		<element name="groupchk" type="integer" min="0" max="1" default="1">
+			<description><![CDATA[Warnings will be printed when invalid genotypes are added to a gene pool.]]></description>
+		</element>
 		<element name="creatwarnfail" type="integer" min="0" max="1">
-			<description><![CDATA[Creatures grown with warnings will not be simulated.]]></description>
-		</element>
-		<element name="groupchk" type="integer" min="0" max="1" default="1"/>
-		<element name="vmdebug" type="integer" min="0" max="1"/>
+			<description><![CDATA[Creatures grown with warnings will not be simulated. This helps prevent the propagation of faulty genes, because genotypes that cause warnings when interpreted will not reproduce.]]></description>
+		</element>
 		<element name="resetToDefaults" function="true" type="void">
 			<description><![CDATA[Clears groups and loads default values for simulator parameters, then calls onExpDefLoad() of the current experiment definition.]]></description>
@@ -5318,4 +5377,7 @@
 			<description><![CDATA[Number of neural network simulation steps in each physics simulation step]]></description>
 		</element>
+		<element name="rndcollisions" type="integer" min="0" max="1" default="1">
+			<description><![CDATA[When enabled, custom collision handlers are invoked in random order. This can help remove unfair bias in some experiments - for example where the same collision order in each simulation step would cause some creatures colliding with food to consume energy while other colliding creatures would starve.]]></description>
+		</element>
 		<element name="signals" type="WorldSignals" flags="35"/>
 	</type>
@@ -6072,7 +6134,24 @@
   recipient.energy += amount;
   this.energy -= amount;
-}]]></description>
+}
+
+Calling this function from inside the collision handler to transfer energy between colliding parts automatically adds the relevant MechPart references, as if transferEnergyToPart was called, i.e.
+	Collision.Creature1.transferEnergyTo(Collision.Creature2, e);
+is equivalent to:
+	Collision.Creature1.transferEnergyToPart(Collision.Part1, Collision.Creature2, Collision.Part2, e);
+When this behavior is not intended, explicit nulls in transferEnergyToPart() can be used to avoid associating the energy transfer with the currently colliding parts, like this:
+	Collision.Creature1.transferEnergyToPart(null, Collision.Creature2, null, e);]]></description>
 			<arguments>
 				<argument name="recipient" type="Creature"/>
+				<argument name="requested_amount_of_energy" type="float"/>
+			</arguments>
+		</element>
+		<element name="transferEnergyToPart" function="true" type="float" flags="32">
+			<description><![CDATA[Transfer energy between specific parts of two creatures. Part arguments are only used for visualization and can be null, which would mean "the entire creature".
+See also: transferEnergyTo()]]></description>
+			<arguments>
+				<argument name="source part" type="MechPart"/>
+				<argument name="recipient creature" type="Creature"/>
+				<argument name="recipient part" type="MechPart"/>
 				<argument name="requested_amount_of_energy" type="float"/>
 			</arguments>
@@ -6487,4 +6566,5 @@
 		<element name="neurons" type="integer" min="0" max="1" default="1"/>
 		<element name="dust" type="integer" min="0" max="1" default="1"/>
+		<element name="energy" type="integer" min="0" max="1" default="1"/>
 		<element name="clear" function="true" flags="34"/>
 		<element name="add" function="true" flags="34"/>
@@ -6568,4 +6648,7 @@
 		<element name="nnspeed" type="float" min="0" max="1000" default="1.0">
 			<description><![CDATA[Number of neural network simulation steps in each physics simulation step]]></description>
+		</element>
+		<element name="rndcollisions" type="integer" min="0" max="1" default="1">
+			<description><![CDATA[When enabled, custom collision handlers are invoked in random order. This can help remove unfair bias in some experiments - for example where the same collision order in each simulation step would cause some creatures colliding with food to consume energy while other colliding creatures would starve.]]></description>
 		</element>
 		<element name="signals" type="WorldSignals" flags="35"/>
@@ -6872,5 +6955,5 @@
 Bits 2-16 are not implemented in the old Framsticks Theater application.]]></description>
 		</element>
-		<element name="world_visibility" type="integer" min="0" max="15" default="15">
+		<element name="world_visibility" type="integer" min="0" max="31" default="31">
 			<description><![CDATA[Bit field:
 1 - background/panorama
@@ -6878,4 +6961,5 @@
 4 - creatures
 8 - dust (particles)
+16 - energy transfers (particles)
 Not implemented in the old Framsticks Theater application.]]></description>
 		</element>
@@ -7041,4 +7125,6 @@
 		<element name="KEY_MENU" type="integer" flags="1"/>
 		<element name="KEY_SEARCH" type="integer" flags="1"/>
+		<element name="KEY_LEFT" type="integer" flags="1"/>
+		<element name="KEY_RIGHT" type="integer" flags="1"/>
 		<element name="SHARING_HTML" type="string" flags="1"/>
 		<element name="top_left" type="Element" flags="1"/>
@@ -7153,4 +7239,5 @@
 		<element name="autorepeat" type="integer" min="0" max="1"/>
 		<element name="style" type="integer"/>
+		<element name="feedback" type="integer"/>
 		<element name="userdata" type="untyped"/>
 		<element name="visible" type="integer" min="0" max="1"/>
@@ -7512,4 +7599,5 @@
 		<element name="neurons" type="integer" min="0" max="1" default="1"/>
 		<element name="dust" type="integer" min="0" max="1" default="1"/>
+		<element name="energy" type="integer" min="0" max="1" default="1"/>
 		<element name="clear" function="true" flags="34"/>
 		<element name="add" function="true" flags="34"/>
