Description
# 🛠️ VR Weaponsmith Plugin
Construct highly modular, production-ready virtual reality firearms in Unreal Engine 5—entirely without writing code.
The VR Weaponsmith Plugin provides a custom visual 3D assembly editor suite and a modular C++ component framework for creating, customizing, and balancing firearms via Data Assets. Architected from the ground up for VR with native Unreal Engine StateTree support, zero-lag kinematic mechanics, procedural recoil damping, turnkey preset templates, and a high-performance zero-GC memory pooling world subsystem.
More images and a complete component overview are available on my website:
---
## 🎮 Demo & Documentation
*Playable VR Sandbox Demo:** [Download SteamVR / Quest Build] https://ctrlaltbo.com/projects/weaponsmith-plugin/
(Includes interactive target range, modular assembly stations, and live weapon tuning).
*Interactive Web Documentation:** [View Online Documentation] https://ctrlaltbo.com/projects/weaponsmith-plugin/
(Complete specification breakdown of all C++ classes, interfaces, gameplay tags, and extension guides).
*Video Walk-through:** [Watch Getting Started Guide] https://ctrlaltbo.com/projects/weaponsmith-plugin/
---
## 🌟 Key Technical Features
### 🛠️ 4 Dedicated 3D Slate Editor Toolkits
*Weaponsmith Asset Editor (`UVRWeaponData`):** Feature-rich visual editor with interactive 3D preview viewports, dynamic socket dropdown selectors, and real-time comparative stat dashboards.
*Attachment Asset Editor (`UVRAttachmentData`):** Standalone 3D preview editor with interactive socket axes, grab collision wireframe bounds, and a real-time Stat Impact visualizer (Recoil, Spread, Velocity deltas).
*Magazine Asset Editor (`UMagazineData`):** Visual customization panel to configure bullet offsets, visual ammo stacking, and capacity limits dynamically in live 3D space.
*Projectile & Ammo Asset Editor (`UProjectileData`):** Standalone editor with Live Round vs. Spent Casing toggling, grab collision wireframes, and shotgun spread cone visualizers (`SpreadAngle` & `PelletCount`).
*1-Click Blueprint Factories:** Generate pre-linked, ready-to-use child Blueprints with one click from any editor toolbar.
### 📦 Packaged Turnkey Weapon Templates & Zero-GC Blueprints
* Includes royalty-free, ready-to-use weapon preset packages inside the plugin content (`ArcadePistol/`, `AssaultRifle/`, `BreakOpenShotgun/`, `Handgun/`) bundling DataAssets, Ammo, Magazines, Attachments, and StateTrees.
* Includes GPU Niagara spent casing particle system (`NS_ModularSpentCasings`) for physical brass ejection without GC actor overhead.
### 🚀 Unified Blueprint Factory Spawning Architecture
4 standardized runtime factory nodes under `VR Weapon | Factory`: *`Spawn Weapon From Data`**, `Spawn Magazine From Data`, `Spawn Attachment From Data`, and `Spawn Round From Data` with optional base class defaults.
### 🌳 Modern C++ StateTree Architecture
* Ditch messy Blueprint state graphs. Firearm lifecycle events (Chambered, Empty, Jammed, Reloading) are orchestrated by Unreal Engine's native StateTree schema.
*Multi-Chamber Ejection:** Support for multi-barrel firearms with selective spent-casing ejection (`bOnlyEjectFired`) preserving live unfired shells in break-action shotguns.
*Sub-Frame Execution (`FSTTask_FastFire`):** High-RPM automatic firearms (1200+ RPM) compress firing, casing ejection, and round chambering into inline C++ execution to eliminate StateTree transition lag.
### 🎯 Zero-Lag Kinematic Mechanical Simulation
* Charging handles, slides, bolts, triggers, and safety selectors are mathematically simulated based on hand movement vectors.
* Eliminates VR controller jitter, physics solver latency, clipping, and physics constraint breakage.
### ⚡ Input-Agnostic Action Routing
* Hand interaction components (`UVRGrabComponent` & `UVRInteractor`) automatically route VR controller inputs (Trigger, Primary, Secondary) directly to the targeted component based on hand context.
### 📦 Zero-Allocation Object Pooler Subsystem
* Spent shell casings (`AVREjectedCasing`), live projectiles (`AVRProjectileBase`), and impact decals are managed by `UUnrealObjectPooler` (a lightweight `UWorldSubsystem`).
* Completely eliminates Garbage Collection (GC) frame stutters during sustained automatic gunfire.
### 🎯 Procedural Recoil Damping & Two-Handed Handling
* Includes dual spring-damper recoil solvers (Rotational & Linear Kickback) with 500Hz sub-stepping stability.
* Automatically shifts recoil pivot points and dampens impulses when stabilizing a firearm with a secondary hand grip.
---
## 🏗️ Architecture & Included Modules
The plugin is partitioned into 3 decoupled runtime and editor modules:
1. `VRModularWeaponSystem` (Runtime): Core weapon container actors, kinematic components, hand grab logic, and StateTree execution schema.
2. `ObjectPooler` (Runtime Subsystem): High-efficiency World Subsystem for zero-allocation projectile, casing, and decal pooling.
3. `VRModularWeaponSystemEditor` (Editor Tooling): Custom Slate viewports, assembly panels, and 4 dedicated data asset inspector toolkits.
---
## 📋 Technical Details & Specifications
- Features:
- Modular Weaponsmith C++ Component Framework (Magwell, Chamber, Muzzle, Mechanical, Feedback).
- 4 Custom Slate 3D Editor Viewports for live visual part assembly, bullet stacking, attachment stat impact, and spread preview.
- Native StateTree Integration for chamber states, multi-chamber ejection, reloading, and safety logic.
- Sub-Frame Execution (`FSTTask_FastFire`) enabling 1200+ RPM automatic fire without StateTree lag.
- Zero-GC Object Pooler Subsystem for projectiles, casings, and decals.
- Kinematic low-latency mechanical slide/bolt simulation without physics jitter.
- Unified 4-Node Blueprint Factory Spawning Architecture.
- Ready-to-use preset weapon templates in Plugin Content.
- Code Modules:
- `VRModularWeaponSystem` (Runtime)
- `VRModularWeaponSystemEditor` (Editor)
- `ObjectPooler` (Runtime World Subsystem)
- Plugin Dependencies / Prerequisites:
- Niagara (Enabled)
- GameplayStateTree (Enabled)
- StateTree (Enabled)
- Number of Blueprints: 5 Base Blueprints + Turnkey Templates
- Number of C++ Classes: 37
- Network Replicated: No (Client-Side Kinematic / Singleplayer VR Framework)
- Supported Development Platforms: Windows (Yes), Mac (Yes)
- Supported Target Build Platforms: Windows, Mac, Linux, Android (Meta Quest)
- Documentation: https://ctrlaltbo.com/projects/weaponsmith-plugin/](https://ctrlaltbo.com/projects/weaponsmith-plugin/
- Example Project: https://ctrlaltbo.com/projects/weaponsmith-plugin/](https://ctrlaltbo.com/projects/weaponsmith-plugin/
- Important/Additional Notes: Built and verified for UE 5.3 through UE 5.8.
---
## ⚙️ Recommended VR Engine Rendering Settings
For maximum VR frame rates (90+ FPS in UE5), we recommend configuring host project rendering settings as follows:
| Setting | Recommended Value | Rationale |
| :--- | :--- | :--- |
| Global Illumination | `None` or `Screen Space` | Bypasses heavy Lumen ray tracing in dual-eye stereo. |
| Reflections Method | `Screen Space` or `None` | Eliminates per-frame Lumen reflection calculations. |
| Shadow Map Method | `Shadow Maps` (Cascaded) | Reduces Virtual Shadow Map (VSM) GPU rendering cost. |
| Forward Shading | `True` (Optional) | Significantly boosts frame rate on PCVR and Standalone Quest setups. |
---
## 🤖 Generative AI Disclosure
Generative AI was utilized during the development of this project for:
* Assisting in Slate UI component layout boilerplate generation.
* Code performance auditing and optimization profiling guidance.