add blueprints
This commit is contained in:
Lefteris Notas
339
docs/blueprints/03-interaction/19_BP_DoorActor.md
Normal file
339
docs/blueprints/03-interaction/19_BP_DoorActor.md
Normal file
@@ -0,0 +1,339 @@
|
||||
# `BP_DoorActor` — Door Actor System
|
||||
|
||||
**Parent Class:** `Actor`
|
||||
**Category:** Interaction
|
||||
**Implements:** `I_Interactable`
|
||||
**Target UE Version:** 5.5–5.7
|
||||
**Build Phase:** 2 — Interaction
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
`BP_DoorActor` powers all door-like actors in the game world — standard hinged doors, sliding doors, double doors, and barricaded passages. It manages a discrete 6-state machine (`Closed → Opening → Open → Closing → Locked → Barricaded`), supports key/lock mechanics, item-required unlocking, one-way passage, partial-open positions, and networked replication.
|
||||
|
||||
The door state is exposed via Event Dispatchers so other systems (AudioManager, CameraStateLayer, AI, Narrative) can react.
|
||||
|
||||
---
|
||||
|
||||
## 2. Mermaid — Door State Machine & Interaction Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[Idle Closed] --> B{Interact?}
|
||||
B -->|Player presses Interact| C[TryOpen]
|
||||
C --> D{Is Locked?}
|
||||
D -->|Yes: Has Required Item?| E{Remove Item?}
|
||||
D -->|Yes: No Item| F[Play Locked Feedback]
|
||||
E -->|Yes| G[Unlock & Open]
|
||||
E -->|No| F
|
||||
D -->|No| H[Play Open Anim]
|
||||
H --> I[State = Opening]
|
||||
I --> J[State = Open]
|
||||
J --> K{Close Conditions Met?}
|
||||
K -->|Auto-Close Timer| L[Play Close Anim]
|
||||
K -->|Player Interact| L
|
||||
K -->|Manual Call| L
|
||||
L --> M[State = Closing]
|
||||
M --> A
|
||||
|
||||
N[Locked Entry] --> O[State = Locked]
|
||||
P[Barricaded Entry] --> Q[State = Barricaded]
|
||||
Q --> R{Barricade Broken?}
|
||||
R -->|Yes| A
|
||||
R -->|No| Q
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Enums
|
||||
|
||||
### `E_DoorState`
|
||||
Defined in `E_DoorState` enum asset.
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Closed` | Door fully closed, no movement. Can be interacted with. |
|
||||
| `Opening` | Door playing open animation. Input blocked. |
|
||||
| `Open` | Door fully open. Can be interacted with to close, or auto-closes. |
|
||||
| `Closing` | Door playing close animation. Input blocked. |
|
||||
| `Locked` | Door locked. Cannot be opened unless unlocked via key/item or external trigger. |
|
||||
| `Barricaded` | Door physically blocked. Must be destroyed/breached. |
|
||||
|
||||
### `E_DoorType`
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Hinged` | Standard door that swings open/closed. |
|
||||
| `Sliding` | Door slides horizontally into a wall pocket. |
|
||||
| `Double` | Two doors that open outward/inward. |
|
||||
| `RollUp` | Garage-style door that rolls upward. |
|
||||
| `TrapDoor` | Floor/ceiling door that opens vertically. |
|
||||
|
||||
### `E_LockState`
|
||||
Optional sub-state for locked doors.
|
||||
|
||||
| Value | Description |
|
||||
|-------|-------------|
|
||||
| `Unlocked` | Door can be opened normally. |
|
||||
| `KeyRequired` | Requires a specific key item in inventory. |
|
||||
| `ItemRequired` | Requires a specific non-key item (crowbar, code). |
|
||||
| `PuzzleLinked` | Lock is controlled by an external puzzle actor. |
|
||||
| `Breachable` | Lock can be broken with force (weapon/explosive). |
|
||||
|
||||
---
|
||||
|
||||
## 4. Structs
|
||||
|
||||
### `S_DoorConfig`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `DoorType` | `E_DoorType` | Visual/mechanical type of door. |
|
||||
| `DefaultState` | `E_DoorState` | State the door starts in at BeginPlay. |
|
||||
| `LockState` | `E_LockState` | Lock type if DefaultState is Locked. |
|
||||
| `RequiredItemTag` | `FGameplayTag` | Tag of item required to unlock (if KeyRequired/ItemRequired). |
|
||||
| `RemoveItemOnUse` | `bool` | If true, the key/item is consumed on unlock. |
|
||||
| `AutoCloseDelay` | `float` | Seconds before door auto-closes. 0 = never auto-close. |
|
||||
| `OpenAngle` | `float` | Degrees the door opens (default 90). |
|
||||
| `OpenSpeed` | `float` | Animation play rate / interpolation speed. |
|
||||
| `CloseSpeed` | `float` | Animation play rate for closing. |
|
||||
| `IsOneWay` | `bool` | If true, door only opens from one side. |
|
||||
| `CanBeBarricaded` | `bool` | If true, door can transition to Barricaded state. |
|
||||
| `BarricadeHealth` | `float` | Damage required to break barricade. |
|
||||
| `bReplicates` | `bool` | Whether door state is replicated. |
|
||||
|
||||
### `S_DoorAudioConfig`
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `OpenSound` | `USoundBase*` | Sound played when door begins opening. |
|
||||
| `CloseSound` | `USoundBase*` | Sound played when door begins closing. |
|
||||
| `LockedSound` | `USoundBase*` | Sound played when player tries to open a locked door. |
|
||||
| `UnlockSound` | `USoundBase*` | Sound played when door is unlocked. |
|
||||
| `BarricadeBreakSound` | `USoundBase*` | Sound played when barricade is destroyed. |
|
||||
| `SqueakInterval` | `float` | Seconds between squeak sounds during movement (0 = no squeak). |
|
||||
|
||||
---
|
||||
|
||||
## 5. Variables
|
||||
|
||||
### Configuration (Instance Editable, Expose On Spawn)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `DoorConfig` | `S_DoorConfig` | Primary configuration struct. |
|
||||
| `AudioConfig` | `S_DoorAudioConfig` | Audio configuration struct. |
|
||||
| `LinkedActors` | `TArray<AActor*>` | Actors to notify on door open/close (lights, alarms, traps). |
|
||||
| `RequiredItemTag` | `FGameplayTag` | Shortcut to DoorConfig.RequiredItemTag (for BP pin). |
|
||||
|
||||
### State (Blueprint Read Only, Replicated)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `CurrentState` | `E_DoorState` | Current door state. Replicated using `OnRep_DoorState`. |
|
||||
| `CurrentLockState` | `E_LockState` | Current lock state. Replicated. |
|
||||
| `CurrentBarricadeHealth` | `float` | Remaining barricade health. Replicated. |
|
||||
| `bIsOpenFromFront` | `bool` | Tracks which side the door was opened from (for one-way logic). |
|
||||
|
||||
### Internal (Blueprint Read Only, Not Replicated)
|
||||
|
||||
| Variable | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `OwningDoorActor` | `AActor*` | Cached reference to owning actor (BP_DoorBase). |
|
||||
| `DoorMeshComponent` | `UStaticMeshComponent*` | Cached reference to the door's static mesh (if hinged/sliding). |
|
||||
| `DoorAudioComponent` | `UAudioComponent*` | Cached audio component for spatialized sounds. |
|
||||
| `AutoCloseTimerHandle` | `FTimerHandle` | Handle for auto-close timer. |
|
||||
| `AnimationTimeline` | `float` | Internal 0-1 progress of open/close animation. |
|
||||
|
||||
---
|
||||
|
||||
## 6. Functions & Events
|
||||
|
||||
### Public Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `Interact_Implementation` | Implements `I_Interactable.ExecuteInteraction`. Routes to `TryOpen` if Closed/Locked/Barricaded, or `TryClose` if Open. |
|
||||
| `TryOpen` | Checks state: if Locked, attempts unlock (check inventory or puzzle); if Barricaded, plays blocked feedback; if Closed, begins open animation. Returns `E_DoorOperationResult`. |
|
||||
| `TryClose` | If Open, begins close animation. If Opening/Closing, ignores. Returns bool. |
|
||||
| `LockDoor` | Transitions to Locked state. Optionally sets lock type and required item. |
|
||||
| `UnlockDoor` | Removes lock, plays unlock effects. If `bAutoOpenOnUnlock`, begins opening. |
|
||||
| `BarricadeDoor` | Transitions to Barricaded state, sets health. |
|
||||
| `DamageBarricade` | Reduces barricade health by damage amount. If health reaches 0, removes barricade and transitions to Closed. |
|
||||
| `ForceSetState` | Bypasses animation; immediately sets door to any valid state. Used for save/load. |
|
||||
| `IsDoorUsable` | Returns true if door can be interacted with (not Opening/Closing/Barricaded with health). |
|
||||
| `GetDoorState` | Returns current `E_DoorState`. |
|
||||
| `GetDoorType` | Returns `E_DoorType` from config. |
|
||||
|
||||
### Protected Functions
|
||||
|
||||
| Function | Description |
|
||||
|----------|-------------|
|
||||
| `BeginPlay` | Caches references, applies default state, initialises audio component. |
|
||||
| `PlayOpenAnimation` | Starts timeline/interp for door rotation/slide. Plays open sound. Calls `OnOpenComplete` when finished. |
|
||||
| `PlayCloseAnimation` | Starts timeline/interp for reverse. Plays close sound. Calls `OnCloseComplete` when finished. |
|
||||
| `OnOpenComplete` | Sets state to Open, clears auto-close timer if `AutoCloseDelay > 0`, notifies `LinkedActors`. |
|
||||
| `OnCloseComplete` | Sets state to Closed. |
|
||||
| `TryUnlockWithItem` | Checks player inventory for `RequiredItemTag`. If found and `RemoveItemOnUse`, consumes the item. Returns bool. |
|
||||
| `CheckPuzzleUnlockCondition` | Returns true if linked puzzle is solved. |
|
||||
| `PlayLockedFeedback` | Plays locked sound + optional UI prompt notifying player of required item. |
|
||||
| `OnRep_DoorState` | RepNotify: when `CurrentState` changes, plays appropriate animation on remote clients. |
|
||||
|
||||
### Event Dispatchers
|
||||
|
||||
| Dispatcher | Payload | Description |
|
||||
|------------|---------|-------------|
|
||||
| `OnDoorStateChanged` | `E_DoorState NewState`, `AActor* Instigator` | Fired on any state transition. |
|
||||
| `OnDoorOpened` | `AActor* Instigator`, `bool bFromFront` | Fired when door reaches Open state. |
|
||||
| `OnDoorClosed` | `AActor* Instigator` | Fired when door reaches Closed state. |
|
||||
| `OnDoorLocked` | `AActor* Instigator` | Fired when door transitions to Locked. |
|
||||
| `OnDoorUnlocked` | `AActor* Instigator` | Fired when door is unlocked. |
|
||||
| `OnBarricadeBroken` | `AActor* Instigator` | Fired when barricade health reaches 0. |
|
||||
| `OnInteractionFailed` | `E_DoorState CurrentState`, `FText FailReason` | Fired when player cannot interact. |
|
||||
|
||||
---
|
||||
|
||||
## 7. Blueprint Graph Flow
|
||||
|
||||
### Event Graph Flow
|
||||
|
||||
```
|
||||
Event BeginPlay
|
||||
→ GetOwner → Cast to BP_DoorBase → Cache OwningDoorActor
|
||||
→ FindComponentByClass UStaticMeshComponent → Cache DoorMeshComponent
|
||||
→ Create Audio Component → Cache
|
||||
→ Apply Default State from DoorConfig.DefaultState
|
||||
→ If Locked → Set CurrentLockState → LockDoor
|
||||
|
||||
On Interact_Implementation
|
||||
→ Branch: CurrentState
|
||||
— Closed → Call TryOpen
|
||||
— Locked → Call TryUnlockWithItem → Branch Result
|
||||
— Success → Play Unlock Effects → Call TryOpen
|
||||
— Fail → Play LockedFeedback → Broadcast OnInteractionFailed
|
||||
— Barricaded → Play Blocked Feedback → Broadcast OnInteractionFailed
|
||||
— Open → Call TryClose
|
||||
— Opening/Closing → Ignore (return)
|
||||
|
||||
TryOpen
|
||||
→ IsDoorUsable? → If not, return false
|
||||
→ Set CurrentState = Opening
|
||||
→ Broadcast OnDoorStateChanged
|
||||
→ Set bIsOpenFromFront = (player side check)
|
||||
→ PlayOpenAnimation
|
||||
|
||||
TryClose
|
||||
→ IsDoorUsable? → If not, return false
|
||||
→ Set CurrentState = Closing
|
||||
→ Broadcast OnDoorStateChanged
|
||||
→ Clear AutoCloseTimerHandle
|
||||
→ PlayCloseAnimation
|
||||
|
||||
PlayOpenAnimation
|
||||
→ Timeline: 0→1 over 1/OpenSpeed seconds
|
||||
→ Interp: DoorMeshComponent RelativeRotation.Yaw from 0 → OpenAngle (or DoorConfig sign for direction)
|
||||
→ PlaySound: AudioConfig.OpenSound
|
||||
→ On Finished → OnOpenComplete
|
||||
|
||||
PlayCloseAnimation
|
||||
→ Timeline: 1→0 over 1/CloseSpeed seconds
|
||||
→ Interp: DoorMeshComponent RelativeRotation.Yaw from current → 0
|
||||
→ PlaySound: AudioConfig.CloseSound
|
||||
→ On Finished → OnCloseComplete
|
||||
|
||||
OnOpenComplete
|
||||
→ Set CurrentState = Open
|
||||
→ Broadcast OnDoorOpened
|
||||
→ If AutoCloseDelay > 0 → Set Timer by Event (AutoCloseDelay, Call TryClose)
|
||||
→ Notify LinkedActors (Open event)
|
||||
|
||||
OnCloseComplete
|
||||
→ Set CurrentState = Closed
|
||||
→ Broadcast OnDoorClosed
|
||||
→ Notify LinkedActors (Close event)
|
||||
|
||||
LockDoor
|
||||
→ Set CurrentState = Locked
|
||||
→ Set CurrentLockState = Input LockState
|
||||
→ Broadcast OnDoorLocked
|
||||
|
||||
UnlockDoor
|
||||
→ Set CurrentLockState = Unlocked
|
||||
→ If bAutoOpenOnUnlock → Call TryOpen
|
||||
→ Broadcast OnDoorUnlocked
|
||||
|
||||
DamageBarricade
|
||||
→ CurrentBarricadeHealth -= Damage
|
||||
→ If CurrentBarricadeHealth <= 0
|
||||
→ Set CurrentState = Closed
|
||||
→ Broadcast OnBarricadeBroken
|
||||
→ Broadcast OnDoorStateChanged
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Replication
|
||||
|
||||
| Variable | Replication | Callback |
|
||||
|----------|-------------|----------|
|
||||
| `CurrentState` | `RepNotify` | `OnRep_DoorState` — plays matching animation on remote |
|
||||
| `CurrentLockState` | `Replicated` | — |
|
||||
| `CurrentBarricadeHealth` | `Replicated` | — |
|
||||
| `bIsOpenFromFront` | `Replicated` | — |
|
||||
|
||||
**Server authority:** All state transitions are executed on the server. Clients predict input via `Interact_Implementation`, but the server validates and broadcasts the authoritative state.
|
||||
|
||||
---
|
||||
|
||||
## 9. Dependencies & Communication
|
||||
|
||||
| System | Relationship |
|
||||
|--------|--------------|
|
||||
| `BPC_InteractionDetector` | Calls `Interact_Implementation` when player looks at door and presses Interact. |
|
||||
| `BPC_InventorySystem` | Queried via `TryUnlockWithItem` for item possession and consumption. |
|
||||
| `BPC_HealthSystem` | Listens to `OnBarricadeBroken` for environmental damage credit. |
|
||||
| `BPC_CameraStateLayer` | May request FOV push when door opens into a large space. |
|
||||
| `AudioManager` | Consumes `AudioConfig` and may play ambient/occlusion changes on door state. |
|
||||
| `AI Perception` | AI listens to `OnDoorOpened`/`OnDoorClosed` to update pathfinding and awareness. |
|
||||
| `Save/Load System` | Calls `ForceSetState` and `LockDoor`/`UnlockDoor` during restore. |
|
||||
| `Narrative Subsystem` | May bind to `OnDoorUnlocked` to trigger dialogue when a story-key door is opened. |
|
||||
| `BP_PuzzleDeviceActor` | `PuzzleLinked` lock type — puzzle completion calls `UnlockDoor`. |
|
||||
| `BPC_DifficultyManager` | May adjust `AutoCloseDelay` and `BarricadeHealth` based on player performance metrics. |
|
||||
|
||||
---
|
||||
|
||||
## 10. Success Criteria
|
||||
|
||||
1. Player can open/close a hinged door with standard interaction.
|
||||
2. Locked door plays feedback sound and shows item-required prompt.
|
||||
3. Player with correct key/item unlocks door; item is consumed if configured.
|
||||
4. Door auto-closes after configurable delay; auto-close timer resets on re-open.
|
||||
5. Barricaded door blocks passage until its health reaches 0 via damage.
|
||||
6. `PuzzleLinked` door unlocks when linked `BP_PuzzleDeviceActor` reports completion.
|
||||
7. One-way doors only open from the configured side.
|
||||
8. Double doors open/close in sync as a paired animation.
|
||||
9. Multiplayer: server-authoritative state syncs to all clients via `OnRep_DoorState`.
|
||||
10. Save/load correctly restores door state, lock state, and barricade health.
|
||||
|
||||
---
|
||||
|
||||
## 11. Data Flow Summary
|
||||
|
||||
```
|
||||
Player Presses Interact
|
||||
→ BPC_InteractionDetector.ScanForInteractables
|
||||
→ Closest valid target = BP_DoorActor
|
||||
→ Call I_Interactable.ExecuteInteraction
|
||||
→ BP_DoorActor.Interact_Implementation
|
||||
→ State check / lock check / inventory check
|
||||
→ Play animation / sound
|
||||
→ Broadcast Event Dispatchers
|
||||
→ Downstream systems react (AI, Audio, Narrative, Save)
|
||||
```
|
||||
|
||||
## 12. Reuse Notes
|
||||
|
||||
- This renamed file (formerly `BPC_InteractableDoorComponent`) is now an Actor-based system (`BP_DoorActor`) as per Master Section 3.5.
|
||||
- The door actor encapsulates all door logic directly rather than as an ActorComponent.
|
||||
- Cross-references updated: `BPC_InventoryComponent` → `BPC_InventorySystem`, `BPC_LeverPuzzleComponent` → `BP_PuzzleDeviceActor`.
|
||||
Reference in New Issue
Block a user