Home Runtime Architecture & Shipped Features

Runtime Architecture & Implemented Features

1. Summary

Flatland3 runs as separate processes in local dev and production-shaped deployments:

Process Binary Default port Role
Control plane control plane HTTP :7380, internal RPC :7381 Accounts, auth, characters, checkpoint, item mint
Region worker region worker Wire :7391 30 Hz sim, AOI, gameplay rules for one region
Gateway gateway TCP :7373 Player protocol, auth handoff, routes to worker
Play client flatland3-gfx — Macroquad map and egui HUD
Agent in-game tools flatland3 — Auth, characters, inventory, headless play

Embedded mode (no separate worker): omit a server setting or pass --embedded to the gateway — the worker runs in-process.

2. Process architecture (implemented)

flowchart TB subgraph clients["Clients"] GFX["flatland3-gfx"] BOT["bot client"] end subgraph edge["Edge"] GW["gateway\nTCP:7373\npostcard FL3\\x01"] end subgraph sim["Simulation"] RW["region worker\nwire:7391\npostcard FL3W"] SIM["RegionSim @ 30 Hz"] RW --> SIM end subgraph durable["Durable"] CP["control plane\nHTTP:7380"] PG[(Postgres)] RD[(Redis)] CP --> PG CP --> RD end GFX -->|Hello / Intent / Tick| GW BOT --> GW GW -->|a server setting| RW GW -->|validate-connect / checkpoint| CP RW -->|mint-item| CP

3. Implemented feature catalog

Each subsection describes what the current revision does and where it lives in code.

3.2 Gateway & protocol

Implemented

  • TCP game server, postcard framing FL3\x01, protocol v2
  • Session + access tokens auth via control plane
  • DevLocal gated by a server setting
  • Remote worker backend (a server setting) or embedded worker
  • Intents: Move, Stop, Harvest, Use, Say, Craft, Interact, TestDamage, SetTarget, Attack, Cast, Dodge, Block, EquipMainhand, Trade*, StowWhisperStone, DestroyWhisperStone, …
  • Server messages: Welcome, Tick, IntentAck, Chat, HarvestResult, CraftResult, Death, Interaction, TradePanel / trade close notices, CombatFx

3.3 Region worker & simulation

Implemented

  • RegionSim @ 30 Hz: movement, AOI, interaction radius 1.5 m
  • Chunk map (16 m), orchestrator split threshold logging
  • World segment YAML: resource nodes, buildings, doors, NPCs, terrain zones, z-bands (z_platforms, z_transitions, z_walls)
  • Timed harvest, node respawn, blocking nodes
  • Nested inventory (instance UUID + contents), mass/volume, worn back/belt containers
  • Placeable lockable chests + unique craft keys; dimensional pouch mass attenuation
  • Wildlife + combat: the source, abilities, multi-slot targeting, 3D LoS + z-walls
  • NPC lifecycle: ground drops, carcass TTL, respawn scheduler (25)
  • Content bundle hot reload (Tier 3.5): Arc swap for blueprints, catalog, settings, NPC defs
  • Timed craft from blueprint packs (the content files)
  • Broker hut (Ada), door enter/exit, resurrection shrines
  • Death / respawn, test damage dev intent
  • Player progression: primaries, skills (tier 0–10), vitals pools, activity growth, atrophy
  • World clock on wire + the terminal client status line
  • Server settings YAML (vitals, progression, day/night) — no hardcoded tuning
  • Multi-worker segment ownership (region_assignment.yaml) + gateway handoff; neighbor preview terrain/buildings/resources until cross-seam Welcome

3.4 Player attributes & persistence

Implemented

  • PrimaryAttributes on wire (internal 1–1000, display /10)
  • Hunger, thirst, mana, stamina, health pools + PoolSpend hooks
  • Regen/drain modifiers; the terminal client character sheet (i)
  • Postgres: attributes, vitals_state, skills JSONB on characters
  • Checkpoint roundtrip: disconnect → validate-connect restores attrs, pools, skills
  • Skills start at tier 0 (internal level 0); tier 1 at internal 100
  • Pristine {} vitals treated as new character (full pools)

3.5 Play client

The maintained client is flatland3-gfx. Key map: Controls. Gfx architecture: Macroquad client.

Implemented

  • In-the terminal client login (email/password) when no session
  • WASD (world-relative; hold two keys for diagonal), sprint, climb/descend, context use (f), craft (n), inventory (b)
  • Click-to-move (left-click) + map target mode (m); Space hard-stops; Shift+Space lunge
  • Combat HUD, loadout (l), rotation editor (o)
  • Stats overlay (i): primaries, derived preview, pools, skills tiers 0–10
  • HP/MP/STA bars; nearby chat (t), whisper (f → Whisper), whisper-stone (g), P2P trade
  • Map glyphs: resources, buildings, doors, NPCs, player first-letter labels; elevation tiers on terrain (▴/^/▲)
  • Combat: Tab/Shift+Tab targets; 0/Shift+0 clear T1/T2; 1–9 hotbar casts; auto (r/Shift+r); dodge (c); block (q); inventory equip (b → Enter / u)
  • Storage: carry mass bar, inventory tree, place/pickup chests (f), equip pouches/backpacks
  • Utility row: b bag, n craft, m map, , keychain, . HUD, ' hide LOG, / or ? help
  • Z-axis: PageUp/PageDown climb; HUD shows z; click-to-move routes through stairs when goal is on another band

Also (gfx primary): unified CHAT column, speech bubbles, combat map FX (39), hideable system LOG. See 22 communication system.

3.8 Combat system

Architecture

  • Intents only — no input methods in sim (SetTarget, Attack, Cast, EquipMainhand, AssignSlotPreset, …)
  • RegionSim @ 30 Hz: combat pursuit → auto-attacks / NPC telegraphs → DoT tick → movement integrate
  • Ability templates in the content files*.yaml; items in the content files
  • Client pathfinding (client lib module) for click-to-move / map targets

Capability layers (implemented)

Layer Behavior
Mainhand weapon EquipMainhand sets PlayerState.mainhand; slot-1 auto uses weapon_ability_id on that item
Auto-attack Per-slot toggles; slot 1 drives pursue
Auto-pursue Slot-1 target; band positioning from mainhand range_min_m / range_max_m
Manual weapon Attack intent → mainhand ability
Manual spells Cast { ability_id, target_id } — independent range/CD/GCD
Defense Dodge (i-frames), Block (frontal melee reduction)
Multi-slot / loadout T1/T2 targets; rotation presets; loadout assign; persist on StoredCombatProfile
Rotation editor the terminal client o — create/edit/delete presets; UpsertRotationPreset / DeleteRotationPreset
Macros ExecuteMacro { macro_id: "burst_opener" }
NPC abilities Wolf wolf_bite / wolf_lunge from YAML; telegraphed lunge dodge window
DoT / on_hit poison_dart / ability on_hit → status-effect catalog + periodic DoT ticks
Pacing combat.pacing.* multipliers in server-settings.yaml

Content shipped

Ability Kind Notes
unarmed weapon_attack Default, no equip
short_sword_slash weapon_attack wooden_sword
bow_shot weapon_attack hunting_bow, short_bow; 3–22 m
arrow_shot spell Manual; same range band
fireball spell Channel + splash
cone_frost, frost_nova spell Cone / self sphere
heal_touch spell Friendly/self; Support preset
poison_dart spell on_hit DoT
wolf_bite, wolf_lunge weapon_attack NPC catalog; lunge telegraphed

Weapons (the content files)

  • wooden_sword → short_sword_slash
  • hunting_bow, short_bow → bow_shot

Persistence

  • StoredCombatProfile: target instance id, target_slots[] (preset_id, auto, rotation_index), rotation_presets[], in_combat, cooldowns, auto_attack_enabled, mainhand_template_id
  • Characters: explicit flatland3 character create only — play never auto-creates

Movement / the terminal client (summary)

WASD (chord diagonals OK); click-to-move; map mode (m); Tab/Shift+Tab targets; 0/Shift+0 clear; 1–9 hotbar; l/o loadout/rotations; c/q dodge/block; Shift+Space lunge; r/Shift+r autos; f use world (players → Whisper/Trade); t chat; g stone; n craft; ' hide LOG.

Vitals regen ramp (the content files)

Per-pool regen_ramp.health / .mana / .stamina — each with seconds_to_full, min_multiplier, max_multiplier, curve_power.

Code

  • sim module — pursuit, resolver, equip, NPC telegraphs, DoTs
  • sim module, the source, the source
  • client lib module, the source
  • tui module, the source, the source

Principle: nothing is hard-coded per weapon name in Rust or the client. The server item catalog defines what an item does; equip/use intents resolve capabilities against the equipped instance.

3.9 Storage & carriers

Implemented

  • Item templates: base_mass, base_volume, packable, capacity_volume, equip_slot (back/belt)
  • Nested inventory graph on wire + Postgres sync; worn back/belt; placed chests in world snapshot
  • MoveItem, equip, place, pickup, lock intents; mass/volume caps; nest depth (default 4)
  • Lockable chests mint unique keys; dimensional pouch mass attenuation
  • the terminal client: inventory tree, carry mass bar, scrollable overlays, chest glyphs on map

3.10 Z-bands & vertical dimension

Architecture

  • Terrain elevation — terrain_zones[].elevation sets ground z per rect; wired on TerrainZoneView.elevation
  • Z-platforms — extra walkable surfaces at fixed z (z_platforms in segment YAML)
  • Z-transitions — stairs/ramps linking z_from ↔ z_to (PageUp/PageDown while standing in rect)
  • Z-walls — axis-aligned volumes blocking 3D combat LoS
  • Movement — z_bands::resolve_horizontal_z / settle_z / apply_vertical_z (no snap-to-ground on platforms)
  • AOI — query_radius_z with AOI_Z_EXTENT_M (6 m) vertical half-extent
  • Client pathing — the source blocks cells at wrong band; opens transition cells; auto-climbs stairs

Starter test slice (starter-plains.yaml v1.2.5): southeast mountain — south trail (z=0→4 in 1 m steps), plateau at ~(220–232, 158–166), north/east/west cliff faces block uphill; fall off rim to z=0. LoS wall on north rim.

3.11 Seasons, lights, buildings, and art

System What ships
Seasons & weather Four seasons on the world clock; one weather state per biome zone; hot thirst and growth multipliers; rain, storm, and snow overlays. Seasons and weather
Day–night & lights Ambient curve, night sight, held and placed lamps, fuel tanks on builder lights. Lights
Buildings Town interiors, one player house per tilled plot, placeable walls, doors, and lamps. Buildings
Art Sprite sheets for props; box skeletons baked to facings for people and creatures; LoRA adapters from gold sheets. Sprites & character models