Foliage

Interactive foliage workflow.

Foliage support lets lightweight instanced foliage behave like normal interactables only when the player actually needs to interact with it. The system starts with a virtual foliage focus, then spawns a proxy actor that carries a regular Interactable Component for the confirmed interaction flow.

Core idea: foliage instances stay lightweight in the world. When the player focuses or starts interacting with a configured foliage mesh, Interaction Engine resolves a virtual focus and can spawn a Foliage Proxy Actor to run normal slot logic, multiplayer validation, damage, progress, widgets, and persistence.

How the foliage flow works

Stage	What happens
1. Local detection	The Interactor traces against the world. If the hit belongs to an instanced foliage component whose mesh is registered in the foliage setup, the player receives a virtual foliage focus.
2. Virtual focus	The plugin builds focus data from the matching foliage entry. This allows prompts, glyphs, outlines, and slot display before any proxy actor exists.
3. Server request	When the player starts an interaction or sends a hit, the server validates the foliage instance, distance, line of sight, slot rules, and damage requirements.
4. Proxy creation	The server creates or reuses an `AFoliageProxyActor` for that foliage instance and injects the configured interaction slots into its Interactable Component.
5. Interaction handoff	The pending interaction is transferred to the proxy, so hold, mash, multi-hit, damage, completion, cancellation, and confirmed events behave like a normal actor interactable.
6. Lifecycle resolution	After completion, Blueprint can decide when to hide the proxy, restore the source instance, start regrowth, or destroy the proxy by calling `ResolveProxyLifecycle`.

When to use foliage support

Harvestable trees, bushes, herbs, mushrooms, minerals, or resource nodes placed as foliage.
Large numbers of repeated environmental objects that should remain lightweight until interaction starts.
Objects that need interaction slots, health, hit requirements, widgets, save/load, and multiplayer validation but should not be placed as individual actors.

Required setup

1. Create a Foliage Interaction Database or Data Table On the player's Interactor Component, assign either FoliageDatabase or FoliageDataTable. Each entry maps a foliage static mesh to the interaction data used by the virtual focus and spawned proxy.

2. Add one entry per interactable foliage mesh In each FFoliageInteractionEntry, set FoliageMesh to the static mesh used by the foliage instance. Matching is done against the mesh asset, so the configured mesh must match the foliage instance's mesh.

3. Assign a proxy actor class Set ProxyActorClass to a Blueprint class derived from AFoliageProxyActor. This proxy contains a mesh component and an Interactable Component, and becomes the real interaction target after the server creates it.

4. Configure interaction slots Add one or more InteractionSlots. These are injected into the proxy's Interactable Component. Use them the same way you would configure normal interactable slots: simple, hold, button mash, multi-hit, cooldowns, conditions, feedback, and behavior.

5. Configure the pre-proxy widget and outline Use the entry's Widget and Outline settings to control what the player sees while focusing the foliage before the proxy exists.

Important foliage entry fields

Field	Purpose
`FoliageMesh`	The static mesh that identifies which foliage instances use this entry.
`ProxyActorClass`	The actor class spawned by the server when the foliage instance needs real interaction logic.
`Conditions`	Global conditions checked before the foliage entry can be used.
`Widget`	Prompt, title, description, input action, key fallback, placement, draw size, and visibility distance for the virtual foliage prompt.
`Behaviour`	Controls whether the source foliage instance is hidden when the proxy spawns and whether it is restored when the proxy is destroyed.
`Outline`	Outline settings used while focusing the virtual foliage and by the spawned proxy.
`InteractionSlots`	The slot definitions copied into the spawned proxy's Interactable Component.
`DistantIndicator`	Optional override for proxy distant-indicator behavior.
`ProxyRespawn`	Optional override for proxy respawn/regrowth behavior after `ResolveProxyLifecycle`.

Virtual foliage focus

A virtual foliage focus is not a spawned actor yet. It is a lightweight focus record that stores the source component, instance index, matched foliage entry, hit location, hit normal, instance transform, and stable instance id. Blueprint can inspect it through the Interactor Component.

Blueprint API	Use
`Is Focusing Virtual Foliage`	Returns true while the current focus is a foliage instance that has not necessarily become a proxy yet.
`Get Current Virtual Focus`	Returns the current `FVirtualFoliageFocus` data.
`On Virtual Foliage Focused`	Fires when the interactor starts focusing a virtual foliage target.
`On Virtual Foliage Unfocused`	Fires when the interactor stops focusing that virtual foliage target.

Foliage widget placement

Foliage widget settings support the same on-focus placement concepts as actor interactables, but they are evaluated before the proxy exists. The pre-proxy prompt can be projected near the foliage hit point or placed at a fixed screen anchor.

Use ProjectedNearTarget when the player should read the prompt as part of the world.
Use FixedOnScreen when the foliage prompt should behave like a stable HUD panel.
Use InputAction to let the glyph system resolve the current binding for the foliage prompt.
Use ExplicitKey or InteractionKeyLabel only as fallback display data when no action binding can be resolved.
Use ProxyWidgetOffset only when the spawned proxy needs a different widget offset from the pre-proxy hit-location prompt.

Proxy actor lifecycle

The proxy actor is the bridge between foliage instances and the normal interaction system. It owns the real Interactable Component and exposes foliage-specific events so Blueprint can play animations, spawn particles, award resources, or delay cleanup.

Event or function	Use
`OnProxyReady`	Called when the proxy has been initialized and registered.
`OnFoliageHoldStarted`	Called when a hold-style foliage interaction starts on the proxy.
`OnFoliageHoldProgress`	Called with hold progress for foliage-specific presentation.
`OnFoliageHit`	Called when a hit/damage interaction is confirmed on the proxy. Includes damage and remaining hits.
`OnFoliageCompleted`	Called when the foliage interaction completes. Use this for gameplay result presentation and then resolve the lifecycle when ready.
`OnFoliageInteractionCancelled`	Called when a foliage interaction is cancelled.
`ResolveProxyLifecycle`	Authority-only function that applies the configured lifecycle result: hide proxy, restore or keep the source instance hidden, schedule respawn/regrowth, or destroy when appropriate.
`DestroyProxy`	Authority-only direct proxy destruction path.

Recommended lifecycle: keep bAutoResolveLifecycleOnCompleted disabled unless you specifically want old automatic behavior. In most projects, handle OnFoliageCompleted, play the falling/chopping/harvesting animation, then call ResolveProxyLifecycle on the authority when the presentation is finished.

Source instance and proxy visibility

The source foliage instance and the spawned proxy can be hidden independently. This is useful for trees that fall before disappearing, plants that regrow later, or resources that should leave a stump/proxy behind.

Function	Use
`HideSourceInstance` / `ShowSourceInstance`	Authority-only helpers for hiding or restoring the original foliage instance.
`SetSourceInstanceHidden`	Authority-only setter for the original foliage instance hidden state.
`IsSourceInstanceHidden`	Reads the replicated hidden state for the source instance.
`HideProxy` / `ShowProxy`	Authority-only helpers for hiding or restoring the proxy actor.
`SetProxyHidden`	Authority-only setter for the proxy hidden state.
`IsProxyHidden`	Reads the replicated proxy hidden state.

Damage and multi-hit foliage

Foliage proxy slots can require a damage type. This lets a tree require an axe-like damage type while a rock requires a pickaxe-like damage type. Configure RequiredDamageType on each FFoliageProxySlotConfig when the slot should only accept a specific damage source.

Leave RequiredDamageType empty when any damage type should be accepted.
Use Set Damage Type on the Interactor before sending hits when the current tool changes.
Use GetRequiredDamageTypeForSlot on the proxy when Blueprint needs to inspect the requirement.
Use GetHitsRemaining for UI or proxy-specific presentation during multi-hit interactions.

Multiplayer behavior

Foliage interaction follows the same server-authoritative model as normal interactables. The owning client may show local focus and prediction, but the server validates the foliage instance and creates or reuses the proxy. After the proxy is replicated and registered, the interaction continues on the proxy's Interactable Component.

Do not run final gameplay rewards from local prediction.
Use confirmed interaction events or the foliage proxy events for final results.
Only the authority should call lifecycle and visibility functions such as ResolveProxyLifecycle, HideSourceInstance, and SetProxyHidden.
Use FoliageServerValidationTolerance only to absorb reasonable client/server hit-position differences, not to bypass validation.

Save and load notes

Foliage proxies can capture and restore state snapshots. This allows save/load to remember the source instance id, source transform, hidden source state, hidden proxy state, live proxy state, deferred regrowth, and the proxy's interactable state.

For modern world-level save/load, use the all-foliage proxy snapshot flow documented in the Save and Persistence chapter.
Do not rely only on the original foliage instance index when World Partition or streaming may be involved. The system also tracks a stable foliage instance id and source component path.
Restore foliage state on the authority so replicated hidden/proxy state reaches clients correctly.

Recommended test plan

Place one foliage resource in a controlled test map.
Assign one matching foliage entry with one simple slot.
Verify virtual focus: prompt, glyph, outline, and widget placement.
Start the interaction and confirm the proxy spawns.
Verify OnProxyReady and the expected start/progress/completion events.
Test source/proxy visibility after completion.
Test the same flow as a client in multiplayer.
Only after that, add hold, mash, multi-hit, damage requirements, respawn, and save/load.

Debugging foliage

Use these console variables when foliage focus, proxy spawning, multiplayer handoff, or lifecycle resolution does not behave as expected:

ie.Debug.Foliage.EventTrace 1
ie.Debug.FoliageProxy 1
ie.Debug.Validation 1
ie.Debug.Net 1
ie.Debug.Transaction 1
ie.Debug.SaveLoad 1

Common problems

The prompt does not appear Confirm that the foliage mesh matches an entry in FoliageDatabase or FoliageDataTable, then verify trace channel, collision, FoliageTraceRadius, and widget visibility distance.

The proxy does not spawn Check server validation logs, the proxy actor class, and whether the server can resolve the source foliage component and instance index.

The first client interaction does not continue Enable foliage event trace, network, validation, and transaction logs. Look for proxy registration, client confirmation, and handoff messages.

The source instance disappears on the server but not on clients Make sure visibility changes are made on the authority and are going through the proxy's replicated source/proxy hidden state rather than local-only Blueprint changes.

The completed tree or plant disappears too early Keep lifecycle manual. Play the completion animation first, then call ResolveProxyLifecycle when the presentation is finished.