Terra Firma: Awakening — Architecture Map

Companion to: Terra_Firma_Functional_Specification.md §2
Demo host: Lyra 5.8 (demo5.8) + SKGShooterFramework + AimAssistSystem + ADDON GFP

This page is the visual breakdown of plugins, logical modules, classes, client vs server authority, hit auth, and threads. Requirement text stays in the Functional Spec.

1. Stack at a glance

┌─────────────────────────────────────────────────────────────┐
│  ALWAYS-ON (not Game Features)                              │
│  CommonGame · CommonUser · GameSettings · UIExtension       │
│  GameplayMessageRouter · ModularGameplayActors · AsyncMixin │
└─────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────────────────────────────────────┐
│  HOST                                                       │
│  LyraGame / LyraEditor — Experiences, pawn data, CommonUI   │
│  ULyraExperienceDefinition::GameFeaturesToEnable            │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┴─────────────────────┐
        ▼                                           ▼
┌───────────────────┐                     ┌───────────────────┐
│ MARKETPLACE /     │                     │ GFP: ADDON        │
│ VENDOR            │                     │ ATerraFirmaCharacter│
│ SKGShooterFramework│                    │ SKG glue only     │
│ AimAssistSystem   │                     │ Active at boot    │
└───────────────────┘                     └─────────┬─────────┘
                                                    │
                                          ┌─────────▼─────────┐
                                          │ GFP: TFACore      │
                                          │ Tags · types ·    │
                                          │ messages · Active │
                                          └─────────┬─────────┘
                    ┌───────────────┬───────────────┼───────────────┐
                    ▼               ▼               ▼               ▼
              TFACombat      TFAMelee        TFASingularity  TFAWeapons
              TFAModular*    TFAOmniVisor    TFAFrontend     TFAVision
              TFACharacterI  TFAProgression  TFAOnline       TFAWorld
              TFACrafting    TFAEconomy      TFAMaps         TFAAI
              TFATrust
              (* optional · + portable MonetaryPlatform: ledgers + AntiCheat)

Rule: Do not fork LyraGame into UBT modules named TFACombat. Logical module names (§2.1) pack into Game Feature Plugins (§2.5). MonetaryPlatform is a portable .uplugin (not a GFP) — ledgers + public AntiCheat; GFPs enable/adapt it.

2. Logical module → GFP → key classes

Logical module	GFP	Key classes / widgets	Ships
`TFA` (host)	`LyraGame` + Experiences	Experience DAs; boot until TF shells land	P0
`TFACore`	TFACore	Tags, message structs, interfaces; shared pawn data refs; owns `ATFAGameMode` / `ATFAGameState` / `ATFAPlayerState` shells (Online/Progression/Combat/Economy write fields — no second GS/PS)	P0
SKG bridge	ADDON	`ATerraFirmaCharacter` (+ SKG components). No inventory/HUD/economy/GAS combat	P0
`TFACombat` (spine)	TFACombat	`UTFACameraDirector`, `UTFALoadoutComponent`, `UTFAVitalityComponent`, shared combat ASC host — thin; no Melee/Singularity impl; Full: Pose Search loco AnimBP / loco DBs (FS-FX-002)	P1–P2
`TFAMelee`	TFAMelee	Melee Drive GAs (`UTFAGameplayAbility_MeleeStrike` / Counter) + `UTFAMeleeDriveCombatComponent` (cone pick · hit trace · Counter window helpers — not a second action runtime) — Plugify swappable; Full: strike / transition Pose Search DBs + chooser (notifies still gate hits). Consumes MeleeFeel / frame stats from Weapons part data — does not author Exact Variables or Refit sockets (FS-MEL-001). Guard Block ≠ Drive Block button. Publishes kill/hit messages via TFACore; no `#include` of Weapons / Singularity	P2
`TFASingularity`	TFASingularity	Kinetic Flow meter + Singularity climax — Plugify; subscribes to kill credit messages (`TFA.Combat.KillConfirmed` locked) — no hard call from Melee/Weapons	P2
`TFAWeapons`	TFAWeapons	`UTFAFirehandBus`, SKG adaptors, `DA_TFA_GunFrame`, `DA_TFA_MeleePart` (sockets Head / Guard / Haft / Pommel / Core) + MeleeFeel Exact Variables authorship (FS-MEL-001; GDD O17 · fig-140-4/5) — Plugify. Demo stays non-modular / fake-modular guns only	P3
`TFAModular`	TFAModular (optional)	Mag/optic/melee Refit dials (guns + MeleeFeel) — split from Weapons when product needs it	P3+
`TFAUI` / HUD	TFAOmniVisor	OmniVisor widgets, chat OV29/31/32, FE30 locator — Plugify GUI. Not Demo Mod chrome	P1
Demo Mod (team tuner)	TFAWeapons host + CommonUI	`W_TFA_DemoMod`, `bDemoModEnabled` (external default false), FS-GUN-012 session overrides (kit/type/quality locks · Name: affix-built below Rare · Rare First+Second Word lexicon · L/U/Apex hand-authored Unique name · affixes/wells/Fake Mag → ammo) · Receiver × Frame ranged kits (`auto_adaptive`, `hc_aggressive`, …) with Frame-band MagSize/reserve · Field Spec slots (FS-ITM-014: guns + melee; Rare 1 · Legendary 2 · Unique 3 · Apex 4; capacity Specs guns-only HUD mag/reserve) · Shiv Spec (FS-ITM-015: Unique/Apex guns + melee · 1 socket · per-name TBD) · OV36 seat loadout test: session `fillOverrides` per seat (`null` = unequipped — not mute) · Isolate / Restore kit · seat kit memory · `KIT_CATALOG` buckets (`ranged` / `melee` / …) via `SEAT_CATALOG_KEYS`; W1–W4 ranged-only until `DEMO_ALLOW_MELEE_ON_W` · Equipped-kit Ranged/Melee optgroups · Lab Combat economy · Flow · Singularity · Attributes · Parkour (`WallRunMaxDuration` 3.0 s · `MaxWallDashDistance` 6.0 m · `MaxWallTurnDegrees` 45 · lookahead 2.0 m / 4) · Encounter (alvl/dlvl/ARL/Difficulty + PowerΔ) · Affix totals per FS-DMG-001 channel (FS-CMB-007 / FS-PRG-002 / FS-PRD-005 / FS-DMG-009 / FS-MOV-004 — TFACombat / TFASingularity / parkour DA rates, not OmniVisor). Export kinds include `lab-flow` · `lab-parkour` · manifest `fillOverrides` / `seatKitMemory` / `kitSnapshot`. Mock: `tfa_gdd_html/figures/demo_mod_mock.html` · specs `docs/inventory/demo-mod-item-specs.md` · `demo-mod-field-specs.md` · `demo-mod-shiv-specs.md` · `demo-fake-modular-optics-mags.md` — Trait on all qualities; Origin + Set on L/U/Apex; Field Spec Rare→Apex (guns+melee); Shiv Spec Unique/Apex (guns+melee). Not OmniVisor child	Demo
`TFAInventory` + I UI	TFACharacterI	`UTFAInventoryComponent`, `W_TFA_CharacterI`, Inspect, Invoke UI — Plugify. Bags / Secure Locker gear: 10×6 cell occupancy bitmask + item anchors `(col,row,rot)` and footprint `W×H` from `DT_TFA_ItemFootprints` / `tfa_item_footprints_v2.json` (+ cook CSV `tfa_gdd_html/data/DT_TFA_ItemFootprints.csv`) (FS-GUI-010) — rectangles only, 90° rotate, no L-shapes; not a flat list with scalar slotCost. Item instances: Trait columns by quality (FS-ITM-010 2026-11-13d — guns Common none · Uncommon Verb · Augmented Feed+Verb · Rare Bullets+Feed+Verb · L/U/Apex +Plate; Feed = `{MagFamily} Spec`; armor/shield Shell·Stride·Brace·Verb; jewelry none); Field Spec slots on guns + melee (FS-ITM-014 Rare 1 · Legendary 2 · Unique 3 · Apex 4); Shiv Spec on Unique/Apex guns + melee (FS-ITM-015 · `shivSpecId` · per-name TBD); `OriginId` Unique only · `OriginId2` Apex only; Unique/Apex `SetID`/`PieceIndex` (FS-ITM-004); loadout `ActiveSetIDs[]` under ASBP=6 (worn unlimited; cost = equipped count; refuse <2; independent ladders; Year 1 ship surface TBD-072). Catalog names filled (TBD-058…061); magnitudes + Set roster (TBD-062/063) still open. Familiarity + Masterwork (FS-ITM-013, FS-CRF-012, FS-TRK-002) — use XP + craft finish; costs TBD-065…068. Inspect mock (`#ins-verb` / `#ins-fam`): Trait column strips + Origin strips (Unique/Apex) + Set membership pips + Familiarity bar / Masterwork mark. Character I Active Sets strip: worn SetIDs + ASBP meter. Apply order FS-ITM-011. No new GFP for Traits/Origins. Secure Locker: `W_TFA_SecureLocker` hub terminal dual-pane bags ↔ account `SecureLocker` (FS-GUI-009); same footprints as Gear; Online deposit/withdraw server fail-closed; tab SKU FS-ECO-014 / TBD-069…071. Not Armory foundry; not coop Vault	P4
`TFAProgression`	TFAProgression	Trees, Customizable 4×4, tentacles, ordnance GAS grants — Plugify	P5
`MonetaryPlatform` (plugin)	Portable plugin (not a GFP)	`UMonetarySubsystem`, ledgers (`CreditsBalance` account-shared · BTUCOIN · LUMENAR on PUID / Solo profile — FS-ECO-001), `UAntiCheatSubsystem` (public), Marketplace Wallet, EntitlementFlags (CF / Founding Clubs) — Plugify money product (swap/omit whole plugin)	P4b prep
`TFAEconomy`	TFAEconomy	TFA money adapter only — enables MonetaryPlatform; play Credits grants into shared account ledger; I chips (CREDITS · BTUCOIN); marketplace routes; CF apply — Plugify. Does not gate AntiCheat	P4b
Trust UI	TFATrust	Report / Trust overlay / ghost chrome — submits into MonetaryPlatform case API — Plugify	P9b
`TFACrafting`	TFACrafting	`UTFACraftingSubsystem` — Plugify. Forge rolls Trait on Common→Rare / reprints Origin+Set on L/U/Apex (FS-CRF-011). Rewrite vs Trait TBD-064. Refit/Bore never write Trait/Origin/SetID	P6
Vision	TFAVision	`UTFAVisionComponent` — Plugify	P7
`TFAWorld`	TFAWorld	`UTFAObjectiveSubsystem`, encounter director — Plugify	P7–P8
`TFAAI`	TFAAI	`ATFAAIController`, Squad coordinator, Logic Driver runners, difficulty DA — Plugify; no second damage pipeline	P7–P8 (Demo C earlier)
`TFAFrontend`	TFAFrontend	Intro, mode, create/select, Command Deck chrome — Plugify boot GUI	P0
`TFAOnline`	TFAOnline	EOS Connect, invite Discord link, fireteam/clan/invites, Online career / Match History / Ladder store — Plugify. Companion Player API is a separate read HTTP gateway in front of this store (not a second UE stats system; not invite Discord) — FS-API-*	P0 / P9
Maps content	TFAMaps	Content-only experiences (like ShooterMaps) — Plugify content GFP	P0 / P8

Player-facing core (always composed onto the pawn / controller / state):

Class	Typical GFP owner	Notes
`ATFACharacter`	TFACore / ADDON glue	Movement, stance, FPP/TPP mesh, GAS avatar
`ATFAPlayerController`	TFACore / Lyra host	Enhanced Input, camera requests, UI router
`ATFAPlayerState`	TFACore (+ Progression / Combat / Economy / Online writers)	Level, XP, stats, trees, loadout, realm pool — one PS class
`ATFAAIController`	TFAAI	Logic Driver Agent host, perception / nav bridge; no second damage pipeline
`UTFAAbilitySystemComponent`	TFACombat spine + Progression grants	Shared ASC host; Melee Drive / Singularity GAs live in sibling Plugify GFPs (tag-gated Activate/Cancel on ASC — no parallel ACS stack)
`UTFAMeleeDriveCombatComponent`	TFAMelee	Target cone on Attack · ANS hit helpers · Counter window — Tick off; never ambient magnet

3. GFP dependency (downward only)

TFACore
  ├── TFACombat (spine) ──► TFAMelee
  │                    └──► TFASingularity   (Flow + climax; message bus)
  ├── TFAWeapons ──► TFAModular (optional)
  ├── TFAVision
  ├── TFAOmniVisor          ← pullable in-game GUI
  ├── TFACharacterI ◄── TFAEconomy (interfaces) ──► MonetaryPlatform
  ├── TFAProgression ──► TFACrafting
  ├── TFAWorld ──► TFAMaps (content)
  │                 └── enables TFAAI (encounters / patrol)
  ├── TFAAI  (MP bot-fill Experiences also enable; depends TFACore only)
  ├── TFAFrontend ──► TFAOnline   ← pullable boot/Deck GUI
  ├── TFAEconomy ──► MonetaryPlatform (money adapter)
  └── TFATrust ──► MonetaryPlatform AntiCheat (submit/display only)

Lyra / TFACore may depend on MonetaryPlatform and call UAntiCheatSubsystem without TFAEconomy.

UI GFPs talk to gameplay through Gameplay Message Router + TFACore interfaces, not by including Combat headers. Plugify: sibling GFPs do not #include each other — Experience composes them. Bible: docs/02-gfp-cookbook.md Plugify lock.

Boot Active: ADDON, TFACore.
Experience-enabled: everything else via GameFeaturesToEnable.

4. Client vs server map

Same C++ for Solo and Online. Solo = listen / local authority. Online = server is the only writer of power.

4.1 Authority by domain

Domain	Client	Server
Camera, anim (incl. Full Motion Matching pose), recoil, ADS, stance mesh	Owns presentation / Pose Search choice	Reconcile pose only — never MM-as-damage
OmniVisor chrome, bag filter/sort, FE widgets	Owns layout	Replicates snapshot
Chat compose	Owns draft	Send RPC by channel (Fireteam / Clan / Match / General / Proximity / Whisper) + flood (TBD-033)
Vision overlay materials	Renders modes server allows	Owns unlock + relevancy (TBD-028)
Hits / damage / Flow / death / loot	Predict FX only	Auth + apply GE
Mag / Energy / ability commit / grenade	Request	Validate + spend
Inventory / sockets / salvage / Apex Invoke	Request UI	Mutate; fail closed
Credits / BTUCOIN 51/49 / LUMENAR convert	Display after ack	Ledger writers
CF / Founding Club EntitlementFlags	Present looks (Material + Armor FX + Body prop; I / hangar / nameplate / VISION chrome)	Upsert on PUID; fail closed; never Combat power / flight (FS-ECO-012)
XP / Commit / trees / subclass unlock	Display	Mutate
Mission complete / Primary / raid rewards	Display	Mutate
AI fuzzy scores / squad intent / agent tactics (FS-AI-005)	Predict presentation only	Owns selection (Online); Solo = local authority
Character create / delete / reset	Form UI	Pool writers
Fireteam / clan / invites	UI	Policy + consume
EOS / Discord HTTP	May run off-GT	Session authority on server services

4.2 Hit auth (hybrid FPS + melee)

Client same frame          Server Game Thread              Workers
─────────────────          ──────────────────              ───────
Fire / Melee Drive  ──RPC──► Rewind + hitscan / melee notify shape
Muzzle / trail / mark        Demo: reach capsule/box · Full: optional socket sweep
Predicted FX                 Cadence · mag · LOS · Apply FS-DMG ──GE──► HP/Flow
(Full: MM may pick clip)     Reject impossible — Pose Search ≠ auth
                                                    Heuristics / replay
                                                    (never delay GE)

See FS-ARCH-013 · FS-CMB-002 · FS-FX-002 · melee hit docs/superpowers/specs/2026-11-02-melee-hit-registration-design.md · Motion Matching docs/superpowers/specs/2026-11-02-motion-matching-full-design.md (Full + Cinematic Benchmark) · CB product docs/28-cinematic-benchmark.md · Melee Drive implementer (parked) docs/tutorials/melee-drive-guns-singularity.md. Rewind window: 200 ms (TBD-041 locked 2026-11-12).

4.3 Apex Invoke (security)

Origin	Stamp	Inspect Invoke
World-found	`InvokeEligible = true`	Allowed if a main class is unowned
Crafted (Frame / Blueprint + mats)	`InvokeEligible = false`	Hidden; RPC fails closed

Client cannot set the stamp. Trade / mail / stash cannot flip it. FS-PRG-009.

5. Thread affinity

Work	Thread
GAS / GE, movement writes, replication, RPCs, inventory/economy/progression mutations, widget↔gameplay, spawn	Game Thread
Hit auth rewind + trace	Game Thread (cheap)
EOS / HTTP, Discord OAuth, catalog, price feed, save compress, JSON parse, analytics, search on copied array	Worker → marshal to GT
Audio, Niagara, streaming, nav build	Engine threaded systems

Never apply GEs, call RPCs, or write components from a worker. FS-ARCH-012.

Tick discipline (Lyra 5.8) — FS-ARCH-014

Lyra host ships characters/health with Tick disabled. TFA GFPs do the same by default.

Pattern	Owner
Power / Flow / loot / economy / inventory mutate	Server (authority) — timer, event, GAS, or rare server-only Tick
Presentation (camera feel, local VFX)	Client — Tick only if needed; never invent power
Cooldowns / windows / meters	Timers or GAS durations — not per-frame polls
Target search / AimAssist / Counter	On input / notify — never ambient Tick magnet

Enable server-only Tick in BeginPlay when HasAuthority() — not in the constructor via Role.

6. Phase → GFP enable order

Phase	Enable
P0	TFACore, TFAFrontend (Plugify boot GUI), TFAOnline, TFAMaps hub (+ ADDON)
P1	TFACombat spine (camera/move/stance/vitality), TFAOmniVisor (Plugify HUD)
P2	TFAMelee + TFASingularity (Plugify; message-coupled)
P3	TFAWeapons (Plugify) · optional TFAModular
P4	TFACharacterI (+ inventory)
P4b prep	MonetaryPlatform plugin (ledgers + AntiCheat + EntitlementFlags)
P4b	TFAEconomy (money adapter + CF entitlement routes)
P5	TFAProgression
P6	TFACrafting
P7	TFAVision, TFAWorld (maps drawers), TFAAI substrate (when experiences need AI)
P8	TFAWorld missions, TFAMaps content, TFAAI product brains (monsters / patrol; MP bots when match Experiences enable)
P9	TFAOnline social / raids / Ladder
P9b	TFATrust (UI → MonetaryPlatform case API)
P9c	Companion Player API gateway (read: memberships / profiles / Ladder / manifest) — Discord companion bot + BenchMark site; FS-API-*

Companion API data flow (read path):

Dedicated game servers
        │ freeze match / career / Ladder writes
        ▼
TFAOnline Online store (FS-MCH / FS-CAR)
        │
        ├── Companion API gateway ──► Companion Discord bot (X-API-Key)
        │                         └──► BenchMark Leaderboard / third-party apps
        └── Static manifest CDN (Orders, Receivers, Triumphs, …)

Invite Discord (client SDK → EOS_Connect_LinkAccount / invite deep links) stays on TFAOnline social — a different Discord application than the companion stats bot. MonetaryPlatform AntiCheat stays Trust / fraud only.

7. CF / Founding Club entitlements (looks)

GDD: founding-clubs-cf-cosmetics. FS: FS-ECO-012 / FS-PRD-006.

Stackable layers on owned armor: Material (mat_*) + Armor FX (fx_*) + Body prop (prop_* — wings, mantle, trails, pips). Also title_* / club_* / hangar / emote / decal. Looks only — no flight from wings; plate size unchanged.

Website / CF pledge resolve
        │ signed upsert
        ▼
MonetaryPlatform  EntitlementFlags (EOS PUID)
        │
        ├── TFAEconomy (adapter apply only)
        ├── TFAFrontend / Character I / Collections  → materials, FX, props, titles, hangar, nameplate, emotes
        ├── TFAOmniVisor                             → VISION-chip chrome (under mark)
        └── TFAOnline roster presentation            → club tag when badge visible
        ✗  TFACombat / TFAWeapons                    → never read for power / flight

Owner	Job
MonetaryPlatform	Authoritative flag store on PUID; stack lower cosmetics + clubs; primary club = highest Apex club
TFAEconomy	Route apply / sync into platform; no Combat GE
Character I / Frontend / OmniVisor	Present Material + FX + Body prop; plate size / underarmor joints unchanged; no flight
Marketing / Discord / site club page	Out of runtime architecture (ops)

8. Vendor keep list

Keep	Why
LyraGame / LyraEditor	Host experiences, CommonUI, EOS hooks
ShooterCore / Explorer / Maps / Tests / TopDownArena	Reference until TFA experiences replace
SKG + Aim Assist	Guns / attachments / ballistics — wrap
ADDON	SKG-on-Lyra glue only

New TFA systems do not go into ADDON. FS-ARCH-011.