Stab at item/transition overview

README.md

@@ -495,7 +495,38 @@ Default is False.
 
 Which Bot class to run. Default: `RandomBot`.
 
-## Item and Item Transition Configuration
+## Items and Transitions
+
+Griduniverse provides a configuration syntax (see game_config.yml) for defining custom
+objects that will be added to the grid world, and transitions that can be triggered by
+players, either independently or in cooperation, that extract some value from the items
+they're interacting with, and transform items of one type into another type. This makes
+it possible for the experiment author to create pathways for techological evolution in
+the game. For example, a `wild_carrot_plant` may only yield a `wild_carrot` if the
+`wild_carrot`` can be cut from the tree using a `sharpened_stone`, and only unsharpened
+`stone`s exist in the grid world's intial state. Two players might need to collaborate
+to sharpen a plain `stone` against a `big_hard_rock` to transition the `stone` into
+a `sharpened_stone`, which can then be used to harvest a `wild_carrot` from the `wild_carrot_plant`.
+
+Transitions are modeled as a pair of states: prior to the transition execution, and after
+the transition has finished. Each state has two sub-componenents: the item
+in the possesion of the player executing the transtion, and the item in the grid block
+they are currently occupy during the transition.
+
+Prior to transition execution:
+  - `actor_start` - the ID of the item the player must be holding for the transition to be available
+  - `target_start` - the ID of the item that must exist on the player's current grid block for the
+     transition to be available
+
+After transition execution:
+  - `actor_end` - the ID of the item that will exist in the player's hand after the transition
+     has executed
+  - `target_end` - the ID of the item left in the player's grid block after the transition executes
+
+Note that any of these values may be `null`. For example, a transition may result in the item
+in the player's current grid block to be consumed, leaving nothing behind.
+
+### Configuration
 
 See detailed explanations for each value for items and transitions on the item_defaults
 and transition_defaults definitions in game_config.yml.