CityPlannerEnv: Modular Urban Simulation

• CityPlannerEnv is a modular simulation environment that formalizes urban growth through spatial agent-based systems and procedural design.
• It features a four-stage pipeline—terrain initialization, road network growth, land-use assignment, and emergent urbanization—driving complex city morphology.
• The platform offers an API for closed-loop interaction, supporting reinforcement learning, generative modeling, and urban policy planning.

CityPlannerEnv is a modular, simulation-ready environment specification for procedural, automated, and multi-agent city planning, designed to support both generative city modeling and reinforcement learning research. It formalizes city growth via spatial agent-based systems, integrates exogenous data and policy objectives, and exposes an API for closed-loop interaction, enabling both open-ended procedural urbanism and integration with planning, evaluation, or vision-language agent toolchains (Lechner et al., 25 Jul 2025).

1. Architectural Overview and Environment Pipeline

At its core, CityPlannerEnv structures the city as a dynamic patch grid, initializes from a digital elevation model and hydrological mask, and orchestrates urban growth through interacting agent classes. The environment’s pipeline consists of four major stages:

1. Terrain & Patch Initialization: Ingests a heightmap and water mask over a rectangular grid. Each patch $p$ encodes local state: elevation $e(p) \in \mathbb{R}$, water flag $W(p) \in \{0,1\}$, road distance $d_\text{road}(p)=\infty$, building density $\rho(p)=0$, and empty land-use.
2. Road Network Growth: Road-extender and -connector agents sequentially lay tertiary (then, later, arterial) road segments. Extenders search for underserviced patches and path back to an existing network node, minimizing a cost function that blends spatial and elevation penalties. Connectors link existing roads to reduce transit inefficiencies, subject to loopiness constraints.
3. Land-Use Assignment and Building Placement: Developer agents (e.g., residential, commercial) scout road-adjacent patches, compute value functions $V(p)$ parameterized by local context, and allocate building plots if the development increases aggregate land value. Density updates and speculator agents are also modeled.
4. Emergent Urbanization Loop: Patch densities evolve in response to accumulated development; growth phases (village, town, city, metropolis) are orchestrated via agent scheduling, model parameters, or exogenous triggers (e.g., built area thresholds).

This agent-based methodology yields complex city morphology, supports intervention at any point in the temporal growth trajectory, and enables decomposition into isolated submodules for benchmarking, visualization, or policy planning (Lechner et al., 25 Jul 2025).

2. Formal Agent System and Rule Sets

CityPlannerEnv operationalizes a range of agent classes—each with parameterizable and deterministic behavioral rule sets, informing the emergence of urban form from micro-decisions:

• Patch (“environment agent”): Encapsulates local, reactive features (elevation, road access, reservation status). Patches indirectly mediate agent coordination.
• Road-Extender Agent: Identifies remote patches and computes minimum-cost paths for network extension; constrained by allowable road density, elevation gain, and intersection spacing. Admits an optimization function:

$$C(P) = \sum_{i=1}^k (\lambda_d \cdot \text{dist}(p_{i-1}, p_i) + \lambda_e \cdot |e(p_i) - e(p_{i-1})|)$$

• Road-Connector Agent: Proposes direct connections to close inefficient network loops, conditional on the discrepancy between actual network path length and grid (Manhattan) distance exceeding a threshold parameter $k$.
• Developer Agents: Calculate discrete land value functions (detailed below), propose plots, and commit development if value margins are positive.
• Speculator Agents (planned): Reserve tracts for sequenced development, guiding resource allocation and competition among developer agents via reserved flags.

Agents interact directly only with local patch fields; all higher-order behaviors, including social and spatial clustering, commercial vs residential stratification, and morphology, are emergent properties of indirect state coupling and rule interaction (Lechner et al., 25 Jul 2025).

3. Mathematical Models for Urban Morphodynamics

Core decision-making is formalized through mathematical models for land value, accessibility, path cost, and density evolution:

• Land Value Functions:
  • Residential:

  $$V_\mathrm{res}(p) = -\alpha_r R(p) + \beta_r E(p) + \gamma_r (1-W(p)) + \delta_r \mathrm{ClusterBonus}(p)$$ - Commercial:

  $$V_\mathrm{com}(p) = +\alpha_c R(p) + \beta_c E(p) + \gamma_c (1-W(p)) + \delta_c \mathrm{ClusterBonus}(p)$$

  Where $R(p)$ is local road density, $E(p)$ is centered elevation, and $\mathrm{ClusterBonus}$ computes local plot clustering differential.

• Density Evolution:

$$\rho_{t+1}(p) = \rho_t(p) + r V(p) \Bigl(1 - \frac{\rho_t(p)}{\rho_\text{max}}\Bigr)$$

• Network Constraints: Emphasize loop limitation, service reach, and settable orthogonality via $k$ and grid-bias parameters. Road segments are regulated for connectivity and topographic realism.

This formal underpinning enables parameter introspection—for instance, tuning $\alpha_c$ versus $\alpha_r$ accentuates commercial clustering, while $k$ manipulates network loopiness—and facilitates the mapping of design parameters to emergent urban typology (Lechner et al., 25 Jul 2025).

4. Data Structures, Algorithms, and Execution Flow

The environment is realized using explicit, multi-layer data models and staged procedural logic:

• World Representation: Patch grids indexed over $[M][N]$, extended with road-graph adjacency lists for efficient spatial-querying and network traversal.
• Agent State: Each agent instance carries type, position, roaming radius, and class-specific parameters.
• Main Simulation Loop: Iterative execution of agent actions, patch state update (e.g., recompute $d_\text{road}$ using BFS), density evolution, and agent spawning. Reproducibility is enhanced by deterministic agent random-seed isolation.
• Action Modalities: Direct (agent instantiation, parameter modulation, forced edits) and indirect (terrain modifications, stochasticity injection).
• Observations: Multi-channel feature maps (elevation, water, $d_\text{road}$, density, categorical land-use) plus agent-centric lists.

The modular kernel allows integration as either an open-ended procedural generator or as an RL/IL planning substrate, admitting both high-level interventions and low-level, cell-wise manipulation (Lechner et al., 25 Jul 2025).

5. Parameterization, Emergent Properties, and Growth Phases

CityPlannerEnv is highly parameterizable—agent counts, growth thresholds, road/land-use valuation weights, plot size, and bias coefficients are all tunable at runtime. This flexibility defines the city’s emergent morphology and supports staged, realistic urban agglomeration:

• Village phase: Sparse agents, minimal connectivity, simple land-use.
• Town phase: Connector activation, district-level plot speculation, increased network complexity.
• City phase: Introduction of hierarchical road networks, higher-density development, functional-zone heterogeneity.
• Metropolis phase: Density evolution dominates; “urban planner” agents may enact superordinate top-down plans.

Transitions can be triggered by built area thresholds or explicit temporal schedules. Logging and snapshot rollback are recommended for phase-specific design or RL-evaluation (Lechner et al., 25 Jul 2025).

6. RL/Planning API and Interoperability

The environment exposes a formal API for external control and agent-in-the-loop learning:

• reset(terrain_map, high_level_params): Resets state with deterministic initialization.
• step(action): Advances the simulation, applying globally or locally specified interventions.
• Observations: Consist of map tensors and agent features.
• Action space: Includes spawn/kill agent commands, parameter tuning, direct interventions, and higher-order plot/road commitment.
• Reward signals: Expose urban plausibility (compactness, connectivity, service coverage) and support complex, user-specified objectives, e.g., maximization of spatial adjacencies or minimization of travel time. Dense and sparse reward structures are both supported.

The environment’s interoperability suite admits higher-level models (LLMs, VLMs), custom evaluation, and integration into comparative benchmarks for urban policy learning or generative design (Lechner et al., 25 Jul 2025).

7. Implementation Guidelines and Use-case Extensions

For scalable implementation and robust experimentation:

• Incremental computation: BFS-based nearest-road updates and spatial indexing (e.g., quad-trees) are recommended for O(1) patch access.
• Agent randomization: Isolation of randomness per agent instance ensures reproducibility.
• Parameter exploration: UI exposure of land-use and road network factor weights is recommended for interpretability and controlled experimentation.
• Growth stage logging: Intermediate city states should be stored to enable phase rollback and sensitivity analysis.

CityPlannerEnv serves as a reference blueprint for procedural city modelers, RL researchers, and urban simulation practitioners, enabling diverse studies in emergent urbanism, planning policy optimization, and city morphology analysis. The environment is positioned as a canonical, generalizable platform for procedural city modeling (Lechner et al., 25 Jul 2025).