add blueprints

2026-05-19 13:22:27 +03:00
parent f71bc678b2
commit 411edea8ce
138 changed files with 23330 additions and 0 deletions
--- a/docs/blueprints/08-weapons/74_BPC_FirearmSystem.md
+++ b/docs/blueprints/08-weapons/74_BPC_FirearmSystem.md
@@ -0,0 +1,105 @@
+# BPC_FirearmSystem — Firearm Component
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`ActorComponent`
+
+### Dependencies
+- [`BPC_AmmoComponent`](52_BPC_AmmoComponent.md) — Ammo management
+- [`BPC_DamageReceptionSystem`](BPC_DamageReceptionSystem.md) — Damage application
+- [`BPC_CombatFeedbackComponent`](54_BPC_CombatFeedbackComponent.md) — Visual/audio feedback
+- [`BPC_CameraStateLayer`](../02-player/14_BPC_CameraStateLayer.md) — Recoil & ADS
+- [`I_Damageable`](../01-core/03_I_InterfaceLibrary.md) — Interface for hit targets
+- [`DA_WeaponData`](../14-data-assets/) — Weapon definition
+
+### Purpose
+Ranged weapon specialization. Handles line trace / projectile fire, weapon spread, bullet drop simulation, and multi-hit logic. Used by firearms (pistols, rifles, shotguns) and charge weapons.
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `FireType` | EFireType | Hitscan, Projectile, Hybrid |
+| `ShootEffectType` | EShotEffect | Single, Spread, Charge |
+| `Range` | Float | Max effective range (cm) |
+| `SpreadAngle` | Float | Base spread in degrees |
+| `SpreadRecoveryRate` | Float | Per-second recovery from spread |
+| `CurrentSpread` | Float | Running spread (fired recently) |
+| `MaxSpread` | Float | Spread cap |
+| `BulletsPerShot` | Int | e.g. shotgun = 8 |
+| `ProjectileClass` | Actor (Blueprint) | Only for Projectile / Hybrid fire types |
+| `FireSocket` | FName | Muzzle attachment point |
+| `MuzzleLocation` | USceneComponent | Muzzle transform reference |
+| `HitScanImpacts` | Array<FHitResult> | Notify component for decals |
+
+### Enums
+
+| Enum | Values | Description |
+|------|--------|-------------|
+| `EFireType` | Hitscan, Projectile, Hybrid | Ray → Instant or Bullet actor |
+| `EShotEffect` | SingleShot, SpreadShot, ChargeShot | Fire pattern |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `PerformHitscanFire` | EWeaponFireMode | Array<FHitResult> | Line trace from camera to crosshair; no bullet |
+| `SpawnProjectile` | Direction: FVector | Actor | Spawn projectile actor with initial velocity |
+| `CalculateSpread` | — | FVector | Apply random offset within CurrentSpread cone |
+| `OnFire_Implementation` | — | — | Override of WeaponBase::OnFire; runs hit scan or spawns projectile |
+| `ApplyRecoil` | — | — | Add camera rotation via CameraStateLayer |
+| `ConsumeAmmo` | — | — | Delegate to BPC_AmmoComponent |
+| `GetEffectiveRange` | — | Float | Return weapon range from data asset |
+
+### Blueprint Flow
+
+```
+[OnFire]
+  └─► If FireType == Hitscan
+         For i = 1 .. BulletsPerShot:
+            AimDir = OwnerCamera.ForwardVector + CalculateSpread
+            PerformHitscanFire returns HitResults
+            For each hit:
+                if actor implements I_Damageable:
+                    BPC_DamageReceptionSystem.ApplyDamage(WeaponData.Damage, Hit)
+                BPC_CombatFeedbackComponent.SpawnImpactFX(Hit)
+  └─► If FireType == Projectile
+         For i = 1 .. BulletsPerShot:
+            AimDir = OwnerCamera.ForwardVector + CalculateSpread
+            SpawnProjectile(AimDir * WeaponData.ProjectileSpeed)
+  └─► If FireType == Hybrid
+         Perform hitscan + spawn projectile for missed overlap area
+  └─► ApplyRecoil
+  └─► ConsumeAmmo
+  └─► BPC_CombatFeedbackComponent.PlayMuzzleFlash
+  └─► BPC_CombatFeedbackComponent.PlayFireSound
+
+[CalculateSpread]
+  └─► CurrentSpread = FMath::Min(CurrentSpread + WeaponData.SpreadPerShot, MaxSpread)
+  └─► Return random vector in cone of CurrentSpread degrees
+
+[OnFireStopped — super]
+  └─► Begin spread recovery: CurrentSpread → 0 over SpreadRecoveryRate seconds
+  └─► BPC_CombatFeedbackComponent.StopFireSound
+```
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`BPC_AmmoComponent`](52_BPC_AmmoComponent.md) | Get Component | Ammo check / consume |
+| [`BPC_DamageReceptionSystem`](BPC_DamageReceptionSystem.md) | Get Component | Apply damage to hit targets |
+| [`BPC_CombatFeedbackComponent`](54_BPC_CombatFeedbackComponent.md) | Get Component | Muzzle flash, tracers, impact FX |
+| [`BPC_CameraStateLayer`](../02-player/14_BPC_CameraStateLayer.md) | Get from Owner | Recoil animation |
+| Owner WeaponAnimBP | Animation Instance | Fire / Reload animations |
+| HUD Widget | Dispatcher | Ammo count update |
+
+### Reuse Notes
+- Hit scan fire uses camera forward, not muzzle forward, for accuracy. Muzzle is for FX only.
+- Spread is cumulative while firing, resets on recovery timer.
+- Projectile type requires a child BP implementing `AP_BaseProjectile` with velocity and lifetime.
+- Renamed from `BP_RangedWeapon` to `BPC_FirearmSystem` per Master naming convention.
+- Cross-references updated: `BPC_DamageHandlerComponent` → `BPC_DamageReceptionSystem`, `BPC_PlayerCameraManager` → `BPC_CameraStateLayer`, `DA_WeaponData` → `14-data-assets/`.