Flatland3 — Initial Vision & Architecture Plan

Current play client (2026-07): flatland3-gfx is the only maintained interactive client (Macroquad + egui). Ratatui map play and flatland-dev are retired. The TUI references in this chapter describe early development intent — see Macroquad Graphical Client.

1. Executive Summary

Flatland3 is a multiplayer online game designed for many concurrent players in a single continuous world with real-time streaming at 30–60 ticks per second. Development is server-first: all world rules, systems, and simulation logic are built and validated on the server before any graphical client exists.

The only client during early development is a TUI (terminal UI) for humans and agents (scriptable CLI, JSON output).

The runtime is Rust for speed, safety, and efficient concurrency.

World model (current)

• One global world per live deployment — operator-controlled region workers
• Region workers partition space for scale (operator-controlled, same ruleset)
• World Building API — grow terrain, resources, underground / underwater / sky strata via CLI and agents
• Segment pipeline — draft → review → approve → publish → deploy; community builders with permissions
• Open source (later) — self-hosters run separate realm deployments

See 01-global-world-architecture.html for full topology.

2. Core Design Principles

3. High-Level Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│  CONTROL PLANE — accounts, economy, persistence, audit, broker indices   │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │
┌───────────────────────────────▼──────────────────────────────────────────┐
│  WORLD BUILD — segment API, validation, review, publish, deploy          │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │ world manifest
┌───────────────────────────────▼──────────────────────────────────────────┐
│  SIMULATION CLUSTER — gateway + region workers (spatial shards)          │
│  One continuous (x,y,z) world · 30–60 Hz per active region               │
└───────────────────────────────┬──────────────────────────────────────────┘
                                │
                         TUI / clients

3.1 Region worker

• Owns a spatial bounds in the global world
• Tick loop, entity registry, AOI, combat, harvesting (active regions)
• Reads deployed world manifest for terrain, resources, zones
• Region handoff when players cross boundaries (gateway-assisted)

3.2 Control plane

• Accounts, characters, inventory, banks, brokers
• Cartography ledger, skills, death penalties
• World segment catalog (published versions)
• Anti-cheat, audit, bans

3.3 World build service

• CRUD for segments (terrain, resources, spawns, structures)
• Vertical strata — underground, surface, underwater, sky (height limits in config)
• Limited resources per segment definitions
• Permissioned community access + review / approve / deploy

4. Communication Protocol (Priority #1)

4.1 Client ↔ gateway

4.2 Internal (cluster)

• Gateway ↔ region workers: entity migration, interest transfer
• Region ↔ control plane: inventory, economy, persistence RPC
• World build ↔ control plane: deploy notifications, manifest versions

4.3 Open protocol decisions

5. Performance Targets

Dormant regions (no players) do not tick — saves CPU as world grows.

6. Persistence Model

Checkpoint on logout, death, region exit; central DB is source of truth for durable player/world state.

7. Game Systems (summary)

Detailed in topic docs — all execute on region workers unless noted.

Travel: continuous movement, region handoffs, and portals within the world.
Economy: brokers per town/region in the same world; cross-region price quotes = travel arbitrage.

8. TUI Client (Co-developed)

• Play: flatland — connect, move, inventory, combat
• World ops: flatland-world — segments, terrain, deploy (permissioned)
• Agent mode: JSON on all commands

9. Phased Goals

Phase 0 — Foundation

Phase 1 — Single worker + chunk model

Phase 2 — Control plane + dynamic regions

Phase 3 — World build + hot deploy

Phase 4 — RPG loop

Phase 5 — World growth

10. Rust workspace

See 01-global-world-architecture.html §8 — region-worker, gateway, control-plane, world-build.

11. Security & trust

• Single operator cluster — no untrusted sim hosts
• Community builders: draft only until review
• Signed published manifests; workers reject undeployed drafts
• Central audit for economy and rare items

12. Observability

• Per-region tick lag, AOI size, handoff latency
• World deploy pipeline metrics
• Trace correlation across gateway → region → control plane

13. Open questions

Resolved (2026-07-06): Chunk 16 m, water zones+currents, deploy push entities, tick 30→60 Hz — see 01 §11.

1. Chunk size 16 m
2. Water sim Zones + currents (01)
3. Deploy crush Push/relocate (01)
4. Fixed timestep 30 Hz launch, 60 Hz when stable (01)

14. Success criteria (server-first)

• Multi-region handoff stable under packet loss
• 100 bots/region @ 30 Hz
• Full loop: harvest → craft → trade → die → recover corpse
• World segment: validate → publish → deploy → playable in sim
• TUI + agents drive play and world build without raw protocol hacks

15. Document index

Appendix A — Glossary