Move

Component enabling mobile agents to move around the world and collect resources

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.

Value	Behavior
"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 index	Meaning
0	No-op — agent stays in place
1	Move left (column − 1)
2	Move right (column + 1)
3	Move up (row − 1)
4	Move 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

scenario config

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