add doc detail free count box, transition, free component

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

@@ -0,0 +1,105 @@
+---
+sidebar_position: 2
+---
+
+# Free Spins Implementation Guide
+
+## Overview
+The Free Spins feature provides bonus rounds where players:
+- Receive complimentary spins
+- Can win prizes without additional bets
+- Often encounter enhanced winning opportunities
+
+![Free Spins Overview](./img/freespins/fs-trigger.jpg)
+
+## Setup Process
+
+### 1. Asset Configuration
+
+#### Core Components
+Required prefabs from core package:
+![Core Assets](./img/freespins/freespin-prefabs-core.png)
+
+#### Game-Specific Assets
+Implementation prefabs:
+![Game Assets](./img/freespins/freespin-prefabs-game.png)
+
+### 2. Background Configuration
+
+1. **Animation Setup**
+   ```typescript
+   // Add to Animation Provider
+   animationProvider.addAnimation('freespin-background');
+   ```
+   ![Animation Config](./img/freespins/add-anim-background.png)
+
+2. **Display Modes**
+   | Mode | Configuration |
+   |------|---------------|
+   | Landscape | ![Landscape](./img/freespins/set-background-freespin-landscape.png) |
+   | Portrait | ![Portrait](./img/freespins/set-background-freespin-portrait.png) |
+
+### 3. Feature Implementation
+
+#### Scene Structure
+Required components:
+- Trigger Display
+- Retrigger Handler
+- Win Presentation
+
+![Scene Components](./img/freespins/featrue-freespin-in-scenes.png)
+
+#### Component Setup
+
+1. **Trigger Configuration**
+   - Add assets:
+     - Fonts
+     - Textures
+   ![Trigger Setup](./img/freespins/trigger-freespin.png)
+
+2. **Retrigger Configuration**
+   - Configure display elements
+   ![Retrigger Setup](./img/freespins/retrigger-freespin.png)
+
+3. **Win Display**
+   - Set congratulations assets
+   ![Win Setup](./img/freespins/win-freespin.png)
+
+:::tip Configuration Guidelines
+Maintain consistency with game design specifications for:
+- Font selection
+- Visual elements
+- Animation timing
+:::
+
+### 4. Optional Enhancements
+
+#### Sidebands
+Classic slot visual enhancement:
+```typescript
+interface SidebandConfig {
+    particleEffect: 'particle-free-sideband';
+    background: 'sideband-back';
+    foreground: 'sideband';
+    shine: 'sideband-shine';
+    liquid: 'sideband-static';
+    indicator: 'indicator-static';
+}
+```
+![Sideband Implementation](./img/freespins/freespin-sideband.png)
+
+#### Transitions
+Polish between game states:
+1. Configure animation provider
+2. Set node mappings
+![Transition Config](./img/freespins/setup-transition.png)
+
+## Implementation Examples
+
+### Feature Flow
+1. **Trigger**
+   ![Trigger Example](./img/freespins/fs-trigger.jpg)
+2. **Active State**
+   ![Active Example](./img/freespins/fs-scene.jpg)
+3. **Completion**
+   ![Complete Example](./img/freespins/fs-congra.jpg)

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

@@ -27,11 +27,14 @@ The **Free Spin (or Free Games) Feature** awards players a set number of spins w
 
 ![Add Animation](./img/freespins/add-anim-background.png)
 
-#### Step 2: Set Display Parameters
+#### Step 2: Configure Display
 
-- Configure **landscape** and **portrait** modes:
+- **landscape**:
 
 ![Landscape Background](./img/freespins/set-background-freespin-landscape.png)  
+
+- **portrait**:
+
 ![Portrait Background](./img/freespins/set-background-freespin-portrait.png)
 
 #### Step 3: Asset Example
@@ -40,7 +43,7 @@ The **Free Spin (or Free Games) Feature** awards players a set number of spins w
 
 ---
 
-#### Main Scene Structure
+#### Main Scene Structure Free Spins
 
 Your scene should include the following nodes:
 
@@ -50,28 +53,91 @@ Your scene should include the following nodes:
 
 ![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
 
-##### 1. Free Spin Trigger
+##### Trigger and Retrigger Setup
 
-- Add fonts and textures for Free Spin trigger.
+Configure animations for both trigger and retrigger.
+
+![content](./img/freespins/add-anim-freespin.png)               
+![content](./img/freespins/add-anim-content.png)
+
+| Node Name | Purpose                                          | Location in Core Package                                   |
+|-----------| ------------------------------------------------ | ---------------------------------------------------------- |
+| `content` | Zoom-in and zoom-out animation | `assets/core-assets/slotty-core/packages/feature-game/animations` |
+
+![config](./img/freespins/freespin-trigger.png)
+
+|       Property         |      Description          |
+|------------------------|---------------------------|
+| `durationPresentation` |  Specifies how long (in seconds) the animation trigger plays before auto-stopping  |
+
+![Effect Example](./img/freespins/effect-explosive.png)
+
+| Prefab Name | Purpose                                          | Location in Core Package                                   |
+| ----------- | ------------------------------------------------ | ---------------------------------------------------------- |
+| `explosive` | Background animation effect triggered by numbers | `assets/core-assets/hyper-core/packages/explosive/prefabs` |
+
+![particles](./img/freespins/textture-particles.png)
+![particles](./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. Free Spin Retrigger
+##### 2. present freespin retrigger
 
-- Add fonts and textures to show retrigger effect.
+Add fonts and textures to show retrigger effect.
 
 ![Retrigger](./img/freespins/retrigger-freespin.png)
 
-##### 3. Free Spin Win
+##### Add Font
 
-- Add congratulations font and texture.
+![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.
 :::
@@ -80,20 +146,30 @@ Follow the visual and font flow as defined by your game's design system.
 
 #### Free Spins Count Box
 
-| Step | Description | Image |
-|------|-------------|-------|
-| 1    | Locate prefab in Core: `freespins-count-box` | ![Core Prefab](./img/freespins/find-freespin-box.png) |
-| 2    | Add the prefab to main game scene | ![In Scene](./img/freespins/game-freespin-box.png) |
-| 3    | Desktop / Mobile | ![mode mobile](./img/freespins/both-mode-mobile.png) 
+| 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 appearance in both desktop and mobile modes. | ![mode mobile](./img/freespins/both-mode-mobile.png) |
 
-![Assets](./img/freespins/assets-freespin-count.png) 
+##### Platform Setup
 
-**Asset Mapping:**
+| 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 Name | Node/Preference Name |
-|------------|----------------------|
-| `box-freespin` |     `bg`         |
-| `freespins`    | `freespins`      |
+##### Asset Setup
+
+| 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 Background                                             | ![common Asset](./img/freespins/freespin-counter-box-common.png) |
+
+##### Asset Font
+
+![common Asset](./img/freespins/set-font-freespin-count-box.png) 
 
 ---
 
@@ -101,11 +177,10 @@ Follow the visual and font flow as defined by your game's design system.
 
 - Optional visual element, commonly used in classic or legacy slot designs.
 
-![Sidebands](./img/freespins/freespin-sideband.png)
+| Overview                                   | Setup                                        |
+|-------------------------------------------|----------------------------------------------|
+| ![Sidebands](./img/freespins/freespin-sideband.png) | ![Sideband Assets](./img/freespins/assets-freespind-sideband.png) |
 
-**Setup Instructions:**
-
-![Sideband Assets](./img/freespins/assets-freespind-sideband.png)
 
 **Asset Mapping:**
 
@@ -122,15 +197,32 @@ Follow the visual and font flow as defined by your game's design system.
 
 #### Transition Effects (Optional)
 
-- These transitions create visual polish between game phases.
+create new node and add `transition`, `transition-scaler` component.
 
 ![Transition Setup](./img/freespins/setup-transition.png)
 
-Steps:
+| 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)