Build

Component enabling agents to construct house landmarks using stone and wood

The Build component (registry name "Build") allows BasicMobileAgent instances to spend one unit each of Wood and Stone to construct a House landmark on their current tile, receiving a coin payment in return. Building has a configurable labor cost and supports heterogeneous skill levels that modify each agent’s payout.

The agent must be standing on an empty tile — no existing landmark or resource — and must possess the required resources in their inventory before the build action takes effect.

Constructor parameters

payment · int · default: "10"

Base amount of Coin an agent receives for successfully building a house. Must be >= 0.

payment_max_skill_multiplier · int · default: "1"

Upper bound on the skill multiplier applied to payment. Must be >= 1. When set above 1, skilled agents can earn up to payment * payment_max_skill_multiplier per build.

skill_dist · string · default: "none"

Distribution used to sample each agent’s build skill at episode reset.

Value	Behavior
"none"	All agents use a multiplier of 1 (uniform skill)
"pareto"	Multipliers sampled from a Pareto distribution
"lognormal"	Multipliers sampled from a log-normal distribution

build_labor · float · default: "10.0"

Labor units charged to agent.state["endogenous"]["Labor"] each time a house is successfully built. Must be >= 0.

Resource cost

Building a house always consumes exactly:

Resource	Amount
Wood	1 unit
Stone	1 unit

These costs are fixed and defined in self.resource_cost = {"Wood": 1, "Stone": 1}.

Required world entities: Wood, Stone, Coin, House, Labor.

Action space

This component adds 1 discrete action for each BasicMobileAgent:

Action index	Meaning
0	No-op — do nothing
1	Attempt to build a house at the current tile

Building sequence

When an agent takes action 1, component_step() calls agent_can_build() to verify all preconditions, then:

1. Deducts 1 Wood and 1 Stone from the agent’s inventory.
2. Calls world.create_landmark("House", row, col, agent.idx) to place the landmark.
3. Adds agent.state["build_payment"] (the skill-adjusted coin amount) to the agent’s inventory.
4. Charges build_labor to agent.state["endogenous"]["Labor"].

Build preconditions

agent_can_build() returns True only when all three conditions hold:

• The agent has >= 1 Wood in inventory.
• The agent has >= 1 Stone in inventory.
• The current tile contains no existing resource or landmark.

Agent state fields

This component adds the following state fields to every BasicMobileAgent:

build_payment · float

Effective coin payout for the next build action. Initialized to payment and updated each episode reset according to the sampled skill multiplier.

build_skill · float

Raw sampled skill value (before clamping). Initialized to 1.

Observations

Agents observe their own normalized build skill. The planner receives nothing from this component.

build_payment · float

Agent’s current build_payment normalized by the base payment value.

build_skill · float

The raw sampled skill value stored in sampled_skills[agent.idx].

Action masks

The single build action is masked to 0 whenever agent_can_build() returns False (insufficient resources or tile already occupied). It is unmasked (1) otherwise.

Metrics

get_metrics() returns a dict with per-agent build counts and a total:

{agent_idx}/n_builds · int

Number of successful builds by this agent over the episode.

total_builds · int

Total number of House landmarks currently on the map (world.maps.get("House") > 0).

Dense log

get_dense_log() returns a list (one entry per timestep) of build-event lists. Each build event is a dict:

builder · int

Agent index that performed the build.

loc · ndarray

[row, col] location where the house was placed.

income · float

Coin payment received for this build.

Skill sampling

At every episode reset additional_reset_steps() re-samples each agent’s skill:

skill sampling

PMSM = payment_max_skill_multiplier

# skill_dist == "pareto"
sampled_skill = np.random.pareto(4)
pay_rate = np.minimum(PMSM, (PMSM - 1) * sampled_skill + 1)

# skill_dist == "lognormal"
sampled_skill = np.random.lognormal(-1, 0.5)
pay_rate = np.minimum(PMSM, (PMSM - 1) * sampled_skill + 1)

agent.state["build_payment"] = float(pay_rate * payment)
agent.state["build_skill"] = float(sampled_skill)

Example usage

scenario config

env_config = {
    "components": [
        {
            "Build": {
                "payment": 10,
                "payment_max_skill_multiplier": 3,
                "skill_dist": "lognormal",
                "build_labor": 10.0,
            }
        }
    ]
}