Skip to content

Plantangenet Regions & Areas

Introduction

Welcome. This document walks you through the core concepts behind the Region and Area systems in Plantangenet.

The goal is simple: give you a mental model you can actually use before you dive into the code. This is not meant to be exhaustive. It is meant to make the system legible.

If you remember nothing else, remember this:

  • Regions are the world outside
  • Areas are the spaces inside
  • Everything evolves through shared state

Once that clicks, everything else becomes detail instead of confusion.

With that in mind, here’s how the system is structured.

Big Picture

Plantangenet simulates a world using two complementary layers that deliberately do different jobs.

Regions

Regions represent physical territory, modeled as a grid of cells where each cell has a position, properties, and relationships to neighboring cells.

Regions answer questions like:

  • What does the land look like?
  • Where is water available?
  • How are resources distributed?
  • How does the environment change over time?

You can think of a region as the "map that exists whether anyone is there or not."

Areas

Areas represent contained environments inside a region.

They are not made of cells. Instead, they are defined by shape and scale, and describe conditions and possible activities.

Areas answer questions like:

  • What can happen here?
  • What conditions exist in this space?
  • What does it feel like to be here?
  • How do those conditions evolve?

You can think of an area as "a place where something specific is happening."

Regions: The World Layer

What is a Region?

A Region is a spatial simulation.

It is composed of:

  • A grid of cells
  • Coordinates for each cell
  • Adjacency between cells

Each cell represents a unit of land with its own local properties, and taken together they form a continuous piece of territory.

How Regions Are Created

Regions are generated from three inputs:

  1. A specification (YAML)
  2. A deterministic seed
  3. A compiler

The specification describes intent.

The seed introduces controlled variation.

The compiler turns both into something concrete.

The compiler produces:

  • Cells (the terrain)
  • Subdivisions (zones like agriculture or watershed)
  • Location mappings
  • Initial environmental state

This process is deterministic. The same inputs always produce the same region.

That property is important for debugging, replay, and reproducibility.

Subdivisions

Regions are partitioned into functional zones such as:

  • Settlement core
  • Agriculture belt
  • Watershed
  • Conservation zone
  • Industrial zone

These are not separate systems.

They are structured groupings of cells with different default conditions and intended roles.

Subdivisions help organize behavior and give meaning to different parts of the region without changing the underlying grid.

For example, a watershed subdivision might maintain high water availability and low land pressure, while an agriculture belt prioritizes soil fertility and moderate water access to support crop production.

Environment Simulation

Regions evolve over time through an environment engine.

Each frame (tick):

  • The engine reads the current state
  • It computes changes
  • It emits updates

These updates are applied in a controlled way after computation completes.

The engine never mutates state directly. This separation allows:

  • Deterministic updates
  • Easier debugging
  • Safe composition of multiple systems

Policy System

Regions can also run policy logic on top of environmental simulation.

Policies:

  • Observe state
  • Trigger events (scarcity, surplus, failure)
  • Enforce constraints

This introduces higher-level behavior such as governance, rules, and consequences.

If the environment engine is "physics," policy is closer to "law."

Areas: The Interior Layer

What is an Area?

An Area is a contained environment.

It is defined by:

  • Shape (point, circle, rectangle)
  • Scale (small, medium, large, epic)

Areas do not have cells.

They are not spatial grids.

They do not model terrain.

Instead, they represent bounded environments with meaning.

What Areas Contain

Areas define three primary things.

1. Environment Fields

Examples include:

  • Temperature
  • Atmosphere
  • Lighting
  • Sensory conditions

These describe what it feels like to exist inside the area.

2. Affordances

Affordances describe what can be done in the area.

Examples:

  • Crafting
  • Storage
  • Interaction
  • Processing

They define possibilities, not actions themselves.

An affordance becomes meaningful when something uses it.

3. Constraints

Constraints define limits such as:

  • Capacity
  • Allowed content types

These are declarations.

They describe intent and expectation, but are not automatically enforced unless another system chooses to enforce them.

Area Simulation

Areas also evolve over time using an environment engine.

The engine:

  • Reads current state
  • Emits updates

These updates influence environment fields and can indirectly affect affordances.

Unlike regions, areas do not have:

  • Spatial adjacency
  • Subdivisions
  • Built-in policy systems

They are simpler by design.

How Regions and Areas Connect

Common misunderstanding: Areas are not mapped onto specific region cells. They belong to a region, but they are not embedded into the region’s grid.

Common misunderstanding: Areas are not mapped onto specific region cells. They belong to a region, but they are not embedded into the region’s grid.

The relationship is intentionally minimal.

  • Each Area belongs to exactly one Region
  • This is represented by a region_id

There is no direct embedding of areas into region cells.

This separation avoids coupling interior logic to terrain logic.

Regions manage territory.

Areas manage experiences.

If you need to relate them spatially, that happens through separate systems (such as location mapping), not by merging their models.

Shared Concept: State ("Chem")

Both Regions and Areas use the same underlying model for dynamic state.

State is stored as key-value pairs, often referred to as "chem paths." The term "chem" comes from the idea of chemistry: small, composable substances that combine to produce complex behavior; in the system, these are time-sampled values provided each frame for agents to read and act on.

Examples:

  • water_table
  • soil_fertility
  • temperature
  • affordance.salience

Engines:

  • Read these values
  • Compute changes
  • Emit updates

This model is intentionally flexible.

New concepts can be introduced simply by adding new paths, without modifying core structures.

The tradeoff is that meaning lives in conventions rather than strict schemas.

Compilation Model

Both Regions and Areas follow a similar pipeline:

  1. Parse a spec (YAML)
  2. Convert to a graph representation
  3. Compile into runtime artifacts

The graph stage allows relationships and dependencies to be expressed cleanly.

The compilation stage produces concrete, ready-to-run structures.

The result is a fully initialized, deterministic system ready for simulation.

A Simple Lifecycle Walkthrough

To make this more concrete, here is a simplified lifecycle:

Initialization phase:

  1. A region spec is loaded
  2. A seed is applied
  3. The region is compiled into cells and subdivisions
  4. Areas are registered against the region

Runtime loop:

  1. Each tick:
  2. Region environment engine runs
  3. Region policies execute
  4. Area environment engines run
  5. Updates are applied

Over time, the world evolves through repeated ticks.

Key Design Principles

Separation of Concerns

  • Regions handle space
  • Areas handle contained environments

These responsibilities are intentionally split.

Determinism

Given the same inputs, the system produces the same outputs.

This makes simulation predictable and testable.

Engine-Based Evolution

All changes happen through engines that emit updates.

No system directly mutates shared state during computation.

Extensibility

New behaviors can be added via:

  • Brands
  • Engines
  • Generators

The system is designed to grow without rewriting core components.

Mental Model Summary

If you are trying to reason about the system, think in these terms:

  • Region = a living map
  • Area = a room with conditions and possibilities
  • State = named values that change over time

If something feels confusing, map it back to one of these three ideas.

That usually clears things up quickly.

Where to Go Next

To go deeper:

  • Look at RegionSpec and AreaSpec examples
  • Trace compile_region and area compilation
  • Inspect environment engine implementations

At that point, the code should line up cleanly with the concepts described here.

If it doesn’t, that’s a sign the abstraction needs tightening—not that you’re missing something.