Skip to content

Gameplay Scaffold

Purpose

This document describes the current C++ gameplay scaffold for Andromeda.

Current goal:

One room, carried salvage, scanner evidence, package assignment, and freeform station placement.

The C++ layer owns gameplay behavior, required component composition, and UI data flow. Blueprints remain the authoring layer for widget layout, art assets, asset references, transforms, tuning, and level placement.

Current C++ Areas

The scaffold is organized by gameplay responsibility:

Source/Andromeda/
  Capabilities/
  Core/
  Placement/
  Player/
  Salvage/
  Station/
  Workstation/
  UI/

See Ownership Boundaries for the dependency rules between these folders.

Player And Interaction

Files:

  • Player/AndromedaCharacter.*
  • Player/AndromedaPlayerController.*
  • Player/AndromedaCarryProviderInterface.*
  • Player/AndromedaCarryComponent.*
  • Player/AndromedaPlacementModeComponent.*
  • Placement/AndromedaPlacementEventSubsystem.*
  • Station/AndromedaStationEventSubsystem.*
  • Capabilities/AndromedaCarryableInterface.*
  • Capabilities/AndromedaFocusCandidateProviderInterface.*
  • Capabilities/AndromedaPromptableInterface.*
  • Capabilities/AndromedaInteractableInterface.*
  • Capabilities/AndromedaCapabilityEventsComponent.*
  • Capabilities/AndromedaScannableInterface.*
  • Capabilities/AndromedaPackageableInterface.*
  • Capabilities/AndromedaScanTypes.h

The player boundary owns input dispatch, carried-object state, focused object tracking, and freeform placement mode. AAndromedaCharacter can call its required native carry and placement components directly because they share the same ownership boundary.

The capability boundary separates focus, prompt, and action:

Can this object be focused?
Can this object show a prompt?
Can this object execute an action?

IAndromedaPromptableInterface owns HUD prompt visibility, prompt text, and an optional prompt event source. Prompt-only objects can show hover text without accepting E input.

IAndromedaInteractableInterface owns only generic interaction: CanInteract(APawn*) and Interact(APawn*).

UAndromedaCapabilityEventsComponent is the reusable capability-change event source. Observed capabilities return it through their own event accessors, such as GetPromptEvents, when their runtime state can change while a listener keeps observing the same object.

IAndromedaCarryableInterface owns the physical pickup, carry, and placement loop. CanBeCarried gates entering carried state; once held, placement is governed by station bounds, collision, and workstation validation rather than by the object refusing to be placed. IAndromedaScannableInterface and IAndromedaPackageableInterface decouple scanner, packager, and station databank behavior from AAndromedaSalvageItem.

AAndromedaCharacter traces forward from the first-person camera each frame. If the hit actor routes the hit to a focus candidate, the character stores it as the focused object. While focused, it subscribes to the promptable target's prompt event source if one exists, so same-object prompt changes are event-driven rather than guessed after input.

The character broadcasts focus changes. The suit HUD owns prompt widget lifecycle:

  • creates UAndromedaInteractPromptWidget from HUD defaults
  • subscribes to character focus changes
  • updates prompt text when focus or focused capability state changes
  • clears or hides the prompt when focus or modal UI state changes

That character-to-HUD connection is event-driven because it crosses from player gameplay ownership into UI presentation ownership.

The character also owns input action dispatch:

  • movement
  • mouse look
  • jump
  • interact
  • suit scan recall request
  • placement mode toggle, axis cycling, and rotation adjustment

IAndromedaCarryProviderInterface is the contract for pawns that expose a carry component. AAndromedaCharacter implements it.

UAndromedaCarryComponent owns the current held actor through IAndromedaCarryableInterface. It is the player's hands and a capsule-child scene component: it provides the held-actor attachment transform, asks the carryable actor to apply carried/released physical state, and does not know about station or salvage classes.

The interact input is contextual. If placement mode is active, E attempts to commit the current preview. Otherwise, carryable actors route to UAndromedaCarryComponent::TryPickUpTarget; generic interactables route to IAndromedaInteractableInterface::Interact. If neither applies, E does nothing.

The Blueprint character should assign input action assets. HUD and controller Blueprint defaults assign UI widget classes. None of these Blueprints should need Event Graph logic for the maintained vertical slice.

Salvage Data

Files:

  • Salvage/AndromedaSalvageItemData.*
  • Salvage/AndromedaSalvageItem.*
  • Station/AndromedaStationDatabankComponent.*

AndromedaScanTypes.h defines the core scan and package data types:

  • EAndromedaHazardRating
  • EAndromedaPackageCategory
  • EAndromedaHandlingSize
  • FAndromedaScanProfile
  • FAndromedaPackageRequirement
  • FAndromedaScanResult
  • FAndromedaScannedItemRecord

UAndromedaSalvageItemData is a UPrimaryDataAsset. It is intended for editor-authored salvage definitions such as DA_DamagedReactorCoil.

It contains:

  • item name
  • manifest claim
  • legal requirement
  • scan profile
  • package requirement

AAndromedaSalvageItem is the physical salvage actor base. A Blueprint item such as BP_DamagedReactorCoil should inherit from it, assign a mesh, and assign a salvage data asset.

The item can:

  • build scan results from its data asset
  • expose a runtime instance ID for station-owned scan memory
  • track whether it has been packaged
  • switch between carried and freeform physics placement states
  • expose prompt, carryable, scannable, and packageable capabilities

The item does not own carry or workstation validation. Carry state belongs to UAndromedaCarryComponent; workstation spatial validation belongs to AAndromedaWorkstation; freeform placement preview and commit rules belong to the player-owned placement mode component.

The item also does not track whether it has been scanned. UAndromedaStationDatabankComponent on the station shell stores scan records by scannable object ID for the current play session.

AAndromedaStation is the station shell actor. It owns the required native station databank component and station access sphere. The inherited Blueprint tunes the access radius/transform/collision settings and places the shell in the level. The station access sphere defines where the suit can connect to the station databank for scan recall. Station access volumes must not overlap; HUD station connection state assumes at most one active station for the owning pawn.

Station access notifications flow through UAndromedaStationEventSubsystem, a domain-specific world subsystem. Stations register while active, keep their own overlap truth, and publish pawn enter/exit transitions through the subsystem. The subsystem also refreshes a pawn against the current station registry so late HUD creation can rebuild current station access state without per-station HUD subscriptions.

The current vertical slice assumes the player controller keeps the same pawn after HUD startup. AAndromedaHUD does not handle pawn possession changes; if future work adds respawn, vehicle/drone possession, cinematic control handoff, or player-character swapping, HUD character subscriptions, focus prompt state, and station access state must be rebound when the owning pawn changes.

UAndromedaPlacementModeComponent is the player-owned freeform placement helper. It reads the carried object, traces from the first-person camera, mirrors its preview mesh as a ghost, checks station bounds through AAndromedaStation, supports yaw/pitch/roll rotation, and asks UAndromedaCarryComponent to release the object with physics when the player commits placement.

Placement commit notifications flow through UAndromedaPlacementEventSubsystem, a domain-specific world subsystem. Placement mode announces that an actor was committed without knowing which workstation cares. Workstations subscribe to the event and refresh their own spatially discovered state, so the workstation remains authoritative for deciding what is currently placed on it.

Scanner

Files:

  • Workstation/AndromedaScannerWorkstation.*
  • Workstation/AndromedaWorkstation.*
  • Workstation/AndromedaWorkstationScreenComponent.*
  • Workstation/AndromedaPackagerWorkstation.*
  • Station/AndromedaStation.*
  • Station/AndromedaStationDatabankComponent.*
  • Station/AndromedaSalvageSpawnPoint.*

AAndromedaWorkstation is the base class for physical workstations that operate on freeform-placed carryable objects. It owns workstation spatial validation, ambiguity rejection, screen-use rules, and workstation-specific follow-up behavior.

AAndromedaScannerWorkstation is the scanner workstation actor. It has:

  • root scene component
  • mesh component
  • placement validator component
  • default placement volume component
  • screen component

The scanner uses the inherited placement validator to find exactly one acceptable carryable object in its placement volume.

The scanner can:

  • build a scan result from that spatial scannable object
  • record scan results in the owning station databank
  • show stored scan data when the same object is scanned again
  • return a clear "No salvage detected" fallback when empty
  • expose the scanned item's required or recommended package handling
  • update its physical scanner screen widget
  • leave the scanned object physical and pickup-enabled

AAndromedaPackagerWorkstation accepts objects that are scannable, packageable, and have a valid scan record in the workstation's owning station databank. It is intentionally separate from the scanner so packaging is a physical work step.

AAndromedaSalvageSpawnPoint spawns a configured salvage item class at BeginPlay. It is the first scaffold for cargo hangar arrivals.

Workstation C++ owns the required root scene, mesh, placement validator, default placement volume, screen, and capability event components. The root scene component anchors workstation-level transforms; mesh, placement volume, and screen components are siblings under it. Placement volumes are query-only validation shapes for freeform-placed objects. The workstation mesh collision is the placement aim surface and must block ECC_Visibility on the tabletop or intended work surface. The inherited screen component is the world-space widget host and the query-only promptable/interactable operation surface for actions such as scanning or packaging. Workstation Blueprints configure mesh assets and collision, placement volume transforms, screen transforms, screen widget classes/draw sizes, and workstation-specific defaults. Workstation Blueprints should not need Event Graph logic for the maintained vertical slice.

Blockout note: the scanner, packager workstation, and inspection table should use the shared SM_Blockout_Workbench mesh for now. Their gameplay differences should come from the C++ class, Blueprint defaults, placement volume tuning, screen component, UI references, and future signage rather than separate blockout geometry.

UI Widgets

Files:

  • UI/AndromedaHUD.*
  • UI/AndromedaInteractPromptWidget.*
  • UI/AndromedaScannerScreenWidget.*
  • UI/AndromedaSuitScanRecallWidget.*

Widget behavior is C++ owned. Widget Blueprints provide layout and named Designer widgets.

UAndromedaInteractPromptWidget owns:

  • prompt text storage
  • prompt visibility
  • prompt text block update

Expected optional Designer bindings:

  • PromptRoot
  • PromptTextBlock

UAndromedaScannerScreenWidget owns:

  • idle/item-ready/error screen state
  • scan result storage
  • scan text updates
  • package requirement text updates

Expected optional Designer bindings:

  • StatusText
  • ItemNameText
  • ManifestText
  • LegalRequirementText
  • RadiationText
  • MassText
  • SerialText
  • HazardText
  • PackageRequirementText
  • NotesText

The scanner screen widget is informational only and is hosted by the inherited ScreenComponent on BP_ScannerWorkstation. The screen component forwards screen-operation interaction to the scanner workstation. Item placement happens through freeform placement; pickup is routed by the character through the salvage item's pickup capability.

UAndromedaSuitScanRecallWidget owns the read-only helmet recall presentation for records queried from the currently connected station databank. The HUD creates it from HUD defaults, toggles it from the character's recall request event, and leaves game input active.

Expected optional Designer bindings:

  • RecallRoot
  • StatusText
  • RecordsText

Maintained vertical-slice widgets should not require Event Graph logic.

AAndromedaHUD owns suit HUD widgets. It subscribes to character focus and scan recall events, subscribes once to the station event subsystem, tracks the single station currently connected to its pawn, and queries that station's databank when scan recall is opened.

Shared Text

Shared player-facing prompts, fallback labels, scanner status text, and enum display labels are centralized through the ST_AndromedaText string table source:

Content/Andromeda/Localization/StringTables/ST_AndromedaText.csv

Code should access these keys through AndromedaText or domain helpers such as AndromedaSalvageText. Item-specific copy remains authored in data assets.

Current Content Layer

Core Blueprint assets:

Content/Andromeda/Blueprints/Core/BP_PlayerCharacter
Content/Andromeda/Blueprints/Core/BP_PlayerController
Content/Andromeda/Blueprints/Core/BP_SalvageBayGameMode

Gameplay content assets:

Content/Andromeda/Blueprints/Items/BP_DamagedReactorCoil
Content/Andromeda/Blueprints/Station/BP_Station
Content/Andromeda/Blueprints/Station/BP_ScannerWorkstation
Content/Andromeda/Blueprints/Station/BP_PackagerWorkstation
Content/Andromeda/Data/DA_DamagedReactorCoil
Content/Andromeda/Maps/L_SalvageBay_Prototype

UI assets:

Content/Andromeda/Blueprints/UI/WBP_InteractPrompt
Content/Andromeda/Blueprints/UI/WBP_ScannerScreen
Content/Andromeda/Blueprints/UI/WBP_SuitScanRecall

Input assets:

Content/Andromeda/Input/IA_Interact
Content/Andromeda/Input/IA_Jump
Content/Andromeda/Input/IA_MouseLook
Content/Andromeda/Input/IA_Move
Content/Andromeda/Input/IA_ScanRecall
Content/Andromeda/Input/IMC_Player

Placement input assets:

Content/Andromeda/Input/IA_TogglePlacementMode
Content/Andromeda/Input/IA_CyclePlacementAxis
Content/Andromeda/Input/IA_AdjustPlacementRotation

Verification

The current vertical slice should verify:

  1. Player can move, look, jump, and interact.
  2. Prompt appears when aiming at an interactable item or workstation screen component.
  3. Loose item pickup works.
  4. Freeform placing an item inside the scanner placement volume and picking it back up work; running the scanner works through the screen component.
  5. Scanner displays reactor coil data through the physical scanner screen.
  6. Suit scan recall opens inside a StationAccess area and lists records from the connected station databank.
  7. Packaging assigns a package, then allows the packaged item to be picked back up.
  8. Placement mode toggles while carrying, shows a ghost, rotates on yaw/pitch/roll, and commits with physics inside station bounds.
  9. Placement mode cancels cleanly, rejects out-of-station placement, and shows workstation warning state without blocking commits.