Buildings, Schematics & Construction

1. Summary

Flatland3 is not a high-poly architectural MMO — but buildings have real dimensions, rooms, doors, and navigable interiors. Players and world-builders use the same schematic system: YAML definitions that describe footprint, rooms, fixtures, and phased construction.

To build in the wild, a player first prepares a plot (flatten/clear terrain — time + resources). Then they construct from a schematic (authored, bought from NPCs, or player-created) over multiple phases with materials and ticks — like any craft, but anchored in the world.

The server validates and derives everything — plot size, material BOM, build time, room volume — from schematic YAML. Clients are a thin view on authoritative state; no client-trusted placement or costs.

Town and village structures in world-build segments are building instances minted from the same schematics, obeying the same navigation, fixture, and permission rules.

2. Locked decisions

3. Design principles

4. Core entities

struct PreparedPlot {
    plot_id: Uuid,
    region_id: RegionId,
    anchor: WorldCoord,           // corner or center — canonical in schematic
    footprint: Footprint2D,       // width × depth in meters
    flatness_quality: f32,        // affects build speed / stability
    prepared_by: CharacterId,
    prepared_at: Timestamp,
    expires_at: Option<Timestamp>, // optional decay if unused
}

struct BuildingInstance {
    instance_id: Uuid,
    schematic_id: SchematicId,
    schematic_version: u32,
    owner_id: OwnerRef,           // character, guild, settlement
    plot_id: PreparedPlotId,
    transform: Transform,           // anchor on plot
    state: BuildingState,         // preparing | phase_n | complete | damaged | demolished
    current_phase: u32,
    phase_progress_ticks: u32,
    rooms: Vec<RoomInstance>,     // resolved from schematic at phase unlock
    fixtures: Vec<FixtureInstance>, // beds, devices, chests, counters
    permissions: PermissionPolicy,
    links: BuildingLinks,         // storage, residence roster (`13`)
}

World-build towns: segment structures layer places BuildingInstance refs (or spawn on deploy) from settlement schematics — not a separate building format.

5. Schematic YAML schema

# assets/buildings/schematics/small_cottage.yaml
id: small_cottage
version: 1
display_name: Small Cottage
kind: residence                    # residence | lodging | storefront | warehouse | workshop | custom
description: One-room home with hearth and bed nook.

# ── Plot & footprint (server validates totals) ──
footprint:
  width_m: 8
  depth_m: 6
  height_m: 4                      # max exterior shell
  rotation_snap: 90                # placement yaw steps

plot_requirements:
  flat_tolerance_m: 0.25           # max slope across footprint after prep
  clearance_above_m: 1               # no overhang obstacles
  min_soil_depth_m: 0.5              # for foundation phase

# ── Interior grid (1 m cells typical) ──
grid:
  cell_size_m: 1
  origin: { x: 0, y: 0, z: 0 }     # local to building anchor
  cells:
    - { x: 0..7, y: 0..5, z: 0..3, room: main }
  rooms:
    - id: main
      tags: [interior, climate_controlled]
      functions: [sleep, cook, craft_bench]
      max_occupants: 4

# ── Shell openings ──
doors:
  - id: front_door
    at: { x: 4, y: 0, z: 0, face: south }
    connects: exterior ↔ main
    width_m: 1

# ── Fixture anchors (installed in later phases) ──
fixtures:
  - id: hearth_1
    room: main
    at: { x: 6, y: 2, z: 0 }
    type: cooking_hearth           # enables kitchen station (`09`)
  - id: bed_1
    room: main
    at: { x: 1, y: 1, z: 0 }
    type: bed
    worker_bed: false              # player sleep; true counts for worker cap (`13`)
  - id: bench_1
    room: main
    at: { x: 3, y: 3, z: 0 }
    type: craft_bench

# ── Construction phases (materials + time) ──
construction:
  phases:
    - id: foundation
      inputs: [{ item: stone_block, qty: 24 }, { item: mortar, qty: 8 }]
      ticks: 1800
      skill: construction ≥ 5
    - id: framing
      inputs: [{ item: hardwood_plank, qty: 40 }, { item: iron_nail, qty: 60 }]
      ticks: 2400
      skill: construction ≥ 8
    - id: fixtures
      inputs: [{ item: hearth_kit, qty: 1 }, { item: bed_frame, qty: 1 }]
      ticks: 1200
      installs: [hearth_1, bed_1, bench_1]

# ── Caps & permissions ──
limits:
  max_worker_beds: 0               # cottage — no hired workers
  max_devices: 2
  storage_links: 2

permissions_default:
  owner: [build, use, storage, invite]
  guest: [use]

5.1 Schematic kinds (examples)

6. Server validation & derived costs

No hand-waved YAML. On upload, publish, or purchase:

validate-schematic small_cottage.yaml
  → footprint area: 48 m²
  → interior volume: 192 m³
  → derived_material_index: 1.12 (ruleset)
  → minimum_phase_materials: OK | FAIL (under minimum stone for area)
  → total_ticks: 5400
  → plot_prep_multiplier: 1.0 (flat grass) | 1.8 (rocky)
  → tradable: true

Player-created schematics that fail validation cannot be built or listed until fixed. Cheating (client sending cheap build) rejected — server recomputes from schematic id + version.

7. Plot preparation (flatten)

Before BuildingInstance placement:

1. Player selects schematic (or footprint size)
2. Server samples terrain at anchor + footprint
3. If slope/obstacles exceed plot_requirements → must run PreparePlotIntent
4. PreparePlot consumes: tools, labor ticks, optional explosives, coins
5. On complete: mint PreparedPlot entity; terrain cells adjusted (authoritative voxel/tile flatten)
6. Plot may expire if no build started (ruleset)

Players may build anywhere in allowed zones (wilderness, claimed land, lease — zone rules from 01 / future land claim). Town lease plots may skip prep (pre-flattened).

8. Construction flow

1. Player at PreparedPlot with schematic (learned, inventory blueprint instance, or settlement grant)
2. StartBuildIntent { schematic_id, plot_id, yaw }
3. Server validates: permissions, zone, plot size ≥ footprint, materials in inventory or linked storage
4. Mint BuildingInstance state=phase_0; debit phase 0 inputs (or escrow)
5. Each tick: progress += builder_skill_modifier; workers may contribute (`13`)
6. Phase complete → unlock rooms/fixtures for that phase; start next phase
7. state=complete → fully navigable; fixtures usable; residence links enabled

Interrupt: pause leaves instance in place; partial progress saved; weather/raid may damage incomplete shells (optional ruleset).

Hired workers: construct job step — same as player, at linked plot.

9. Interiors — navigation & use

9.1 Grid model

• Exterior footprint on world (x, y); z for floor levels (single floor at launch; multi-floor later).
• Cells tagged solid | walkable | door | fixture.
• Navmesh per building instance — NPCs and players path indoors (19 schedules use anchor: hearth_1).

Not AAA mesh — logical geometry for collision, LoS (12), and “who is in the room.”

9.2 Fixtures

Fixtures are installed in construction phase or added later via remodel schematic — each validated.

9.3 Item placement indoors

Dropped/placed items use building-local coords + building instance_id — same rules as outdoor placement (11 §2.3). Storage chests at chest_anchor slots.

10. Modification & demolition

No freeform delete-wall at launch — YAML patches keep validation centralized.

11. Blueprint economy

flatland schematic validate, flatland schematic publish, flatland build start.

Brokers list blueprint instances; creators set price (10).

12. Town & village buildings (world-build)

Segment structures layer (01):

structure_placement:
  id: northhold_smithy
  schematic_id: town_smithy_v1
  plot: pre_flattened              # authored terrain already prepared
  owner: settlement:northhold
  rotation_yaw: 90
  fixtures_override: []            # optional — quest-locked door
  npc_anchors:
    - blacksmith_elsa → forge_1

Same BuildingInstance type — settlement-owned; NPC schedules reference fixture ids (19).

13. Integration with workers & residences

craft_residence (13) is a BuildingInstance where kind: residence | workshop with:

links:
  lodging: { building_id, bed_fixtures: [bed_1, bed_2] }
  devices: [mill_1]
  storage: [warehouse_link_a]
  worker_spawn: worker_quarters_anchor

Worker cap = count(worker_bed: true) in linked buildings ≤ limits.max_worker_beds on schematic.

14. Zones & permissions

permissions on instance: owner, guild, invite list — chest access, device use, build remodel.

15. Server authority (anti-cheat)

All state in region worker + central persistence — same security model as combat and inventory.

16. TUI / agent

flatland plot scan --schematic small_cottage
flatland plot prepare --schematic small_cottage --at <coord>
flatland build start small_cottage --plot <id>
flatland build status <building_id>
flatland building enter <building_id>
flatland building fixtures <building_id>
flatland schematic validate ./my_shed.yaml
flatland schematic publish my_shed.yaml

17. Content pipeline

assets/
  buildings/schematics/*.yaml
  buildings/patches/*.yaml          # extensions
  buildings/fixtures/*.yaml         # fixture type defs
ruleset/
  building_derive.yaml              # cost/volume formulas
tools/
  validate-schematic.mjs
  validate-building-nav.mjs

18. Phasing

19. Open questions

Resolved (2026-07-06):

Crafting & materials: 09-crafting-and-recipes.html
Worker residences: 13-workers-and-automation.html
World segments: 01-global-world-architecture.html §5