Swap Core

Swap Core is a server-authoritative mesh-swap and regrow framework. It continuously scans the world around a player character for static meshes that match entries in a data table, removes matching instances, spawns a configurable pickup actor in their place, and later restores them with an optional animated regrow effect.

The system has no built-in dependency on any inventory or gameplay framework. Item delivery is handled entirely through Blueprint delegates and overrideable functions, so it integrates cleanly with any item system — struct-based, data-asset-based, data-table-based, or custom.

Two-Component Architecture

The system uses two components that must both be placed on the same actor (typically the player character). The swap component automatically locates the respawn component on the same owner via GetOwner().

Complete Detection-to-Respawn Flow

The Foliage Table property on the swap component accepts a UDataTable asset whose row type is FFoliageSwapRow. Each row maps one source mesh to a complete set of harvest and respawn rules. You can have an unlimited number of rows — one per mesh type you want to make harvestable.

Creating the Asset

Foliage Swap — Core Fields

Respawn Settings

Regrow Animation Settings

World Partition Settings

Row Validation Rules

A row is invalid (skipped silently at startup) if:

• Source Foliage Mesh is null
• None of Harvest Actor Class, Payload Class, or Payload Data Table is set
• RespawnTimeMin > 0 and RespawnTimeMax > 0 and RespawnTimeMin > RespawnTimeMax

Invalid rows are reported by Validate Setup.

Every row can carry an arbitrary array of named, typed variables called Custom Payload Variables. These flow through OnPayloadHarvested as the CustomVars output pin and are accessible in Blueprint without any C++ code.

FFoliagePayloadVariable Struct

Example Row Configuration

A row for a rare herb might have these custom variables:

Reading Custom Vars in Blueprint

In your OnPayloadHarvested event, the CustomVars pin gives you a TArray<FFoliagePayloadVariable>. Loop through the array and match by VarName:

// Example flow in Blueprint pseudocode
OnPayloadHarvested → For Each Loop (CustomVars)
    ├─ Branch: Array Element.VarName == "Rarity"
    │   └─ Use IntValue → set item icon rarity border
    ├─ Branch: Array Element.VarName == "IsQuestItem"
    │   └─ Use BoolValue → lock item in inventory
    ├─ Branch: Array Element.VarName == "HarvestSFX"
    │   └─ Cast ObjectValue to SoundCue → Play Sound at Location
    └─ Branch: Array Element.VarName == "XPGain"
        └─ Use FloatValue → Add to player experience

There are three independent ways to configure what happens when a mesh is harvested. They can be combined — for example, a Harvest Actor for the world presence and a Payload Class for inventory delivery.

Mode A — Harvest Actor Only

Set Harvest Actor Class. No Payload Class or Data Table. The system spawns (or retrieves from pool) the specified actor at the harvest location. OnPayloadHarvested does not fire. The spawned actor manages its own interaction and inventory logic internally.

// Row config for Mode A:
Source Foliage Mesh  = SM_Bush_01
Harvest Actor Class  = BP_BushPickup       // your custom BP actor
Respawn Time         = 20.0
// BP_BushPickup handles its own overlap, interaction, and item grant logic

Best for: simple pickups with no inventory integration, prototype setups, or actors that initialize themselves.

Mode B — Payload Class (Blueprint/DataAsset driven)

Set Payload Class to any UObject subclass. This is the class that represents the item type — it is not spawned in the world, it is the data. OnPayloadHarvested fires on the server with this class and the quantity. To also place a visible actor in the world, set Default Payload World Actor on the component (used as a generic pickup) or Payload World Actor on the row (per-row override).

// Row config for Mode B:
Source Foliage Mesh        = SM_Crystal_Blue
Payload Class              = BP_CrystalItem      // a UObject/DataAsset subclass
Payload Quantity           = 3
// On component: DefaultPayloadWorldActor = BP_GenericPickup

// In character OnPayloadHarvested event:
// PayloadClass output pin = class reference to BP_CrystalItem
// Use to create instance, look up defaults, or pass to inventory AddItem(PayloadClass, Quantity)

Best for: Blueprint-class-based inventory systems, DataAsset item definitions, any system where items are represented as UClass references.

Mode C — Data Table Row (Row-Name driven)

Set Payload Data Table (your existing item data table) and Payload Row Name (the key of the row for this item). OnPayloadHarvested fires with the data table reference and row name. Your inventory system reads the row itself. Set Default Payload World Actor on the component for a world-space pickup actor. If bUseReflectionInit is enabled and the param names are configured, the system can initialize the pickup actor automatically via reflection.

// Row config for Mode C:
Source Foliage Mesh   = SM_Mushroom_Red
Payload Data Table    = DT_Items              // your item definitions table
Payload Row Name      = Mushroom_RedCap       // key in DT_Items
Payload Quantity      = 2
// On component: DefaultPayloadWorldActor = BP_GenericPickup

// In character OnPayloadHarvested event:
// PayloadDataTable + PayloadRowName → pass directly to your inventory AddItemFromRow(Table, RowName, Qty)

Best for: Any inventory system where items are defined as data table rows (struct-based inventories, data-driven systems).

Combining Modes

Harvest Actor and a Payload Class/DataTable can coexist in the same row:

// Combined: spawn a specific VFX actor AND deliver payload data
Source Foliage Mesh   = SM_Ore_Gold
Harvest Actor Class   = BP_OreNode_VFX        // shows mining VFX, has its own collision
Payload Data Table    = DT_Items
Payload Row Name      = Ore_Gold
Payload Quantity      = 5

Setup Group

Detection Group

Performance Group

Cooldown Group

Replication Group

World Partition Group

Debug Group

Replicated Stats

BlueprintCallable Functions

Respawn Core

Animation Settings

Distance & Instant Spawn Settings

Instance Matching Settings

Batch Processing Settings

World Partition Settings

Respawn Component Events

Respawn Component Blueprint Functions

All delegates are BlueprintAssignable — bind them via Add Dynamic or the component's bound event node in the character's Event Graph. Server-only events fire on the server; multicast events fire on all machines.

Both components expose override points via BlueprintNativeEvent — functions with a C++ default implementation that you can override in a Blueprint subclass of the component, or in your character Blueprint if it owns the component. Override these by right-clicking the function name in Blueprint and choosing Add Override.

UniversalFoliageSwapComponent Overrides

FoliageRespawnComponent Overrides

// Example: CanHarvestInstance override in character Blueprint
function CanHarvestInstance(StaticMesh Mesh, Vector Location) → bool

// Inside override:
// Get equipped item slot → check if harvesting tool is equipped
// Get required skill level from row (via GetRowForMesh) → compare with player skill
// If conditions not met → play denial feedback → return false
// Otherwise return true (call parent)

Swap Core has no built-in inventory knowledge. Integration is always done in Blueprint using one of three approaches, depending on how your inventory identifies items. No C++ changes are required for any of them.

Integration Path Matrix

Pattern A: Data Table Row Handle Integration

Most struct-based inventories use an FDataTableRowHandle to identify items. Build it from the delegate pins:

OnPayloadHarvested fires (server-side)

Pins available:
  PayloadDataTable  →  UDataTable* (your item definitions table)
  PayloadRowName    →  FName       (the row key, e.g. "Herb_Sage")
  Quantity          →  int32

Blueprint flow:
  Make DataTableRowHandle
    ├─ DataTable  ← PayloadDataTable pin
    └─ RowName    ← PayloadRowName pin

  → Inventory Component → Add Item From Row Handle(Handle, Quantity)

// This works with any inventory where AddItem accepts an FDataTableRowHandle

Pattern B: Blueprint Class / DataAsset Integration

For systems where items are represented as Blueprint class references or DataAssets:

OnPayloadHarvested fires (server-side)

Pins available:
  PayloadClass   →  UClass*    (class reference to e.g. BP_HerbItem_Sage_C)
  Quantity       →  int32

Blueprint flow for class-based systems:
  → Inventory Component → Add Item By Class(PayloadClass, Quantity)

Blueprint flow for DataAsset-based systems:
  GetClassDefaultObject(PayloadClass)        // gets CDO = the data asset instance
  → Cast to UMyItemDataAsset
  → Inventory Component → Add Item From Asset(Asset, Quantity)

Pattern C: InitializePayloadActorBP Override (Zero Blueprint wiring per-mesh)

When your inventory requires calling a specific function on the pickup actor (and you can't or don't want to use the reflection path), override InitializePayloadActorBP in your character or a component subclass:

// Override InitializePayloadActorBP in your character Blueprint:
function InitializePayloadActorBP(Actor Actor, FFoliageSwapRow Row)

// Inside the override:
Cast Actor → BP_MyPickupActor
  → Set ItemDataAsset    = GetClassDefaultObject(Row.PayloadClass) → Cast to UMyItemDA
  → Set Amount           = Row.PayloadQuantity
  → Set SkeletalMesh     = Row.PayloadSkeletalMesh     // if needed
  → Call ActivatePickup()

// This runs once per harvest for every row that has a PayloadClass set.
// One override handles all mesh types in the data table.

Reflection Path (bUseReflectionInit)

Enable this when your inventory pickup actor has a known initialization function that accepts the item class and quantity, and you want zero Blueprint wiring. Configure on the component:

// Component settings for a system with: SetPickup(FPickupConfig Config) function
bUseReflectionInit      = true
PayloadInitFunctionName = SetPickup          // exact function name
PayloadClassParamName   = ItemClass          // property inside FPickupConfig
PayloadQuantityParamName = Quantity          // int32 property inside FPickupConfig

// The system will call Actor->SetPickup(Config) automatically,
// injecting Row.PayloadClass into Config.ItemClass
// and Row.PayloadQuantity into Config.Quantity.
// Works for both struct-param and direct-param function signatures.

Object Type vs Mobility

Actor pooling pre-spawns harvest actors at BeginPlay and reuses them rather than spawning/destroying on every harvest. This eliminates spawn cost, garbage collection pressure, and the one-frame visual gap caused by actor registration.

How It Works

Pool Configuration

• bUseActorPooling — enables/disables the entire system
• ActorsPerPool — actors pre-spawned per class. Set to the maximum number of that mesh type visible simultaneously
• The pool grows dynamically if demand exceeds the pre-spawned count — there is no hard cap on pool size, only on total active harvestables (MaxActiveHarvestables)

Pool Size Monitoring

// In Blueprint, monitor pool health during development:
GetPoolSizeForClass(BP_MyPickup_C)   → how many are available right now
GetActiveHarvestCount()             → how many are currently in the world
GetStatsSummary()                   → formatted string with all metrics

Pool Reconciliation

A periodic reconciliation pass (every ~10 seconds) compares the expected pool count against actual weak pointer validity. This automatically corrects drift caused by edge cases like world resets or garbage collection. The log will report corrections as [ReconcilePoolCounts] Count drift detected for class X: Tracked=N, Actual=M. Correcting....

Swap Core is designed for server-authoritative multiplayer. All harvest decisions happen on the server. Clients receive multicast RPCs to mirror the visual state.

Server vs Client Responsibilities

Setup for Multiplayer

• The UniversalFoliageSwapComponent must be on an actor that has authority on the server. A player-owned character pawn typically fulfills this when using a listen or dedicated server.
• bForceReplicateHarvestActors = true — ensures pickup actors are replicated to all clients
• bForceAlwaysRelevantHarvestActors = true — ensures all clients receive the actor even when far away. Disable and let net relevancy cull for large worlds with many concurrent harvests.
• The component itself has SetIsReplicatedByDefault(true) — the component replicates stats and triggers multicast RPCs automatically.

Single-Player Configuration

For single-player games, you can save bandwidth and object overhead:

// On the component, for single-player:
bForceReplicateHarvestActors         = false
bForceAlwaysRelevantHarvestActors    = false
bHandleWorldPartition                = false   // unless using WP

World Partition + Multiplayer Notes

In a World Partition + multiplayer combination, harvest state is tracked per-server using the grid cell key system. All connected clients receive multicast RPCs when cells stream in/out. The Multicast_PauseRegrowAnimation and Multicast_ResumeRegrowAnimation RPCs on the respawn component ensure client-side animations stay synchronized with server streaming state.

World Partition levels dynamically load and unload cells as players move. Swap Core handles this via level streaming event subscriptions on both components.

How Streaming is Handled

Configuration Checklist

• Both components: bHandleWorldPartition = true
• Swap component: bAutoResumeOnStreamIn = true
• Respawn component: bPauseRespawnsWhenUnloaded = true, bResumeRespawnsOnLoad = true
• Row: Persist Across Streaming = true on rows where you want timers to survive streaming
• Swap component: StreamingCheckInterval = 2.0 (default) — adjust if streaming occurs very rapidly

Swap Core supports meshes spawned by Unreal's PCG system at runtime. PCG-generated HISM and ISM components are automatically detected and registered when the PCG graph completes generation.

How PCG Integration Works

• The plugin checks for the PCG plugin at build time. If found, it compiles with SWAPCORE_PCGENABLED=1 for all build targets (Editor, Development, Shipping).
• The swap component subscribes to the OnPCGGraphGenerated callback at BeginPlay.
• When a PCG graph generates or regenerates, the component scans new components for matching meshes and adds them to the tracked set (PCGManagedComponents).
• PCG-generated ISM and HISM components are handled by the same code paths as manually-placed ISM/HISM, with the same scale-to-zero and multicast RPC system.

Requirements for PCG Meshes

1. The PCG graph must use a Spawn Static Mesh node outputting to a StaticMeshComponent (generates an ISM or HISM).
2. The mesh asset assigned in the PCG graph's Spawn Static Mesh node must match the Source Foliage Mesh in the data table row exactly (same asset reference).
3. The PCG component's actor must use WorldStatic collision object type (default for PCG-generated actors).

Runtime PCG Regeneration

If a PCG graph regenerates at runtime (e.g., dynamic world generation), the swap component re-scans for new components automatically via the callback. Previously-harvested locations are preserved in the active harvestables map, so regrown mesh instances from re-generation are not immediately re-harvested.

Key Performance Levers

Recommended Settings by Project Type

// Small/Linear Level (corridor game, dungeon)
CheckInterval          = 0.25
DetectionRadius        = 200
MaxOverlapsPerCheck    = 32
ActorsPerPool          = 10
bUseBatchProcessing    = true

// Open World (large terrain, many foliage instances)
CheckInterval          = 0.4
DetectionRadius        = 300
MaxOverlapsPerCheck    = 64
ActorsPerPool          = 20
bUseBatchProcessing    = true
MaxRespawnsPerBatch    = 10
bUseDistanceBasedInstantSpawn = true
InstantSpawnDistance   = 5000    // 50m distant = instant

// Dense Forest / Gathering Game
CheckInterval          = 0.2
DetectionRadius        = 250
MaxOverlapsPerCheck    = 128
MaxSwapsPerCheck       = 20
ActorsPerPool          = 40
bUseRenderSync         = true
AnimationTickRate      = 20

Debug Visualization

Enable bDebugDraw = true on the swap component to draw colored debug points at every detected foliage location during each detection pass:

• Cyan — HISM/ISM instance detected at that location
• Yellow — StaticMeshComponent detected at that location

No debug points at a foliage location means that location was not found by the sphere overlap. Check ObjectTypesToQuery.

Verbose Logging

Enable bVerboseLogging = true on both components to get detailed Output Log output. Each detection tick logs:

• [RunDetection] Overlap component: [name] (Class=[class], Owner=[actor], ObjType=[channel]) — every component found
• [ProcessStaticMesh] SKIP — no static mesh on component [name] — mesh is missing
• [ProcessStaticMesh] SKIP — mesh '[name]' not in MeshSwap data table — mesh not in table
• [ProcessStaticMesh] SKIP — mesh '[name]' at [loc] is [dist]cm away, outside InteractionRadius [r]cm — outside interaction range
• [ProcessStaticMesh] SKIP — CanHarvestAtLocation blocked — cooldown, regrow, or already seen
• [ProcessStaticMesh] PROCEEDING to harvest '[name]' at [loc] — harvest will execute

Stats

// Call in Blueprint (e.g. on a debug key):
string Stats = GetStatsSummary()
// Returns something like:
"Harvests: 42 success / 3 failed | Respawns: 38 | Avg Detection: 0.8ms | Pool: BP_Pickup_C=15/20 available"

// Individual stats:
HarvestsSucceeded   // replicated int32
HarvestsFailed      // replicated int32
RespawnsCompleted   // replicated int32 (on both components)
GetActiveHarvestCount()      // currently harvested meshes
GetPoolSizeForClass(Class)   // available actors in pool

// Respawn component:
GetActiveRespawnCount()     // pending respawns
GetPausedRespawnCount()     // WP-paused respawns
GetBatchQueueSize()         // queued for batch

Validate Setup

With the UniversalFoliageSwapComponent selected in the Details panel, click Validate Setup. This checks and reports:

• FoliageTable not assigned
• FoliageTable has zero rows
• Rows with null Source Foliage Mesh
• Rows with no payload configured
• Rows with invalid RespawnTimeMin/Max range
• DetectionRadius ≤ InteractionRadius (likely mis-configuration)
• bUseReflectionInit = true but PayloadInitFunctionName is None
• No ObjectTypesToQuery channels (will default to WorldStatic)
• FoliageRespawnComponent not found on owner