Global World Architecture & World Building

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

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

in-game tools:

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 (in-game tools + agents)

Agent-first HTTP/internal RPC API (the terminal client wraps same):

the world tools segment create --id north-mines --bounds...
the world tools terrain paint --segment north-mines --layer surface --file...
the world tools resource place --segment north-mines --type iron_ore --density 0.3 --limited
the world tools segment validate north-mines
the world tools segment submit north-mines
the world tools segment approve north-mines    # reviewer
the world tools segment deploy north-mines     # ops
the world tools 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)