Global World Architecture & World Building

1. Architecture overview

The sim is spatially sharded for performance: region workers own chunk sets under orchestrator control. This is not a single monolithic process for the entire world.

2. High-level topology

┌──────────────────────────────────────────────────────────────────────────┐
│                         CONTROL PLANE                                    │
│  Accounts · economy ledger · world catalog · segment review/deploy API     │
│  Auth · bans · audit · broker indices · persistence orchestration        │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │
┌───────────────────────────────▼──────────────────────────────────────────┐
│                      WORLD BUILD SERVICE                                 │
│  Segment draft · validate · review · approve · publish · deploy          │
│  CLI + agent API · community permissions · versioned world manifest      │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │ published segments
┌───────────────────────────────▼──────────────────────────────────────────┐
│                     WORLD SIMULATION CLUSTER                             │
│  Gateway (QUIC) · region assignment · cross-region interest handoff        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐                       │
│  │  Region R1  │  │  Region R2  │  │  Region R3  │  … (spatial workers) │
│  │  tick loop  │  │  tick loop  │  │  tick loop  │                       │
│  └─────────────┘  └─────────────┘  └─────────────┘                       │
│         └──────────────── one continuous world space ─────────────────┘    │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │
                    ┌───────────▼───────────┐
                    │  TUI / future clients │
                    └───────────────────────┘

Chat, party, and economy live on the control plane and shared world state. Region crossing is an internal gateway handoff (milliseconds).

3. World space model

3.1 Coordinates

WorldCoord { x, y, z, w, t }

Players experience one world — walk, sail, dig, or fly within the deployment's vertical limits.

3.2 Vertical strata (decided — deep & high)

The world is very tall and very deep. Limits live in world_manifest.yaml (tunable, not hardcoded in Rust).

Design intent: players can dig far and fly high; cartography and AOI use full z extent per (x,y) column (06). Water is a volume (terrain + fluid zone), not a single plane — deep ocean is first-class.

# world_manifest.yaml (defaults)
vertical:
  z_min: -4096
  z_max: 2048
  sea_level: 0
  deep_ocean_floor: -512

3.3 Chunk-primary simulation (foundation)

Chunks are the stable unit of world data and ownership. Regions are runtime groupings of chunks assigned to a worker.

WorldChunkKey { cx, cy, cz }   # e.g. 32×32×32 m cells — config
RegionId                      # ephemeral; owns Set<WorldChunkKey>

• Terrain deploy, resources, and persistence key off chunks
• Dynamic split/merge = reassign chunks between workers — no world data rewrite
• Segment bounds align to chunk grid at validation time

3.4 Dynamic region splitting (decided — from day one)

Not a fixed 512×512 grid for the life of the server. The region orchestrator (control plane component) grows and shrinks regions based on load.

                    ORCHESTRATOR
                         │
         metrics: players, tick_ms, intent_q, entities
                         │
    ┌────────────────────┼────────────────────┐
    ▼                    ▼                    ▼
 Region A            Region B            Region C
 (quiet, merged)   (split → B1,B2)      (single)
 chunks {…}         hot town → 2 workers

Split triggers (configurable thresholds)

Merge triggers

Split / merge flow

1. Orchestrator picks axis-aligned cut through chunk set
2. Pause intents at boundary slice (≤ 1 tick)
3. Migrate chunk authority + entities to new/existing workers
4. Update gateway routing table (atomic swap)
5. Resume; handoffs use new boundary

Players see at most a brief boundary hitch — same as any region cross.

Initial bootstrap

• World starts as one region (or seed-sized region) covering deployed segments
• Splits happen as soon as metrics warrant — not a future phase
• Phase 1 still ships one worker process; orchestrator + split logic can run single-node before cluster scale-out

Why dynamic from the start

• Towns and events concentrate players — fixed cells overload one worker
• Empty wilderness should not each consume a tick loop
• Chunk-primary model makes dynamic split a routing change, not a content change

4. Performance characteristics

Spatial sharding keeps sim cost manageable; the orchestrator tunes region density as the world grows.

5. World building system

5.1 Segments

A segment is the unit of authored world content:

WorldSegment {
  id,
  bounds: { x0,y0,z0, x1,y1,z1 },
  version,
  status: draft | in_review | approved | published | deployed,
  author,
  layers: {
    terrain,
    resources,
    spawns,
    structures,
    zones,        // PvP, safe, water, etc.
  },
}

Segments tile the world — adjacent segments must align at boundaries (validator enforces).

5.2 Layer types

Limited resources: finite depletion per node or per segment until repop event — defined in segment data.

5.3 Pipeline (review / publish / deploy)

  draft ──► submit ──► in_review ──► approved ──► published ──► deployed
              │            │              │
              │            └── community reviewers (permissioned)
              └── validation (geometry, resources, perf budget)

Community builders: special roles — can draft segments in assigned zones, cannot deploy without approval.

5.6 Hot terrain deploy (decided)

Deployments are versioned and applied without taking the world offline.

Versioning model

SegmentVersion {
  segment_id,
  version: semver,           // e.g. 1.2.0
  content_hash,
  parent_version,            // optional diff base
  published_at,
  author,
}

WorldDeployment {
  deployment_id,
  created_at,
  manifest_version,          // bundle of segment versions
  segments: [{ id, version }],
  status: rolling | complete | rolled_back,
}

• Every publish creates an immutable segment@version
• Deploy references a manifest bundle — reproducible rollbacks
• Workers track deployed_manifest_version per chunk column

Hot apply pipeline

published segment@1.2.0
        │
        ▼
  build chunk diff (vs currently deployed)
        │
        ▼
  push to orchestrator ──► route to workers owning affected chunks
        │
        ▼
  worker: apply terrain/resource layers in-place
        │
        ├── entities in modified solid cells → relocate / crush rules
        ├── players in chunk → resync AOI + reliable chunk revision
        └── broker/resource nodes refresh from new layer

CLI:

flatland-world segment publish north-mines --version 1.2.0
flatland-world deploy create --manifest world-2026-07-06.yaml
flatland-world deploy start dep-7a3f          # hot rolling
flatland-world deploy status dep-7a3f
flatland-world deploy rollback dep-7a3f

Agent API

• Idempotent deploy endpoints; JSON status with per-chunk progress
• GET /deployments/{id} → { status, chunks_total, chunks_applied, errors }

5.4 World Building API (CLI + agents)

Agent-first HTTP/gRPC API (TUI wraps same):

flatland-world segment create --id north-mines --bounds ...
flatland-world terrain paint --segment north-mines --layer surface --file ...
flatland-world resource place --segment north-mines --type iron_ore --density 0.3 --limited
flatland-world segment validate north-mines
flatland-world segment submit north-mines
flatland-world segment approve north-mines    # reviewer
flatland-world segment deploy north-mines     # ops
flatland-world manifest status

JSON request/response throughout; idempotent where possible.

5.5 Growing the world

• Start with seed manifest (starter continent + underground band + sky cap)
• Expand by adding segments to the published manifest
• World map catalog — all published segments + versions
• Runtime loads deployed manifest version per chunk; hot-updated on deploy (§5.6)

6. Travel & portals

Region handoffs are gateway-coordinated; players do not manage cross-server travel.

7. Open source (future)

• Open-source game server + world-build toolchain
• A self-hoster runs a full stack = their own w realm, their own world manifest
• Separate from the official live world deployment
• Same codebase, separate deployment — like running your own Minecraft server vs joining Hypixel

8. Rust workspace (revised)

flatland3/
├── crates/
│   ├── protocol/
│   ├── sim/
│   ├── region-orchestrator/ # dynamic split/merge, chunk routing
│   ├── region-worker/
│   ├── gateway/            # client connections, region routing
│   ├── control-plane/      # accounts, economy, persistence
│   ├── world-build/        # segment API, validation, deploy
│   ├── client-lib/
│   └── tui/
├── assets/
│   ├── world/              # deployed + draft segments
│   ├── items/
│   └── recipes/
├── tools/
│   └── flatland-world-cli/
└── Cargo.toml

9. Phasing

10. Terminology

Downstream docs (06, 07, 10) use region for sim partition and world for player geography.

11. Open questions

Resolved (2026-07-06):

Executive summary and principles: 00-initial-vision.html