Merge pull request 'updates/20250606-update-freespin' (#76) from updates/20250606-update-freespin into develop

Reviewed-on: #76

docs/03-setup-special-feature/02-free-spin.md

@@ -7,6 +7,269 @@ sidebar_position: 2
 ## Overview
 The **Free Spin (or Free Games) Feature** awards players a set number of spins without requiring additional bets. During these spins, players can still win prizes—often larger than in the base game—without spending any of their own credits.
 ![Free Spin Overview](./img/freespins/fs-trigger.jpg)
-## Implementation
 
-### Prepare Assets
+## Implementation Guide
+
+### Prepare Assets
+
+| Component Type         | Description                                       | Visual |
+|------------------------|---------------------------------------------------|--------|
+| **Core Components**    | Locate the prefabs from the core package.         | ![Core Prefabs](./img/freespins/freespin-prefabs-core.png) |
+| **Game-Specific Components** | Prefabs are already present in the main game scene. | ![Game Prefabs](./img/freespins/freespin-prefabs-game.png) |
+
+---
+
+### Setup Scene
+
+#### Structure Free Spins
+
+Your scene should include the following nodes:
+
+- **Trigger**
+- **Retrigger**
+- **Win**
+
+***Example Scene Structure:***
+
+![Scene Structure](./img/freespins/featrue-freespin-in-scenes.png)
+
+|      Property            | Description                                               |
+|------------------------- |----------------------------------------------------------|
+| `transitionStart`        | Triggers the show animation when Free Spins start.<br/>Default: `null`. |
+| `transitionStop`         | Triggers the return animation to the base game.<br/>Default: `null`.    |
+| `nodeActivate`           | Maintains the visual state during Free Spins.             |
+| `freeSideBandContainer`  | Activates the Free Spins side band visual.                |
+
+---
+#### Component Configuration
+
+##### Trigger & Retrigger
+
+To configure the Free Spin **trigger** and **retrigger** components, follow these steps:
+
+1. **Add Animations** 
+
+Include the required animations for both the trigger and retrigger elements.
+
+![Add Animation](./img/freespins/add-anim-freespin.png)
+![Add Animation Content](./img/freespins/add-anim-content.png)
+
+| Node Name | Purpose                                 | Location in Core Package                                         |
+|-----------|-----------------------------------------|------------------------------------------------------------------|
+| `content` | Handles zoom-in and zoom-out animations | `assets/core-assets/slotty-core/packages/feature-game/animations` |
+
+![Trigger Config](./img/freespins/freespin-trigger.png)
+
+| Property               | Description                                                              |
+|------------------------|--------------------------------------------------------------------------|
+| `durationPresentation` | Duration (in seconds) the trigger animation plays before auto-stopping   |
+
+2. **Add Background Animation Effect**  
+
+![Effect Example](./img/freespins/effect-explosive.png)
+
+| Prefab Name | Purpose                                         | Location in Core Package                                    |
+|-------------|-------------------------------------------------|-------------------------------------------------------------|
+| `explosive` | Background animation effect triggered           | `assets/core-assets/hyper-core/packages/explosive/prefabs`  |
+
+3. **Configure Particle Effects**  
+
+![Particles](./img/freespins/textture-particles.png)
+![Set Particles Scale](./img/freespins/set-particles-scale.png)
+
+| Node Name   | Purpose                                                                                 | Location in Core Package                                   |
+|-------------|-----------------------------------------------------------------------------------------|------------------------------------------------------------|
+| `particles` | - Particle effects around title and number triggers.<br/>- Set scale to `1` for visibility. | `assets/core-assets/slotty-core/packages/present/particles` |
+
+:::tip
+Set up the **present freespin retrigger** in the same way as the **present freespin trigger**.
+:::
+
+##### 1. present freespin trigger
+    
+Add fonts and textures for Free Spin trigger.
+
+![Trigger](./img/freespins/trigger-freespin.png)
+
+##### 2. present freespin retrigger
+
+Add fonts and textures to show retrigger effect.
+
+![Retrigger](./img/freespins/retrigger-freespin.png)
+
+##### Add Font
+
+![config](./img/freespins/trigger-freespin-font.png)
+
+#### 3. Present Free Spin Win
+
+**Free Spin Win Setup**
+
+![Win](./img/freespins/set-freespin-win.png)
+
+| Property                | Description                                                                                   |
+|-------------------------|-----------------------------------------------------------------------------------------------|
+| `content`               | Node for displaying the win animation content.                                                |
+| `durationPresentWin`    | Duration (in seconds) that the win presentation is shown.                                     |
+| `animation`             | - Animation controller for the win presentation.<br/>- Located at: `assets/core-assets/slotty-core/packages/feature-game/animations` |
+| `clipStartPresentation` | Animation clip played when the win presentation starts.                                       |
+| `clipStopPresentation`  | Animation clip played when the win presentation ends.                                         |
+| `allowPresentWinPoint`  | Enables the display of win points during the presentation.                                    |
+| `durationCountPoint`    | Duration (in seconds) for counting up win points.                                             |
+| `lblTotalWinPoint`      | Label node showing the total win points.                                                      |
+| `lblTotalFreeSpinCount` | Label node showing the total number of free spins awarded.                                    |
+
+- Add congratulatory font and texture for the win display.
+
+![Win](./img/freespins/win-freespin.png)
+
+---
+
+:::tip Best Practice
+Follow the visual and font flow as defined by your game's design system.
+:::
+
+---
+#### Free Spins Count Box
+
+The **Free Spins Count Box** displays the remaining number of free spins to the player. Follow these steps to set it up:
+
+##### Steps to Add the Count Box
+
+| Step | Description                                                                 | Image                                         |
+|------|-----------------------------------------------------------------------------|-----------------------------------------------|
+| 1    | Locate the `freespins-count-box` prefab in the Core package.                | ![Core Prefab](./img/freespins/find-freespin-box.png) |
+| 2    | Add the `freespins-count-box` prefab to your main game scene.               | ![In Scene](./img/freespins/game-freespin-box.png) |
+| 3    | Verify its appearance in both desktop and mobile modes.                     | ![Mobile Mode](./img/freespins/both-mode-mobile.png) |
+
+##### Platform-Specific Setup
+
+Assign the appropriate node and controller for each platform:
+
+| Platform | Node Name                | Component to Add            | Example Image                                         |
+|----------|--------------------------|-----------------------------|-------------------------------------------------------|
+| Desktop  | `freespins-box-desktop`  | `Platform-ui-controller`    | ![Desktop Controller](./img/freespins/add-script-freespin-counter.png) |
+| Mobile   | `freespins-box-mobile`   | `Platform-ui-controller`    | ![Mobile Controller](./img/freespins/add-script-freespin-counter-mobile.png) |
+
+##### Asset Configuration
+
+Ensure the correct assets are used for each platform:
+
+| Platform | Asset Path                                                        | Example Image                                                                 |
+|----------|-------------------------------------------------------------------|-------------------------------------------------------------------------------|
+| Desktop  | `assets/game-assets/textures/desktop/preloads/main-game/custom-scale` | ![Desktop Assets](./img/freespins/freespin-counter-box-desktop.png) |
+| Mobile   | `assets/game-assets/textures/mobile/preloads/main-game/custom-scale`  | ![Mobile Assets](./img/freespins/freespin-counter-box-mobile.png)  |
+| Common   | Freespins Box Background                                              | ![Common Asset](./img/freespins/freespin-counter-box-common.png) |
+
+##### Font Setup
+
+Set the font for the count box display:
+
+![Font Setup](./img/freespins/set-font-freespin-count-box.png)
+
+---
+#### Free Spin Background Setup
+
+##### 1. Add Animation to Animation Provider
+
+Add the Free Spin background animation to your **Animation Provider**.
+
+![Add Animation](./img/freespins/add-anim-background.png)
+
+##### 2. Configure Background Display
+
+Set up the background for both landscape and portrait modes:
+
+- **Landscape Mode**  
+
+![Landscape Background](./img/freespins/set-background-freespin-landscape.png)
+
+- **Portrait Mode**  
+
+![Portrait Background](./img/freespins/set-background-freespin-portrait.png)
+
+
+##### 3. Asset Example
+
+Example background assets for Free Spin:
+
+![Background Assets](./img/freespins/assets-freespin-background.png)
+
+
+#### Sidebands (Optional)
+
+Sidebands are optional visual elements, often used in classic slot game designs.
+
+| Preview | Asset Structure |
+|---------|----------------|
+| ![Sidebands](./img/freespins/freespin-sideband.png) | ![Sideband Assets](./img/freespins/assets-freespind-sideband.png) |
+
+**Setup Steps:**
+
+1. **Add Preference:**  
+    Add the free sideband preference in your configuration.  
+    ![Add Preference](./img/freespins/add-preference-free-sideband.png)
+
+2. **Assign Texture:**  
+    Set the correct texture for the free sideband.  
+    ![Add Texture](./img/freespins/add-texture-free-sideband.png)
+
+**Asset Mapping:**
+
+| Asset Name                | Node/Preference Name    |
+|---------------------------|------------------------|
+| `anim-free-sideband-static` | `particle-free-sideband` |
+| `sideband-back`           | `sideband-back`        |
+| `sideband`                | `sideband`             |
+| `sideband-shine`          | `sideband-shine`       |
+| `sideband-static`         | `liquid`               |
+| `indicator-static`        | `indicator-static`     |
+
+---
+
+#### Transition Effects (Optional)
+
+##### Setup: Create Transition Node
+
+1. **Create a new node** in your scene for the transition effect.
+2. **Add the following components** to this node:
+    - `transition`
+    - `transition-scaler`
+3. Configure the transition properties as required for your effect.
+
+![Transition Setup](./img/freespins/setup-transition.png)
+
+| Property           | Description                                |
+|--------------------|--------------------------------------------|
+| `content`          | Target node for transition effects         |
+| `animationName`    | Animation identifier/reference             |
+| `sfxName`          | Sound effect identifier                    |
+| `transitionFrame`  | Frame to trigger transition callback       |
+
+
+##### Asset Setup
+
+1. Add transition animation to the **Animation Provider**.
+2. Match the animation name with the correct node.
+
+![Transition Setup](./img/freespins/add-anim-transition.png)
+
+**add preferrence**
+
+Configure preferences as needed for your transition.
+
+![Transition Setup](./img/freespins/add-preference-transition.png)
+
+**Example Result:**
+
+![Transition Result](./img/freespins/fs-transition.jpg)
+
+---
+
+## Final Result Examples
+
+| Phase | Image |
+|-------|-------|
+| Trigger | ![Trigger](./img/freespins/fs-trigger.jpg) |
+| Active Scene | ![Scene](./img/freespins/fs-scene.jpg) |
+| Completion | ![Congrats](./img/freespins/fs-congra.jpg) |