Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/salesforce/ai-economist/llms.txt

Use this file to discover all available pages before exploring further.

The Gather component (registered as "Gather") allows BasicMobileAgent instances to navigate the world grid in four cardinal directions and automatically collect resources when they land on populated resource tiles. Movement and collection each incur a configurable labor cost, and agents can optionally have heterogeneous collection skills sampled from statistical distributions.
The class name is Gather and its registry name is "Gather". It applies only to agents of subclass BasicMobileAgent.

​
Constructor parameters

​
move_labor
float
default:"1.0"
Labor cost incurred each time an agent successfully moves to an adjacent tile. Must be >= 0.
​
collect_labor
float
default:"1.0"
Additional labor cost incurred on top of movement cost when the agent lands on a tile containing a resource and triggers collection. Must be >= 0.
​
skill_dist
string
default:"none"
Distribution used to sample each agent’s bonus_gather_prob at episode reset.
ValueBehavior
"none"All agents receive bonus_gather_prob = 0.0 (no bonus)
"pareto"Skills sampled from a Pareto distribution, clipped and normalized to [0, 1]
"lognormal"Skills sampled from a log-normal distribution, clipped and normalized to [0, 1]

​
Action space

This component adds 4 discrete movement actions for each BasicMobileAgent:
Action indexMeaning
0No-op — agent stays in place
1Move left (column − 1)
2Move right (column + 1)
3Move up (row − 1)
4Move down (row + 1)
Actions targeting a tile that is already occupied by another agent or is inaccessible are silently ignored — the agent remains in place and no labor is charged.

​
Movement and resource collection

On each timestep the component iterates over all agents in a random order and:
  1. Resolves the chosen direction by calling world.set_agent_loc(). If the target tile is occupied or out of bounds the agent stays put.
  2. Charges move_labor to agent.state["endogenous"]["Labor"] if the agent actually moved.
  3. Checks every resource at the agent’s final tile via world.location_resources().
  4. For each resource with health >= 1, collects 1 unit (or 2 if rand() < agent.state["bonus_gather_prob"]), calls world.consume_resource(), and charges collect_labor.
Required world entities: Coin, House, Labor.

​
Collection skill

Each agent carries a bonus_gather_prob state field (float in [0, 1]). When this value is non-zero, each collection event has a chance of yielding an extra unit of the resource at no extra labor cost. Skills are re-sampled at the start of every episode via additional_reset_steps():
reset skill sampling
# skill_dist == "pareto"
bonus_rate = np.minimum(2, np.random.pareto(3)) / 2

# skill_dist == "lognormal"
bonus_rate = np.minimum(2, np.random.lognormal(-2.022, 0.938)) / 2

​
Observations

Each agent observes its own collection skill. The planner receives nothing from this component.
​
bonus_gather_prob
float
The agent’s probability of collecting a bonus resource unit on each gather event. Keyed by agent index string.

​
Action masks

Generated every step, the mask for each of the 4 movement directions is 1 only if the target tile is both unoccupied and accessible (according to world.maps.unoccupied and world.maps.accessibility). No-op (index 0) is always allowed.

​
Dense log

get_dense_log() returns a list of gather events — one list per timestep. Each gather event is a dict:
​
agent
int
Index of the agent that collected the resource.
​
resource
string
Name of the collected resource (e.g., "Wood", "Stone").
​
n
int
Number of units collected (1 or 2).
​
loc
list
[row, col] of the tile where collection occurred.

​
Example usage

env_config = {
    "components": [
        {
            "Gather": {
                "move_labor": 1.0,
                "collect_labor": 1.0,
                "skill_dist": "pareto",
            }
        }
    ]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us