Add detailed documentation of item config variables

dlgr/griduniverse/game_config.yml

@@ -1,6 +1,18 @@
 ---
 player_config:
+  # The distribution model used when spawning players on the grid.
+  # Griduniverse provides a pre-defined set of distribution options:
+  #    - random
+  #    - sinusoidal
+  #    - horizontal
+  #    - vertical
+  #    - edge_bias
+  #    - center_bias
+  #
+  # See the distributions.py module for their implementations
   probability_distribution: "random"
+
+  # Griduniverse uses different colors to represent player groups or teams
   available_colors:
     BLUE: [0.50, 0.86, 1.00]
     YELLOW: [1.00, 0.86, 0.50]
@@ -9,26 +21,110 @@ player_config:
     PURPLE: [0.85, 0.60, 0.85]
     TEAL: [0.77, 0.96, 0.90]
 
+
 item_defaults:
+  # Each item definition must include a unique item_id. This actual value doesn't matter,
+  # though an easily identifiable label can be helpful in developing and
+  # debugging your experiment
   item_id: default
+
+  # How many instances of this item should the world initially include? If "respawn" is true
+  # the world will regenerate replacements for consumed instances to maintain this
+  # number of instances.
   item_count: 8
+
+  # How many calories does a single instance provide when a player consumes it?
+  # In the simple case, the consuming player will get all the caloric benefit from
+  # items they consume, but there are also options for dividing this benefit among
+  # other players (see public_good and public_good_multiplier, below)
   calories: 0
+
+  # Can a player occupy the grid block this item is sitting on?
   crossable: true
+
+  # Does a player need to explicitly interact with this item via the action button
+  # when they co-occupy its grid block, or do the immediately consume the item
+  # without needing to take any explicit action?
   interactive: false
+
+  # How rapidly does this item progress through its maturation lifecycle in
+  # WHAT UNITS???
   maturation_speed: 0.0
+
+  # At what level of maturity ("ripeness") is this item ready for consumption?
+  # Prior to reaching this threshold, a player may be able to co-occupy the same
+  # grid block, but not consume the item.
   maturation_threshold: 0.0
+
+  # Some items can be consumed (or otherwise used) more than once; for example
+  # a berry bush that provides multiple "servings" of berries before it's exhausted.
   n_uses: 1
+
+  # Friendly name of the item that may be displayed to the player.
   name: Food
+
+  # Can this item be "planted" (added to the gridworld) by the players themselves?
   plantable: false
+
+  # If this item is plantable (see above), how many points/calories are deducted from
+  # the player's score for each planting event they trigger?
   planting_cost: 1
+
+  # Can this item be picked up and carried to another location by the player?
   portable: true
+
+  # The distribution model used when spawning instances of this item on the grid.
+  # Griduniverse provides a pre-defined set of distribution options:
+  #    - random
+  #    - sinusoidal
+  #    - horizontal
+  #    - vertical
+  #    - edge_bias
+  #    - center_bias
+  #
+  # See the distributions.py module for their implementations
   probability_distribution: "random"
+
+  # The number of calories to be given to all *other players* when a player consumes
+  # an instance of this item.
+  # If this value is non-zero, public_good_multiplier will be ignored.
   public_good: 0.0
+
+  # Basis from computing calories credited to all *other players* when a player
+  # consumes an instance of this item. The credit will be equal to:
+  #     calories * public_good_multiplier / number of players
+  #
+  # Note that unless public_good is 0, this value will be ignored.
   public_good_multiplier: 0.0
+
+  # Should a replacement of this same item type be immediately added to the gridworld
+  # when an instance is consumed?
   respawn: false
+
+  # If the current number of instances of this item in the gridworld exceeds the
+  # configured item_count, should we prune items to limit the total to item_count?
+  #
+  # Note that item_count is potentially dynamic, changing over time based on
+  # seasonal_growth_rate and spawn_rate (see below).
   limit_quantity: false
+
+  # Degree to which the quantity of this item should fluctuate based on "seasons"
+  # (expressed as alternating rounds of the game, so there are just two seasons).
+  # This value is an *exponential* multiplier.
   seasonal_growth_rate: 1.0
+
+  # At what rate should additional instances of this item be added to the gridworld?
+  # A rate of 1.0 means that the target number of items (item_count) will not grow over
+  # time, but a large value will result in a steadily growing item_count.
   spawn_rate: 1.0
+
+  # Visual representation of this item in the UI.
+  # This value can be any of:
+  #    - A single hex color value
+  #    - A comma-separated pair of hex colors representing the items immature and mature
+  #      states
+  #    - A unicode emoji "🍓"
+  #    - The path of an image in within the images/ folder ("sprites/strawberry.png")
   sprite: "#8a9b0f,#7a6b54"
 
 transition_defaults: