feat: Enhance interaction and inventory systems with new components and functionality

- Added BPC_UsableWorldObjectSystem for handling various interactable world objects with detailed manual implementation guide. - Introduced BPC_ActiveItemSystem to manage quick slots and active item usage, including cycling and selection logic. - Implemented BPC_DocumentArchiveSystem for managing collectible documents with read tracking and categorization. - Developed BPC_JournalSystem for narrative entries with auto-adding features based on gameplay events. - Created BPC_KeyItemSystem for key management with consumable and persistent key support. - Enhanced BPC_FirearmSystem for ranged weapon mechanics, including hitscan and projectile firing. - Updated BPC_MeleeSystem for melee combat with combo and blocking mechanics. - Established BPC_ReloadSystem for managing weapon reloading processes, including partial reloads and state management.
2026-05-19 18:37:42 +03:00
parent f272257cb3
commit eeb1bf82c9
11 changed files with 1361 additions and 11 deletions
--- a/docs/blueprints/08-weapons/76_BPC_MeleeSystem.md
+++ b/docs/blueprints/08-weapons/76_BPC_MeleeSystem.md
@@ -131,4 +131,115 @@ Melee weapon specialization. Handles swing detection, hitbox overlap checking du
 - Hit collision is a simple box or capsule that exists only during Active phase.
 - Block reduces incoming damage via DamageReception; parry reflects stagger.
 - Renamed from `BP_MeleeWeapon` to `BPC_MeleeSystem` per Master naming convention.
- Cross-references updated: `BPC_DamageHandlerComponent` → `BPC_DamageReceptionSystem`.
+- Cross-references updated: `BPC_DamageHandlerComponent` → `BPC_DamageReceptionSystem`.
+
+---
+
+## Manual Implementation Guide
+
+### Class Setup
+1. Create Blueprint Class: Parent = `ActorComponent`, Name = `BPC_MeleeSystem`
+2. Attach to `BP_WeaponBase` subclass: `BP_MeleeWeapon`
+3. Add `HitDetectionCollision` (Capsule or Box component) to weapon — disabled by default
+
+### Variable Init (BeginPlay)
+```
+Event BeginPlay
+  ├─ Set SwingPhase = Idle
+  ├─ Set ComboStep = 0
+  ├─ Set bCanCombo = false
+  ├─ Set bIsBlocking = false
+  ├─ Disable HitDetectionCollision (NoCollision)
+  ├─ Get Owner Weapon → Read DA_WeaponData for: ComboWindowDuration, ChargeDuration, ParryWindow, StaggerDuration
+  └─ Get Owner → Find BPC_DamageReceptionSystem → Cache
+```
+
+### Function Implementations
+
+#### `StartSwing(AttackType: EAttackType)` → `void`
+
+```
+[Function: StartSwing]
+  Step 1: Branch on SwingPhase != Idle AND SwingPhase != Recovery → Return (can't chain now)
+  Step 2: Set SwingPhase = WindUp
+  Step 3: Build montage section name:
+    If this is combo: "Combo_" + ComboStep
+    If AttackType == HeavyAttack: prefix "Heavy_"
+    If AttackType == ChargeAttack: "Charge_"
+  Step 4: Play Montage (SwingMontage, Section = built section name)
+  Step 5: Set bHitRegistered = false, Clear HitActors array
+  Step 6: Fire OnSwingStarted(AttackType, ComboStep)
+```
+
+**Nodes:** `Switch on EAttackType`, `Build String`, `Play Montage` (with Starting Section), `Clear Array`
+
+#### `OnSwingActive()` → `void` *(Called by Animation Notify: "Notify_Active")*
+
+```
+  Step 1: Set SwingPhase = Active
+  Step 2: HitDetectionCollision.SetCollisionEnabled(QueryOnly)
+  Step 3: Set bHitRegistered = false
+```
+
+#### `OnSwingHit(HitResult)` → `void` *(Called by HitDetectionCollision OnComponentBeginOverlap)*
+
+```
+  Step 1: Get Hit Actor from Overlap → Cast to Actor
+  Step 2: ForEach HitActors → if match found → Return (already hit this actor this swing)
+  Step 3: Add HitActor to HitActors
+  Step 4: If HitActor implements I_Damageable:
+    Get BPC_DamageReceptionSystem → Call ApplyMeleeDamage:
+      BaseDamage = WeaponData.Damage
+      Multiplier: Light=1.0, Heavy=1.8, Charge=2.5, Sprint=1.5
+      HitLocation = HitResult.ImpactPoint
+      Apply impulse in swing direction
+  Step 5: Get BPC_CombatFeedbackComponent → Call PlayHitFX(HitResult)
+  Step 6: Apply Stagger to HitActor
+```
+
+#### `OnSwingRecovery()` → `void` *(Animation Notify: "Notify_Recovery")*
+
+```
+  Step 1: Set SwingPhase = Recovery
+  Step 2: HitDetectionCollision.SetCollisionEnabled(NoCollision)
+  Step 3: Clear HitActors
+  Step 4: Set bCanCombo = true
+  Step 5: Start Timer (ComboWindowDuration) → On timer: if no combo received → OnSwingComplete()
+```
+
+#### `OnSwingComplete()` → `void`
+
+```
+  Step 1: Set SwingPhase = Idle
+  Step 2: Set bCanCombo = false
+  Step 3: Set ComboStep = 0
+  Step 4: Fire OnSwingFinished
+```
+
+#### `StartBlock()` → `void`
+
+```
+  Step 1: Set bIsBlocking = true
+  Step 2: Play block montage loop section
+  Step 3: Get Owner Character → Get CharacterMovement → Set MaxWalkSpeed *= 0.5
+  Step 4: Set ParryWindow timer: bParryActive = true for ParryWindow seconds
+    On timer end → bParryActive = false
+```
+
+#### `EndBlock()` → `void`
+
+```
+  Step 1: Set bIsBlocking = false
+  Step 2: Stop block montage
+  Step 3: Restore MaxWalkSpeed
+```
+
+### Build Checklist
+- [ ] Create BPC_MeleeSystem, add to BP_MeleeWeapon
+- [ ] Add HitDetectionCollision component (Capsule/Box, NoCollision by default)
+- [ ] Create SwingMontage with sections: Combo_1, Combo_2, Combo_3, Heavy_1, Charge_1
+- [ ] Place Animation Notifies: Notify_Active, Notify_Recovery, Notify_CanCombo, Notify_ParryWindow
+- [ ] Implement phase state machine: Idle→WindUp→Active→Recovery→(combo)→Idle
+- [ ] Bind HitDetectionCollision.OnComponentBeginOverlap → OnSwingHit
+- [ ] Implement combo system with bCanCombo window timer
+- [ ] Implement block/parry with damage reduction and stagger reflection