Tutorial: Regions in Downbeat

A region is a geographic zone that contains other things. For downbeat, the region is the lobby—a spatial container for the entrance area and any support spaces.

This tutorial mirrors TUTORIAL-areas.md but focuses on region-level design for zine scenarios.

---

The Minimal Region Document

apiVersion: net.plantange/v1
kind: simulation.region

meta:
  title: Lobby Region
  name:
    common:
      en: lobby
  uuid: 019d8202-e322-76c6-1f0a2b3c4d5e6fa7

That's the absolute minimum. The Rust parser requires apiVersion, kind, meta.title, and meta.uuid.

---

Optional Blocks

biome

Describes the ecosystem and sensory environment:

biome:
  terrain_class: urban
  temperature: 18.5
  light_level: 0.85
  ambient_sound: 0.4
  odor_profile:
    stone: 0.3
    air: 0.7

For downbeat, use urban and moderate values (neutral environment).

features

References the areas contained in this region:

features:
  - spec: 019d8202-e322-76c6-1f0a2b3c4d5e6fa2 # entrance area uuid

The uuid must match meta.uuid in the area document exactly.

surface

Declares the physical extent of the region:

surface:
  scale: medium
  geometry: rectangle
  bounds:
    x_km: 1.0
    y_km: 0.5

For downbeat (a lobby), use small scale and rectangle geometry.

ecology

Declares native species and ambient life:

ecology:
  biota:
    - species: human
      density: 0.3
      role: citizen
    - species: bird
      density: 0.05
      role: ambient

For downbeat (entrance only), keep ecology minimal or omit.

---

A Full Example — Lobby Region

apiVersion: net.plantange/v1
kind: simulation.region

meta:
  title: Lobby Region
  description:
    common:
      en: "The grand entrance lobby where all players begin their journey."
  name:
    common:
      en: lobby
  uuid: 019d8202-e322-76c6-1f0a2b3c4d5e6fa7

surface:
  scale: medium
  geometry: rectangle
  bounds:
    x_km: 1.5
    y_km: 1.0

biome:
  terrain_class: urban
  temperature: 18.5
  light_level: 0.85
  ambient_sound: 0.4
  odor_profile:
    stone: 0.3
    air: 0.7

features:
  - spec: 019d8202-e322-76c6-1f0a2b3c4d5e6fa2 # entrance area
  - spec: 019d8202-e322-76c6-1f0a2b3c4d5e6fa8 # antechamber area (optional)

ecology:
  biota:
    - species: human
      density: 0.2
      role: guest

---

Region vs Area — When to Use Which

Use simulation.region when…	Use simulation.area when…
It's a geographic zone or container	It's a specific named place
It defines terrain, climate, ecology	It's where agents concretely inhabit
It may contain multiple areas via features:	It may have a corporation/institution
It is a parent in the world graph	It is a leaf in the world graph

For downbeat:

• Region (lobby) = the overall entrance zone
• Area (entrance) = the specific hall where the zine plays
• Area (antechamber) = staging zone for NPCs (optional)

---

Common Patterns for Zine Scenarios

Minimal Lobby

If you want the smallest possible region:

apiVersion: net.plantange/v1
kind: simulation.region

meta:
  title: Entrance Lobby
  name:
    common:
      en: lobby
  uuid: <unique uuid>

surface:
  scale: small
  geometry: point

features:
  - spec: <entrance area uuid>

This is perfectly valid. Regions don't require biome, ecology, or bounds. Add fields as content richness grows.

Interconnected Lobby

If multiple entry points feed into a shared lobby:

apiVersion: net.plantange/v1
kind: simulation.region

meta:
  title: Grand Hall
  name:
    common:
      en: grand_hall
  uuid: <unique uuid>

features:
  - spec: <north entrance area uuid>
  - spec: <south entrance area uuid>
  - spec: <central gathering area uuid>

The zine panel will show all areas' characters mixed together. This is useful for multi-gateway entrances or festival scenarios.

---

Key Design Principle

For zine scenarios, the region is a container, not a visual space.

The zine panel does not render the region itself. It renders characters from the areas within the region. Keep regions simple and focus your authoring effort on areas and choreography.

---

Common Mistakes

Mistake	Symptom	Fix
Missing meta.uuid	Parser error	Add a unique UUID under meta:
kind: simulation.area in the region/ folder	Area handler rejects it	Change to kind: simulation.region
Features list references non-existent area	Warning logged, area missing	Ensure area uuid matches meta.uuid in area document exactly
meta.name locale map missing common.en	Name resolves as empty	Add common: en: <name> inside the map
Complex ecology defined but unused	Clutter; no runtime effect yet	Keep ecology minimal for now; add detail when game uses ecology data