> For the complete documentation index, see [llms.txt](https://maystudios.gitbook.io/maysimplerecoil/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://maystudios.gitbook.io/maysimplerecoil/getting-started/quickstart.md).
# Quickstart
## 2.1 Installation & Requirements
1. **Installation:**
* **Via Marketplace:** Search for “MaySimpleRecoil” in the Unreal Engine Marketplace and click “Install.”
* **Manual Installation:** Download the plugin package and copy the folder into your project’s `Plugins/` directory.
2. **Engine Compatibility:**\
MaySimpleRecoil System is compatible with Unreal Engine 5.4 and later. Ensure your project meets these requirements before installing.
## 2.2 Basic Setup in a New Project
{% hint style="warning" %}
Please take a look in [Default Implementation](/maysimplerecoil/getting-started/default-vs.-advanced-implementation.md) Page!
{% endhint %}
1. **Add the Recoil Component:**\
Open your Character Blueprint (or Pawn) and add the **MaySimpleRecoilComponent** via the “Add Component” menu. \
For fast Setup please use the [Default Implementation](/maysimplerecoil/getting-started/default-vs.-advanced-implementation.md)! **(****AC\_MaySimpleRecoil\_Default****)**\
The **MaySimpleRecoilComponent** is for advanced own use cases, or to adapt it.
2. **Assign Recoil Data:**\
In the Details panel of the component, set the **RecoilData** property to an existing **UMayRecoilData** asset or create a new one. (Just drag and drop)
3. **Trigger Recoil:**\
To trigger weapon recoil, call the **Recoil()** function on the Recoil Component in your weapon's fire event using either Blueprint or C++. In Blueprint, simply drag out the Recoil Component and select **Recoil()**. The Recoil function will create a new Worker if one isn't already initialized, or it will use the existing Worker to handle the recoil functionality.
4. **Add Yaw and Pitch of Mouse Input:**\
This function ensures secure and accurate restoration of the mouse's default position in the game by verifying user input integrity. It executes cursor repositioning with error handling to prevent issues, maintaining a seamless gaming experience. By using input validation and conditional checks, it enhances user satisfaction and ensures consistent interface behavior.
Add Yaw and Pitch on Mouse Input
5. **Add ADS:**\
The **TrySetADS()** function is designed to determine whether the player can transition into Aim Down Sights (ADS) mode. It utilizes the **CanSwitchToADS()** method, which, by default, evaluates if the player is in a suitable state to perform this switch. Specifically, the default implementation checks conditions such as whether the player is neither falling nor jumping at the time of the transition. These checks are critical to ensure that transitioning to ADS mode occurs smoothly and without interruption by unintended actions or states.
However, developers can easily override the **CanSwitchToADS()** function to modify the behavior and impose custom conditions that better fit their game's unique mechanics or design philosophy. For instance, a game might allow switching to ADS while in mid-air but restrict it when the player is reloading a weapon. By providing the capability to override, the design is flexible enough to accommodate a wide range of scenarios that align with different game dynamics or
Start Camera Aiming and Stop Camera Aiming (only Demo) Right side is important!
## 2.3 Testing the Example Project
### The plugin comes with a full demo project that includes:
* Fully replicated example weapons.
* An Example Widget for live editing of Recoil Data.
* A built-in Spread System for weapon line tracing.
#### **Steps:**
* Open the level found in `Plugins/MaySimpleRecoil Content/Example/DemoMap.umap`.
* Play the level and use the provided widget to adjust recoil parameters in real time.
* Fire the example weapons to see the recoil and spread system in action.
## 3. Recoil Data & Configuration
### 3.1 Understanding UMayRecoilData
The **UMayRecoilData** asset centralizes all configurable parameters for recoil behavior. Key properties include:
* **Vertical Recoil:**
* *MinRecoilVerticalStrength* and *MaxRecoilVerticalStrength*
* *ForceMinMaxVerticalStrength* (if enabled, selects only the min or max value)
* **Horizontal Recoil:**
* *MinRecoilHorizontalStrength* and *MaxRecoilHorizontalStrength*
* *ForceMinMaxHorizontalStrength* (if enabled, selects only the min or max value)
* **Scaling Factors:**
* *RecoilScale* for base scaling.
* Additional multipliers for Sprint, Crouch, Jump, and ADS states (e.g., *RecoilScaleSprint*, *RecoilScaleCrouch*, etc.).
* **Animation Settings:**
* *RecoilSpeed* and *RecoilResetSpeed* determine the speed of the recoil and reset animations.
* *RecoilInterpolation* and *RecoilResetInterpolation* define the easing functions and interpolation steps.
* **Preview Settings:**
* Properties like *NumShots*, *Iterations*, *BulletRadius*, and *CircleThickness* control how recoil patterns are previewed in the editor.
## 4. Use of Data Provider
To leverage specialized data for weapons or actors (objects the player interacts with), you can integrate the **AC\_MaySimpleRecoilDataProvider** into the weapon/object setup. This approach is functional if you utilize the default component implementation provided in the framework. Moreover, the default component implementation serves as an excellent reference model. By examining it, developers can gain insights into how to effectively override existing functions to introduce additional functionalities or customize behavior. **AC\_MaySimpleRecoil\_Default** Component efficiently searches for attached or child actors linked to the character's setup using the **AC\_MaySimpleRecoilDataProvider**. This provider plays a vital role in identifying and connecting relevant actors, ensuring smooth and responsive recoil mechanics in the game, enhancing Gameplay with precise performance dynamics.
For developers looking to expand the capabilities of their game objects, studying the default component approach offers guidance on best practices and patterns. By extending or modifying these components, you can tailor the interaction rules and data handling to align with the specific needs of your game design. Whether you're enhancing weapon systems or building complex actor interactions, the default implementation can be a foundational starting point.
Therefore, when planning to implement new features or modifications, consider using the default components as both an inspiration and a building framework. It not only demonstrates how core mechanics are structured but also opens up possibilities for innovative extensions and improvements in your game environment.
