second iteration

README.md

@@ -1,5 +1,7 @@
 # AIrium 2
 
+## Creature Structure
+
 Each creature is represented as a matrix of blocks in a 2D grid world
 
 There are three kinds of blocks:
@@ -7,28 +9,38 @@ There are three kinds of blocks:
 - action blocks
 - sensor blocks
 
-all signals exchanged by blocks are floating point numbers
-
 TODO: energy system
 
-### Neuron Blocks
+### Connection
 
-They act as connectors, they have a __data direction__ attribute which tells in which direction their output flows
+Each block is connected to every other adiacent block
 
-They can be represented as arrows
+`source block output ->>>- * weight ->>>- destination block`
 
-### Action blocks
+- A connection has 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
+
+### Signals
+
+A signal is a floating point value. Each block stores a signal (initialized at 0 which is a null signal).
+
+### Neuron (Processing) Blocks
+
+Their output is the sum of all their input connections' current output.
+
+### Action (Input) blocks
 
 They take an input signal and act by doing something, for example:
 
 - they move the body in space
 - they eject something
 - they change color
-- they read the next block
-- they write the next block
+- they interact with other structures
 - they "eat" a block
+- nothing (can be useful to stop signals from passing through)
 
-### Sensor blocks
+### Sensor (Input) blocks
 
 They give adiacent blocks a signal, for example:
 
@@ -40,29 +52,17 @@ They give adiacent blocks a signal, for example:
 
 ### Traversing the brain graph
 
-In this system, the body is the brain. It can be represented either as a __graph__ of arrows (neuron blocks) and nodes (action/sensor blocks) or as a __matrix__ of block instances.
+for each iteration, the `stored signal` of each block is calculated using its input connection.
 
-Graph traversing pseudocode:
+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.
 
-    stack = []
+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
 
-    getOutput = function (avoidLoops) :
-        if avoidLoops: return lastIterationCache
-        if currentIterationCache: return currentIterationCache
-        stack.add(thisBlock)
-        outputs = []
-        for each input block in this block:
-            thatBlock = the current input block we're checking
-            output.add(thatBlock.getOutput(amIInTheStack)) // passes avoidLoops as true to avoid cyclic structures
-        res =  // use the outputs to figure out what to return
-        lastIterationCache = currentIterationCache
-        currentIterationCache = res
-        return res
 
-    clearStacks()
-    // Clean up iteration
-    fixIterationCacheOfAllBlocks()
+## World Structure
 
-    for each output block in the body:
-        actionBlock.apply(actionBlock.getOutput())
+A creature is a matrix of blocks, each adiacent block is connected. The blocks make up both the body and the mind.
 
+The world is a matrix where each cell is either empty or occupied by something. Every structure occupies only one cell.