Technical Guide and User Guide

For shared setup guidance, see the Migration Guide and Integration Guide. Use the System Atlas to look up functions, variables, events, components, and ownership references. Use this page for Trap Defense System-specific setup, runtime behavior, extension points, and integration notes.

This document explains the Hyper Defense / Trap System from both an implementation and designer-facing point of view. It covers the trap manager component, trap states, trigger actors, buildable inheritance, resource requirements, damage handling, individual trap Blueprints, and common extension workflows.

Overview

The Defense / Trap System is a Blueprint-based trap framework for Unreal Engine projects. It provides reusable trap actors, external trigger actors, trap state management, damage application, inventory/resource requirements, and buildable-world integration.

At a high level, the system is built around AC_TrapManager. The trap actor owns this component and uses it as the central authority for trap state, damage, activation rules, automatic resets, trapped actor tracking, trap effects, and resource requirements. Child trap Blueprints then implement their own visuals and special behaviour by responding to the trap manager state changes.

The system is intended to support two different usage styles at the same time:

Designer-facing placement, where a trap can be placed in a level, connected to an external trigger, armed, activated, and tested without rewriting the manager logic.

Technical extension, where developers can create new trap child Blueprints that reuse the existing manager, interaction, buildable, inventory, and damage flow.

The demo world shows several trap examples, including ground spikes, wall spikes, fly swatter jaws, double fly swatters, a hanging rope snare, a log cleaver, a spiked spinner, static spikes, a trap door, pressure plates, trip wires, lever triggers, and a rolling boulder.

Spike trap sign from the demo level.

System Architecture

The trap system is built from a small set of shared pieces rather than one large monolithic Blueprint. The most important design point is that most traps share the same base class and component layout, while the boulder is handled separately because it is primarily physics-driven.

The inheritance relationship matters because users should not recreate interaction, building, connection, resource, or trap-state handling for every new trap. A normal new trap should be created as a child of the appropriate trap base, then only the unique behaviour should be added in the child.

Core runtime flow

A typical trap uses the following runtime flow

The trap is built or placed into the world through the buildable actor flow inherited from BP_Buildable_Base.

The trap owns AC_TrapManager, which holds the current state and configuration.

The player or an external trigger attempts to progress or trigger the trap.

AC_TrapManager validates whether the current state can transition to the desired state.

The trap child receives the Trap State Changed event and runs its own animation, timeline, collision, physics, or damage logic.

Damage is applied through Hyper attribute/damage functions, and optional trap effects are constructed and applied.

The trap either resets automatically, moves back to Armed, returns to Unarmed, enters Released, or waits for player interaction depending on configuration.

Trap State Enum and Requirement Struct

E_DefenseSystem_Trap_State

E_DefenseSystem_Trap_State defines the shared state machine vocabulary used by AC_TrapManager and the trap child Blueprints. The same enum is used for interaction text, allowed state transitions, automatic reset logic, animation state selection, and resource requirements.

Trap state enum used by the trap manager and child Blueprints.

F_DefenseSystem_TrapState_Item_Requirement

F_DefenseSystem_TrapState_Item_Requirement links a desired trap state to inventory items required to move into that state. This is how the trap base can ask the inventory system whether the interacting controller has the correct resources before allowing a state change.

Requirement struct used for trap-state resource requirements.

AC_TRAPMANAGER

AC_TrapManager is the main trap runtime component. It is attached to trap actors and acts as the public API for state changes, activation, damage, trapped-actor tracking, resource requirements, and trap effects. Child trap Blueprints should call into this component instead of duplicating manager logic.

The manager is designed to be reusable across many different trap types. A pressure plate, lever, trip wire, or direct overlap can all request the same manager function, and the trap child can decide how it should visually react after the state changes.

AC_TrapManager function list from the Blueprint editor.

Details panel / important variables

Configuration variables exposed on AC_TrapManager.

State update and replication flow

Trap state changes are routed through Try Update Trap State and Server_Try Update Trap State. The public event can be requested from gameplay code, but the authoritative update is performed on the server. On BeginPlay, the manager waits until the next tick, applies the current trap state, and then optionally attempts automatic reset/arming behaviour.

The Try Set Trap State function checks initialization, validates whether the current state can transition into the desired state, updates Current Trap State, and then calls the Trap State Changed event. This keeps trap children simple: they can bind to state changes and react to the new state without owning the whole transition system.

Trigger validation

Validate Trigger Source checks whether the overlapping pawn is player-controlled or AI-controlled and then compares that result against Should Player Trigger Trap and Should AI Trigger Trap. This gives designers a simple way to make a trap affect only players, only AI, or both.

Damage and trap effects

AC_TrapManager provides both area damage and single-target damage routes. Area damage collects overlapping actors from a supplied collision/primitive component. Single-target damage is used when a specific hit actor and hit result are already known from an overlap or collision event. Both routes resolve the target attribute manager, apply direct damage, and then apply configured trap effects.

Resource requirements and inventory integration

The manager can check and consume resources before allowing a state transition. The BP_Trap_Base interaction flow asks the manager for the resources required for the desired state, checks the controller inventory through the inventory manager, and then removes those resources when the transition succeeds.

Movement locking and release tracking

Some traps need to temporarily stop a character moving. Toggle Movement Enabled loops through supplied actors, casts them to characters, resolves AC_CH_Extended_Movement, and calls Disable Movement On Client. Add Trapped Actors can also store trapped actors and later allow them to release or clear them from arrays using timer-based cleanup.

BP_TRAP_BASE

BP_Trap_Base is the shared parent for normal trap actors. It is also a child of BP_Buildable_Base, which means the trap system plugs into Hyper buildable behaviour while keeping the buildable implementation separate. This document only covers the trap-specific behaviour and the points where the trap actor calls into the buildable/base flow.

BP_Trap_Base component and function layout.

Components

Interaction behaviour

BP_Trap_Base overrides interaction functions from its parent chain. It calls parent interaction first, then uses AC_TrapManager to decide whether the player can interact, what text should display, and whether the interaction should release a trapped actor or progress the trap state.

Connection behaviour

When a connection is made, BP_Trap_Base can identify whether the connected actor is a BP_External_Trap_Trigger. If it is, the trap passes its AC_TrapManager reference to the trigger. This is the key link that lets a lever, pressure plate, or trip wire activate a separate trap.

BP_Trap_Base interaction flow: release actors, check resources, consume resources, and progress state.

Trigger Actors

External trigger actors are separate actors that can activate or progress a linked trap. They do not own the trap state themselves. Instead, they store a reference to the linked AC_TrapManager and call manager functions when the trigger is used.

BP_External_Trap_Trigger

BP_External_Trap_Trigger is the generic trigger base. It uses AC_Connectable and cable attach points so that the trigger can be linked visually and functionally to a trap. On connection, it resolves the trap base, finds the trap manager, stores it as Linked Trap Manager, and creates a cable between the two connection points.

Generic external trigger connection logic and cable setup.

BP_External_Trap_Trigger_Lever_Switch

The lever switch is an interactable external trigger. When the player interacts with it, it calls Try Progress Trap To Next State on the linked trap manager. It also binds to the trap manager state changed event and lerps the lever rotation so the lever visually reflects trap state changes.

Lever trigger shown in the demo level.

BP_External_Trap_Trigger_PressurePlate

The pressure plate activates when an overlapping character has enough inventory weight. It casts the overlapping actor to a character, reads inventory information through the inventory component, compares the total weight against Weight Required to Trigger, and then calls Try Activate Trap From Trigger when the check passes.

Pressure plate trigger shown in the demo level.

BP_External_Trap_Trigger_TripWire

The trip wire activates when an actor crosses the wire after building is complete. The visual cable ends are detached when overlapped, then the trigger calls Try Activate Trap From Trigger on the linked trap manager.

Trip wire trigger shown in the demo level.

Trap Base Variants

BP_Trap_Activatable_Base

BP_Trap_Activatable_Base is used for traps that are activated and deactivated through trap states. It keeps interaction availability tied to build completion and uses state-specific interaction text such as Activate Trap or Deactivate Trap.

BP_Trap_Armable_Base

BP_Trap_Armable_Base is used for traps that can be armed and potentially released. It builds on BP_Trap_Base interaction behaviour and changes the displayed text depending on whether the interacting pawn is allowed to release itself.

Individual Traps

The following traps are implemented as individual child trap Blueprints, except for BP_Trap_Boulder which is documented separately. Each child uses the shared manager for state, damage, effects, and activation, then implements its own visuals and physical response.

BP_Trap_Fly_Swatter

BP_Trap_Fly_Swatter is a primitive jaw trap made from two spiked halves. When triggered, it moves its trap parts toward the target rotation using a timeline, applies area damage, and then updates the trap back to Unarmed. When arming, it plays a reset timeline and then updates to Armed.

BP_Trap_Fly_Swatter_Double

BP_Trap_Fly_Swatter_Double extends the jaw trap idea by using two moving halves and storing the current roll rotation before animation. It can damage an area, move back to Unarmed, and track trapped actors for release timing.

BP_Trap_GroundSpikes

BP_Trap_GroundSpikes uses an animation Blueprint to extend and retract spikes. The trap manager state is converted into a replicated Trap Armed boolean, and animation events feed back into the trap manager when the spikes are armed, triggered, or ready to deal damage.

BP_Trap_Hanging_Rope

BP_Trap_Hanging_Rope is a suspended snare trap. It catches the overlapping actor, moves the trap upward, attaches the rope to the actor, ragdolls the actor, and constrains the actor to the trap. When released, it disconnects the rope and destroys the spawned physics constraint.

BP_Trap_Log_Cleaver

BP_Trap_Log_Cleaver is a heavy swinging log trap. It stores the default center-support rotation, rotates the center support, applies damage from spiked log overlaps, and uses a damaged actor cooldown map so the same target is not damaged too many times per second.

BP_Trap_Spinner

BP_Trap_Spinner is a rotating wooden beam with spiked balls. It uses constraints for the spiked balls, rotates the spinner base by torque, ramps torque up and down with timelines, and applies single target damage from multiple overlap components.

BP_Trap_Static_Spikes

BP_Trap_Static_Spikes is the simplest trap shown. It applies area damage whenever the Damage Overlap component begins overlap. This is useful for always-dangerous spike fields or traps that do not need a complex state machine.

BP_Trap_TrapDoor

BP_Trap_TrapDoor uses left and right door meshes, door pivots, and physics constraints to open a floor hatch. It can move into Armed, simulate or stop physics on the door parts, and open the gates/doors when triggered.

BP_Trap_Wall_Spikes

BP_Trap_Wall_Spikes uses a long spike animation Blueprint. The child sets an Extend Trap replicated value, pushes that value into ABP_Spike_Trap_Long, and listens for animation events to apply damage and return to Armed after retracting.

Boulder Trap

BP_Trap_Boulder is the major exception to the normal trap hierarchy. It is documented separately because the boulder is mostly physics-driven and can be pushed by the player when it is not directly impacting the player. It has its own collision, force, sound, cooldown, and velocity-based damage flow.

Rolling boulder sign from the demo level.

The boulder should be treated as a special hazard rather than a normal arm/disarm trap. Designers can place it into the world as a rolling physics object and tune its push force, damage velocity thresholds, sound arrays, and cooldown settings.

Functions to Use

The following functions are the main public entry points designers and developers are most likely to use when integrating traps into gameplay logic.

Events and Dispatchers

The system relies on events rather than hardwired child logic. The trap manager broadcasts state changes and the child Blueprints respond with the appropriate visuals, timelines, animation events, or physics changes.

Hooking Traps Into Other Systems

The trap system integrates with several other Hyper systems while keeping ownership boundaries clear. The trap should request services from those systems rather than copying their logic.

How to Place a Trap in the World

Use this workflow when adding an existing trap to a map or test level.

1. Drag the desired trap Blueprint into the level. For normal traps, use one of the BP_Trap_Base child actors. For the boulder, place BP_Trap_Boulder separately.
2. Position and rotate the trap so its damage/trigger zones line up with the intended gameplay path.
3. If the trap uses the buildable workflow, make sure it can reach the finished/buildable state before testing interaction. Several trap functions check Is Building Finished before allowing use.
4. Select the trap and inspect AC_TrapManager. Confirm Current Trap State, Allowed Trap State Transitions, Trigger settings, Trap Damage, Trap Damage Type, and automatic arm/reset settings.
5. Decide whether the trap should be triggered by the player, AI, or both by setting Should Player Trigger Trap and Should AI Trigger Trap.
6. Configure Trap Effects To Apply On Damage or Trap Effects To Apply On Enter Trigger if the trap should apply extra effects beyond damage.
7. Press Play and test the trap with the intended trigger source.

How to Connect a Trap to an External Trigger

Use this workflow for lever switches, pressure plates, and trip wires.

1. Place the trap actor in the level.
2. Place the desired BP_External_Trap_Trigger child, such as BP_External_Trap_Trigger_Lever_Switch, BP_External_Trap_Trigger_PressurePlate, or BP_External_Trap_Trigger_TripWire.
3. Use the connectable workflow to connect the trigger actor to the trap actor. The trigger should receive the trap manager reference from the trap when the connection is made.
4. Check that the visual cable is created between the trigger Cable Attach Point and the trap Cable Attach Point.
5. In Play mode, interact with or overlap the trigger. The trigger should call Try Progress Trap To Next State or Try Activate Trap From Trigger on the linked manager.
6. If nothing happens, verify Linked Trap Manager is valid on the trigger and that the trap current state can transition to the desired state.

How to Change Trap Damage

Trap damage is configured on AC_TrapManager rather than inside every child trap.

1. Select the trap actor in the level or Blueprint defaults.
2. Open the AC_TrapManager details.
3. Set Trap Damage to the desired amount.
4. Set Trap Damage Type to the damage type that should be passed into the attribute/damage system.
5. If the child trap uses velocity-based damage, such as BP_Trap_Boulder, tune the boulder-specific min/max damage and velocity threshold values instead of only changing the generic trap manager damage.
6. Test the trap against a valid actor with an attribute manager. If no damage is applied, confirm the actor can be resolved by Get Attribute Manager By Actor and that the collision component is overlapping the actor correctly.

How to Make a Trap Require Items to Arm or Activate

The resource requirement workflow is driven by F_DefenseSystem_TrapState_Item_Requirement and the inventory manager.

1. Select the trap and open AC_TrapManager.
2. Find Required Resource For Trap State.
3. Add a new array entry.
4. Set Trap State to the desired target state, such as Armed.
5. Add the required inventory slot item entries to Inventory Items.
6. Make sure Allowed Trap State Transitions allows the current state to progress into the state that has the requirement.
7. When the player interacts, BP_Trap_Base will check Has Required Resources For Trap State.
8. If the check passes, Remove Required Resources For Trap State consumes the items and then the manager updates the trap state.
9. If the interaction text is not showing the item name correctly, verify the inventory item row name and item data lookup used by Get Interact Text.

How to Add a New Normal Trap

A new normal trap should usually be created as a child of an existing trap base, not from Actor directly.

1. Decide whether the trap should be a simple trap, activatable trap, or armable/releasable trap.
2. Create a child Blueprint of BP_Trap_Base, BP_Trap_Activatable_Base, or BP_Trap_Armable_Base.
3. Add the trap-specific meshes, skeletal meshes, collision boxes, trigger boxes, pivots, cables, physics constraints, or scene components needed by the trap.
4. Use AC_TrapManager for Current Trap State, damage, trap effects, resources, and trigger validation. Do not create a separate state variable unless the child needs a replicated animation parameter.
5. On BeginPlay, call parent BeginPlay and then bind to Trap State Changed if the child needs to react to state changes.
6. Add a Switch on E_DefenseSystem_Trap_State in the child and route relevant states to custom events such as Trap Armed, Trap Triggered, Trap Unarmed, or Trap Releasing.
7. For damage, call Apply Area Damage or Apply Single Target Damage on AC_TrapManager rather than applying damage manually.
8. If the trap catches or locks actors, call Add Trapped Actors and use Actors Allowed To Release for release logic.
9. Configure Allowed Trap State Transitions in AC_TrapManager so generic interactions and external triggers know what the next state should be.
10. Test the trap in isolation first, then connect it to a lever, pressure plate, or trip wire.

How to Add a New External Trigger

A new external trigger should call the trap manager rather than owning trap behaviour directly.

1. Create a child Blueprint of BP_External_Trap_Trigger.
2. Keep AC_Connectable and the Cable Attach Point setup so the trigger can be connected to a trap.
3. Add the trigger-specific input: interaction, overlap, hit event, timer, proximity check, item check, or weight check.
4. When the trigger condition passes, call either Try Activate Trap From Trigger or Try Progress Trap To Next State on Linked Trap Manager.
5. Pass the actor that caused the trigger so Validate Trigger Source can check player/AI rules.
6. Add visual feedback if needed. For example, a lever lerps rotation, a trip wire detaches its cable, and a pressure plate can depress its mesh.
7. In Can Interact or activation logic, verify Linked Trap Manager is valid before allowing use.

How to Add a Trap Effect

Trap effects are configured through AC_TrapManager maps and applied after damage or trigger events.

1. Create or choose a BP_TrapEffectBase child that contains the effect behaviour.
2. Select the trap actor and open AC_TrapManager.
3. Add the effect to Trap Effects To Apply On Damage if it should trigger when damage is dealt.
4. Add the effect to Trap Effects To Apply On Enter Trigger if it should trigger when an actor enters a trigger zone.
5. Fill in the effect data map value expected by that effect class.
6. Test the trap against a valid actor. Apply Trap Effects constructs the effect object and calls Apply Effect with the affected actor, owning trap, hit component, and hit result.

How to Make a Trap Reset Automatically

Automatic reset is controlled through AC_TrapManager and the child trap state implementation.

1. Enable Should Automatically Arm on AC_TrapManager if the trap should reset without manual interaction.
2. Set Automatic Arm Delay to the time the manager should wait before trying to reset or arm again.
3. Ensure Allowed Trap State Transitions contains the path the trap should follow after Triggered or Released.
4. In the child trap, make sure the state event for Arming or Unarmed actually plays the reset animation/timeline and updates the manager to Armed when complete.
5. For animation-driven traps, bind the animation event that indicates the reset is finished and update the manager from there.
6. Test multiple activations to confirm damage, overlap, and recently trapped actor arrays are cleared correctly between activations.

Example Flows

Player steps on a pressure plate

The pressure plate overlap fires.

The actor is cast to Character and its inventory component is resolved.

Total inventory weight is compared against Weight Required To Trigger.

If valid, the pressure plate calls Try Activate Trap From Trigger on the linked trap manager.

The manager validates the trigger source and state transition.

The child trap receives Trap State Changed and performs its own triggered behaviour.

Player pulls a lever to arm or activate a trap

The player interacts with BP_External_Trap_Trigger_Lever_Switch.

The lever calls parent interaction and passes the controlled pawn to Try Progress Trap To Next State.

AC_TrapManager reads Allowed Trap State Transitions and updates the current state if valid.

The lever receives the state changed event and lerps its rotation.

The trap child receives the same state change and animates, arms, triggers, or releases depending on the new state.

Player arms a resource-gated trap

The player interacts with the trap actor.

BP_Trap_Base finds the next state from Allowed Trap State Transitions.

The manager checks Required Resource For Trap State for that desired state.

The inventory manager confirms whether all required items exist.

If valid, the required items are removed and the trap state is updated.

The child trap reacts to the state change and moves into Arming or Armed.

Actor is caught by the hanging rope

The rope trap overlap gate is open while the trap is Armed.

An overlapping character is stored as Actor That Triggered This.

The trap manager is set to Triggered and the actor is added to trapped actor tracking.

The trap interpolates upward, attaches cable to the actor, ragdolls the actor, and creates a physics constraint.

When released, the rope disconnects, the constraint is destroyed, and the manager moves to Released.

Boulder hits a player

The boulder collision detects a player contact.

The boulder calculates direction, velocity, and dot product to decide whether the player is pushing or being hit.

If the player is being hit, the boulder can ragdoll the actor and apply damage.

Damage scales based on current boulder velocity and the configured min/max damage values.

The actor is added to the damaged actor cooldown map so it is not damaged repeatedly every frame.

Troubleshooting

Summary

The Defense / Trap System provides a reusable Blueprint foundation for traps, triggers, state transitions, damage, trap effects, resource requirements, and buildable integration. BP_Trap_Base is the shared trap parent and is itself a child of BP_Buildable_Base, so normal traps inherit buildable-world behaviour while keeping trap-specific logic in AC_TrapManager and child trap Blueprints.

Most traps should be extended as children of the trap base chain. The child trap should focus on visuals, timelines, animations, physics, overlap zones, and special behaviour, while AC_TrapManager continues to own the state machine, damage routes, trap effects, resource checks, trigger validation, and release tracking. BP_Trap_Boulder is the main exception and should be treated as a separate physics-driven hazard.

For designers, the system is practical because traps can be placed, configured, connected to external triggers, tuned for player or AI activation, assigned resource requirements, and tested through shared manager settings. For developers, the system is extensible because new traps can be created by inheriting from the trap base, binding to trap state changes, and calling the existing manager functions rather than rebuilding the framework from scratch.