better wording, and add section on energy, primordial world and reproduction

README.md

@@ -1,35 +1,57 @@
 # AIrium 2
 
-## Creature Structure
+AIrium is an artificial life simulation environment. The second iteration of the project
+focuses on solving the problems of the first:
 
-Each creature is represented as a matrix of blocks in a 2D grid, but all creatures and
+- variety in creature body and mind structure
-structures only occupy one block in the world matrix.
+- removing evolution limits (such as brain size)
+- allowing different species to mate and produce possibly stable children
+- speed: trying to get the simulation to be as fast as possible on consumer grade hardware
 
-There are three kinds of blocks:
+### World
+
+The world is a matrix where each cell is either empty or occupied by a structure.
+Every structure occupies only one cell.
+
+### Creatures and other structures
+
+A structure is a matrix where each cell is either empty or occupied by a Block.
+Each adiacent Block can be connected.
+The blocks make up both the body and, if the blocks are connected, the mind.
+
+A structure with an operational mind governing the body is called a creature or machine.
+
+There are four kinds of blocks:
 - neuron blocks
 - action blocks
 - sensor blocks
+- resource blocks
 
 TODO: energy system
 
 ### Connection
 
-- Each block is connected to every other adiacent block (diagonals too), so each block has 9 connection weights.
+- Each block can be connected to every other adiacent block (diagonals too), so each block has 8 connection weights.
 
 `source block output ->>>- * weight ->>>- destination block`
 
-- A connection has a weight, which is a floating point number.
+- A connection _is_ a weight, which is a floating point number.
 - The connection outputs its source block's current stored signal multiplied by the weight.
-- If the weight is `0`, then there's no connection
+- If the connection is `0`, then there's no connection
-- the weight is a floating point number between -1 and 1 included.
+- if the connection is `not 0` then there is a connection
+- the highest `abs(val) where val is the connection/weight` is, the stronger the connection
+- the weight (or connection) is a floating point number between -1 and 1 included.
 
 ### Signals
 
-A signal is a floating point value. Each block stores a signal (initialized at 0 which is a null signal).
+A signal is a floating point value. Each block stores a signal.
+
+- new blocks contain the `0` signal (null signal).
+- blocks store a signal forever or until it is changed.
 
 ### Neuron (Processing) Blocks
 
-Their output is the sum of all their input connections' current output.
+Their signal is the sum of all the values provided by their input connections.
 
 ### Action (Input) blocks
 
@@ -64,19 +86,73 @@ Examples:
 
 - a "mouth" block that can communicate wether food is available to eat and can receive eat commands at the same time
 
-### Traversing the brain graph
+### Evaluating a machine's mind's iteration
 
-for each iteration, the `stored signal` of each block is calculated using its input connection.
+for each iteration, the `stored signal` of each block is calculated using its input connections.
 
 This `new stored signal` is stored in a special variable without overwriting the `current stored signal`
 so that the process can be easily accomplished in multithreading execution environments.
 
 After all the `new stored signals` have been calculated, their value is applied to the `current stored signal`
-and the calculation process is repeated. This way, signals can propragate around
+and the calculation process is repeated. This is done to encourage parallel computing.
 
+__Note:__ the bigger a machine, the slower it reacts to signals because they need more time to travel through the body
 
-## World Structure
+### Reproduction and evolution
 
-A creature is a matrix of blocks, each adiacent block is connected. The blocks make up both the body and the mind.
+This requires two action blocks:
 
-The world is a matrix where each cell is either empty or occupied by something. Every structure occupies only one cell.
+- the egg block
+- the fertilizer block
+
+machines can of course have both blocks, or even multiples of them.
+
+- the egg block leaves a structure behind, an egg. This egg will either be fertilized or deplete energy and die.
+- the fertilizer block can be used on egg structure to fertilize them
+
+#### Hatching
+
+When the egg hatches, a structure is born. The structure is built using a combination of the father's and the mother's blocks, then a mutation is applied to the result.
+
+## Energy
+
+This requires some new blocks:
+
+- the battery block
+- the energy drain block
+- the generator block
+
+- the energy drain block sucks energy from a structure's batteries.
+- the battery block stores energy and emits the current level to its connections
+- the generator block uses up a lot of energy, then gives back slightly more
+
+#### Consumption
+
+- each action block uses up a moderate amount of energy when activated
+- each sensor block uses up a small amount of energy when activated
+
+## Primordial world
+
+The world should be composed of a variety of huge, small and anything in between energy farming or storage
+structures.
+
+Even better, there should be structures generating energy and shipping it off in space.
+
+### Primordial creature
+
+Since we can't expect that interesting machines pop up in our simulation, we need to design one.
+On Earth, it took billions of years for something to show up, but we want to speed things up a little bit.
+
+This machine needs:
+
+- to search for energy sources
+- to find energy sources and get there
+- to use energy sources to fill up batteries
+- to successfully create fertilized eggs
+
+From there, maybe something smarter can show up. It is __essential__ that the user can save a machine at any time,
+even early in an implementation. We __don't__ want to lose good machines!
+
+## Interface
+
+Good luck coming up with a good one...