# 🛠️ 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 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, and a high-performance memory pooling world subsystem.
More images and a component overview are available on my website:
https://ctrlaltbo.com/projects/weaponsmith-plugin/
---
## 🎮 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
### 🛠️ Custom Slate Editor Tooling Suite
*Weaponsmith Asset Editor (`UVRWeaponData`):** Feature-rich visual editor with interactive 3D preview viewports, dynamic socket attachment panels, and real-time comparative stat dashboards.
*Magazine Asset Editor (`UMagazineData`):** Visual customization panel to configure bullet offsets, visual ammo stacking, and capacity limits dynamically in 3D space.
### 🌳 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.
*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 data asset inspector toolkits.
---
## 📋 Technical Details & Specifications
- Features:
- Modular Weaponsmith C++ Component Framework (Magwell, Chamber, Muzzle, Mechanical, Feedback).
- Custom Slate Editor Viewports for live 3D visual part assembly and stat comparison.
- Native StateTree Integration for chamber states, 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.
- Code Modules:
- VRModularWeaponSystem (Runtime)
- VRModularWeaponSystemEditor (Editor)
- ObjectPooler (Runtime World Subsystem)
- Plugin Dependencies / Prerequisites:
- Niagara (Enabled)
- GameplayStateTree (Enabled)
- StateTree (Enabled)
- Number of Blueprints: 5
- Number of C++ Classes: 32
- 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/
- Example Project: 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.