Bury storage module #

Technical Documentation
Component scope: AC_Buriable_Storage and its owner/tool integration points.

---

Introduction #

The Bury Storage Module is a clean, modular way to let players bury and recover world storage actors such as chests, caches, or any other loot container that should be hidden underground. The implementation shown here is centred on the AC_Buriable_Storage component and the actor/tool integrations that drive it.

At runtime, the component is responsible for validating whether the current surface can be dug, tracking bury progress, moving the owning actor up or down over time, broadcasting state changes, and playing dig feedback such as Niagara and sound effects. The digging tool is responsible for finding a valid target and calling into the component, while the owning actor decides how to react to the buried state, such as disabling interaction.

• Supports burying and digging back up through the same progress-driven function.
• Uses physical surface filtering so storage can only be buried on approved surfaces.
• Broadcasts events that let the owning actor react without hard-coupling storage logic into the component.
• Works with save/load by exposing a Loaded event that can be used to reapply owner-side state after restoration.
• Can be attached to storage actors or repurposed for any actor that needs underground hide/reveal behaviour.

Demo overview boards showing the intended gameplay loop, chest usage prompt, and physical surface filtering rules.

---

System Overview #

The system is deliberately split into three responsibilities so that the bury logic remains reusable.

The full runtime flow looks like this:

• A digging-capable tool performs a trace and identifies a compatible buriable actor.
• The tool stores the actor’s AC_Buriable_Storage component and triggers Progress Dig.
• Progress Dig validates the ground below the actor with Check Surface Type and updates Current Bury Progress.
• Based on whether the actor is currently buried or unburied, the module calculates a target location and calls Move Storage Actor.
• Move Storage Actor starts a short timer loop, while Lerp Storage Actor To Target gradually updates the owner location and rotation.
• When progress reaches the configured threshold, the component marks the actor buried or dug up and broadcasts events so the owner can react.

---

Adding the Module to a Buriable Actor #

This documentation intentionally scopes itself to the buriable module rather than the parent storage framework. From the evidence supplied, the minimum practical setup for a buriable actor is:

• Add AC_Buriable_Storage to the actor that should be buryable.
• Configure the component defaults: number of hits to bury, number of hits to dig up, bury depth, allowed physical surfaces, and optional VFX/SFX.
• Ensure a digging tool can obtain a reference to the component and call Progress Dig on it.
• Bind owner-side reactions to the component dispatchers. The most important example shown in the demo is interaction enable/disable handling.
• If the project uses save/load, reapply owner-side state by reacting to the Loaded dispatcher after data is restored.

This keeps the module reusable: the component handles bury behaviour, while each actor decides what “buried” means for that specific gameplay object.

Owner-side integration example. The chest actor binds to On Bury Progress Changed, disables interaction while burying or buried, and re-applies that state when Loaded fires after save restoration.

---

Details Panel / Important Variables #

The component contains a small but important set of configuration values and runtime state variables. The first group is what most developers will edit in defaults; the second group is maintained by the system during play.

Variable list from AC_Buriable_Storage.

---

Event Dispatchers #

The module exposes a small event surface that makes it easy for owning actors or external systems to respond without needing to duplicate the internals.

Event dispatchers exposed by AC_Buriable_Storage.

---

Functions Explained #

---

Progress Dig #

Progress Dig is the main gameplay-facing function. Each successful dig action calls into this function, which then decides whether the actor should continue moving down into the ground or come back up. It is responsible for validating the surface, updating Current Bury Progress, deciding the target location, and handling completion rules for buried and dug-up states.

• Calls Check Surface Type to make sure the actor is standing on an approved physical surface.
• Stores the last valid intersect location so visual and audio feedback can be spawned from the correct place.
• Increments or decrements bury progress depending on whether the actor is currently buried.
• Calculates the target world location by offsetting the owner up or down using Distance To Bury Down.
• Marks Is Buried and Is Being Buried as progress reaches its thresholds, then broadcasts On Bury Progress Changed so the rest of the system can react.

Progress Dig function. This is the primary public gameplay entry point for the bury module.

---

Check Surface Type #

Check Surface Type traces below the owner actor and inspects the physical surface that was hit. This prevents burying on surfaces that should not support digging, such as metal floors or stone, while still letting the same module work across multiple levels and material setups.

• Builds a vertical trace beneath the owner actor rather than tracing from the actor mesh itself.
• Checks the hit result’s physical surface against the Allow Burying On These Surfaces array.
• Returns both a boolean result and the intersect location so callers can both validate the action and place VFX/SFX at the correct point.

Check Surface Type function. The result gates the bury action and provides the ground hit location.

---

Begin Play, Load, and Feedback Flow #

At startup, the component binds its internal feedback logic and caches its original rotation so it can later blend between a stable base pose and a more animated movement pose.

• Event Begin Play runs on authority, binds a local custom event to On Bury Progress Changed, and caches Actor Base Rotation from the owner.
• The bound custom event forwards into the multicast event so all relevant clients can receive the bury progress feedback.

When On Bury Progress Changed is multicast, the component spawns the configured Niagara system and sound at Last Surface Intersect Location. This makes every successful dig action feel grounded in the world and tied to the exact surface that was hit.

The save/load entry point is intentionally small: Event On Load simply calls Loaded. This keeps the component generic while still giving the owning actor a reliable post-load signal it can use to restore interaction state or other presentation logic.

Top: Begin Play authority setup. Middle: multicast feedback event used for VFX/SFX. Bottom: save/load hook that broadcasts Loaded.

---

Movement and Bury Progression #

Movement is deliberately split into a start event and a lerp loop. Move Storage Actor sets up the move, introduces slight rotation variation, resets the timer state, and starts a repeating timer. Lerp Storage Actor To Target performs the actual interpolation each step until the move is complete.

• Move Storage Actor caches a Desired Rotation built from the base rotation plus a small randomised angle.
• A timer is created only when needed and points to Lerp Storage Actor To Target.
• Lerp Storage Actor To Target increments Current Location Lerp Time using Move Storage Actor Timer Interval.
• The owner location is updated through a vector lerp toward the target location.
• The owner rotation is also blended so the chest feels like it is settling into or being pulled out of the ground rather than snapping instantly.
• The timer is cleared once the move completes.

Move Storage Actor. This event prepares the interpolation and starts the timer-driven move loop.

Lerp Storage Actor To Target. This applies the location and rotation updates until the move is finished.

---

Tool Integration #

The demo uses a child of BP_Melee_Equipment as the digging tool. The important point is not the parent melee logic, but the fact that the tool only needs a very small amount of bury-specific logic to drive the module.

• The tool performs a forward box trace.
• It loops through hit results and casts to the buriable chest actor.
• From the hit actor it pulls the AC_Buriable_Storage component and stores that reference.
• A separate dig-progress event calls Progress Dig on the stored component.

This means the tool is only responsible for target detection and access control. The actual bury rules stay inside AC_Buriable_Storage, which is exactly what makes the module portable across different projects and tool types.

Example tool-side integration. A traced hit produces a buriable actor reference, then the stored AC_Buriable_Storage component is used to call Progress Dig.

---

Owner Actor Integration #

The owner actor shown in the demo binds to On Bury Progress Changed and uses the component’s Is Being Buried state to toggle interaction. In practice, this is the pattern developers should follow for any owner-specific reaction that should not be hard-coded into the component.

• Bind owner events on Begin Play.
• React to On Bury Progress Changed by reading component state and applying actor behaviour such as interaction enablement, prompt visibility, or collision changes.
• React to Loaded so those same owner-side behaviours are restored when a saved game is resumed.

Because this logic lives on the owner, the same component can drive a chest, a buried stash, a quest container, or any other actor with different interaction rules.

The owning actor binds to the module event and reuses the same logic after load restoration.

---

CUSTOMISATION HOW-TOs #

---

How to require more effort to bury than to dig up #

Set Amount Of Hits To Bury higher than Amount Of Hits To Dig Up. This creates a system where hiding loot takes longer than recovering it, which is useful when you want burying to be a deliberate commitment while still letting a player reclaim the stash quickly later.

• Raise Amount Of Hits To Bury to increase the number of successful dig actions needed before Is Buried becomes true.
• Leave Amount Of Hits To Dig Up lower if recovery should feel faster.
• Invert the relationship if you want digging a stash back out to be the more demanding action.

---

How to support only specific terrain types #

Populate Allow Burying On These Surfaces with only the physical surfaces you want to support. For example, allowing Grass and Dirt but excluding Metal and Stone immediately turns the same component into a terrain-aware bury system.

• Confirm the project’s physical materials resolve to the correct EPhysicalSurface values.
• Add only approved surfaces to the array on the component defaults.
• Use the demo pattern to present this clearly to players if a failed dig should have feedback rather than silently doing nothing.

---

How to add a tool gate, stamina cost, or cooldown #

Keep AC_Buriable_Storage unchanged and add the restriction on the tool side before calling Progress Dig. This is the cleanest extension point because the component stays reusable while each project decides which tools or player states are allowed to dig.

• Before storing the component or calling Progress Dig, verify the equipped tool type, gameplay tag, stamina value, or cooldown state.
• Only call Progress Dig when those conditions pass.
• Optionally play a separate failure sound or UI response on the tool when the player is not allowed to dig.

---

How to make buried actors do more than disable interaction #

Bind extra owner-side reactions to On Bury Progress Changed, On Buried, or On Dug Up. The supplied chest example only toggles interaction, but the same pattern can also drive collision, widget visibility, quest logic, sound states, lock states, or minimap markers.

• Use On Bury Progress Changed when you need to react immediately as the state changes.
• Use On Buried and On Dug Up when you only care about the fully-complete transition.
• Keep these reactions on the owning actor so the core component remains generic.

---

How to change the visual feel of burying #

There are three main levers for the feel of the movement: Distance To Bury Down, Move Storage Actor Timer Interval, and the rotation behaviour inside Move Storage Actor and Lerp Storage Actor To Target.

• Increase Distance To Bury Down for a deeper burial result.
• Adjust Move Storage Actor Timer Interval to make the interpolation feel snappier or slower.
• Reduce or expand the random angle range used when Desired Rotation is built if you want less or more wobble during movement.
• Swap Niagara and sound assets to better match sand, soil, snow, ash, or magical burial themes.

---

How to reuse the module on non-chest actors #

The component itself is not chest-specific. To reuse it on another actor, attach AC_Buriable_Storage, make sure the tool can discover that actor type and obtain the component reference, then bind whatever owner-side behaviour makes sense for that actor when buried or restored.

• The actor can be a stash bag, trap cache, relic container, or even a non-storage gameplay object.
• The key requirement is that the owner can move down or up and react sensibly to the component events.

---

Troubleshooting and Implementation Notes #

• Cannot bury on valid-looking ground: check the physical material assigned to the surface and confirm that its EPhysicalSurface is present in Allow Burying On These Surfaces.
• Digging plays no feedback: verify Niagara System To Play or Sound To Play When Digging is assigned, and confirm Last Surface Intersect Location is being returned from Check Surface Type.
• Actor never moves: confirm the tool actually stores a valid AC_Buriable_Storage reference and that Progress Dig is being called.
• Interaction state is wrong after load: ensure the owner actor listens to Loaded and reapplies its interaction logic, just like the demo chest example.
• Actor behaviour is too tightly coupled: keep project-specific reactions on the owner or tool side rather than adding storage-specific logic directly into AC_Buriable_Storage.

In its current form, the module is already practical for production use because it isolates the digging rules, surface validation, movement, and event broadcasting into one reusable component. Most customisation work will happen around it rather than inside it, which is generally the right shape for a marketplace-ready gameplay module.