1 files changed, 53 insertions, 0 deletions
diff --git a/src/world/README.md b/src/world/README.md
new file mode 100644
index 0000000..a88eadc
--- /dev/null
+++ b/src/world/README.md
@@ -0,0 +1,53 @@
+# world
+
+The world is composed of a cell lattice. Each cell can contain a specific type of cell, and these cells
+evolve according to fixed, regular rules.
+
+Agents exist on top of the cell lattice. They occupy specific cell locations, but those locations are
+otherwise considered empty. Agents exist independent of the cells and evolve independent of them, though of
+course they are intertwined.
+
+Time step process:
+
+ * Agents update internal state and propose moves.
+ * World updates
+ * Agent moves are resolved in the new world, and agent status is updated.
+ * World state is updated to include agents.
+
+Cell types:
+*(all cells, except for Empties and Flags, count as GoL living)*
+
+ * Empty (territory-colored, GoL dead)
+ * Immutable
+ * Mutable
+ * Active (GoL living)
+ * Flag
+
+Agent aspects: (64)
+  * team (4)
+  * orientation (4)
+  * mobile/frozen (2)
+  * has flag (2)
+  * identity (3-channel)
+
+Agents have *internal state* corresponding to the state of their internal neurons (and roughly corresponding to their memories and experiences) and *status*, which refers to things like their current orientation, position, and mobility.
+
+
+Agent senses:
+ * Hearing (inverse square, infinite range)
+ * Sight (2D top-down, see further ahead than behind or to the sides, 7-channel)
+ * Match timer
+ * Epoch timer
+
+Agent actions:
+ * Move forward/backward
+ * Turn left/right
+ * Place mutable
+ * Trigger mutable -> active (5x5 square ahead of agent)
+ * Play frozen
+ * Unfreeze
+ * Take flag
+ * Drop flag (immediately ahead of agent)
+
+
+ When carrying a flag, an agent counts as a flag tile (and other agents can steal the flag from them!). Otherwise, an agent counts as an empty tile.