Merge branch 'master' of https://github.com/MaxRobinsonTheGreat/EvolutionSimulatorV2

README.md

@@ -1,3 +1,5 @@
+This is the readme for the evolution simulator, The Life Engine. The code is private, though that may change.
+
 # The Life Engine
 The life engine is a cellular automaton designed to simulate the long term processes of biological evolution. It allows organisms to eat, reproduce, mutate, and adapt.
 Unlike genetic algorithms, the life engine does not manually select the most "fit" organism for some given task, but rather allows true natural selection to 
@@ -15,62 +17,48 @@ A cell can be one of the following types.
 ### Independent Cells
 Independent cells are not part of organisms. 
 - Empty - Dark blue, inert.
-- Food - Green, provides nourishment for organisms.
+- Food - Grayish-blue, provides nourishment for organisms.
 - Wall - Gray, blocks organisms movement and reproduction.
 ### Organism Cells
 Organism Cells are only found in organisms, and cannot exist on their own in the grid.
 - Mouth - Orange, eats food in directly adjacent cells.
-- Producer - White, randomly generates food in directly adjacent empty cells.
+- Producer - Green, randomly generates food in directly adjacent empty cells.
 - Mover - Light blue, allows the organism to move and rotate randomly.
 - Killer - Red, harms organisms in directly adjacent cells (besides itself).
 - Armor - Purple, negates the effects of killer cells.
+- Eye - Light purple with a slit, allows the organism to see and move intelligently. See further description below.
 
 ## Organisms
-Organisms are structures of cells.
+Organisms are structures of cells that eat food, reproduce, and die.
 When an organism dies, every cell in the grid that was occupied by a cell in its body will be changed to food.
 Their lifespan is calculated by multiplying the number of cells they have by the hyperparameter `Lifespan Multiplier`. They will survive for that many ticks unless killed by another organism.
-When touched by a killer cell, and organism will take damage. Once it has taken as much damage as it has cells in its body, it will die. If the hyperparameter `One touch kill` is on, an organism will immediatly die when touched by a killer cell.
+When touched by a killer cell, an organism will take damage. Once it has taken as much damage as it has cells in its body, it will die. If the hyperparameter `One touch kill` is on, an organism will immediatly die when touched by a killer cell.
 
 ## Reproduction
 Once an organism has eaten as much food as it has cells in its body, it will attempt to reproduce. 
-First, offspring is formed by cloning the current organism and possibly mutating it.
+First, offspring is formed by cloning the current organism and possibly mutating it (see below).
-The offspring birth location is then chosen 2 + (number of cells) in a random direction (up, down, left, right). This ensures it will not be intersecting with its parent.
+The offspring birth location is then chosen a certain number of cells in a random direction (up, down, left, right). This number is calculated programmatically such that it is far enough away that it can't intersect with it's parent.
-Additionally, a random value between 1 and 3 is added to the location so they are not always failing to reproduce due to intersections.
+Additionally, a random value between 1 and 3 is added to the location to introduce a little variance.
-Finally, the distance between the parent and offspring maxes out at 30 cells.
+Reproduction can fail if the offspring attempts to occupy non-empty cells, like other organisms and food. If reproduction fails, the food required to produce a child is wasted.
-If reproduction fails, the food required to produce a child is wasted.
 
 ## Mutation
-Offspring can mutate in 3 different ways: lose a cell, change a cell type, or add a cell. Losing and changing are pretty self explanatory, but adding is a little more complex.
+Offspring can mutate their anatomies in 3 different ways: change a cell, lose a cell, or add a cell. Changing a cell sets a random cell to a random type. Losing a cell removes a random cell. Note that this can result in organisms with "gaps" and cells disconnected from the rest of its body. I consider this a feature, not a bug.
-The organism first selects a cell it already has in its body, then randomly grows a cell connected to that original branch cell.
+To add a cell the organism first selects a cell it already has in its body, then grows a new cell with a random type in a location adjacent to the selected cell.
 
-## Food Production and Lifespan Multiplier
+If an organism mutates, there is a 10% chance that mutation will alter the movement patterns of the organism (see below).
-To stablize ecosystems, I set up a simple equation to handle the relationship between how likely an organism is to produce food and how much time it has to do so.
-Essentially, the equation makes it so that for an organism of any given size, a single producer cell will produce as much food as cells in the organisms body. 
-For example, if an organism has 5 cells, it will live long enough so that a single producer cell will (on average) produce 5 food. This works if assuming the organism eats all 
-of the food and successfully reproduces. However, this assumtion is very often not the case, and for this reason I added a scalar value to make food production more probable.
-This is the final equation:
 
-```
+## Movement and Rotation
-p = probability of producing food (0 - 100)
+Organisms with mover cells (light blue) are permitted to move freely about the grid. Only a single mover cell is required and adding more doesn't do anything. By default, an organism selects a random direction and moves one cell per tick in that direction for a certain number of ticks. This number is called "Move range", and it can mutate over time.
-l = lifespan multiplier (how many ticks per cell an organism is given)
-x = scalar
 
-p/100 = x/l
+Organims can also rotate around a central pivot cell. This cell can never be removed by mutation, though it can change type. Movers rotate randomly when they change direction, and their rotation is not necessarily the same as their movement direction, ie, they aren't always facing the direction they are moving. Offspring of all organisms (including static ones) rotate randomly during reproduction. This rotation can be toggled in the simulation controls.
-```
 
+## Eyes and Brains
+Any organism can evolve eyes, but when an organism has both eyes and mover cells it is given a brain. The eye, unlike other cells, has a direction, which is denoted by the direction of the slit in the cell. It "looks" forward in this direction and "sees" the first non-empty cell within a certain range. It checks the type of the cell and informs the brain, which then decideds how to move. The brain can either ignore (keep moving in whatever direction), chase (move towards the observed cell), or retreat (move in the opposite direction of the observed cell). The brain maps different observed cell types to different actions. For instance, the brain will chase when it sees food and retreat when it sees a killer cell. These behaviors can mutate over time. 
 
 
-# Building and Playing
-Requirements to edit and build:
-- npm
-- webpack
-
-## Playing
-Included in this repo is an already built version of the game. You can play it simply by opening `index.html` in your browser.
-
 ## Building
 If you want to change the source code and then play, use any of the following commands to build the project:
 To build minified: `npm run build`
 To build in dev mode: `npm run build-dev`
 To build in dev/watch mode: `npm run build-watch`
-You can then open `index.html` in your browser.
+You can then open `dist/index.html` in your browser.