> ## Documentation Index
> Fetch the complete documentation index at: https://salesforce-ai-economist.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> 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) |

> [!TIP]
>
> 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()`:

```python reset skill sampling theme={null}
# 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

```python scenario config theme={null}
env_config = {
    "components": [
        {
            "Gather": {
                "move_labor": 1.0,
                "collect_labor": 1.0,
                "skill_dist": "pareto",
            }
        }
    ]
}
```

```python accessing the log theme={null}
env.reset()
obs, rew, done, info = env.step(actions)

component = env.world.components["Gather"]
gather_log = component.get_dense_log()
# gather_log[-1] -> events from the last timestep
# e.g., [{"agent": 0, "resource": "Wood", "n": 1, "loc": [3, 7]}, ...]
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.