Merge pull request 'feature/add-special-win' (#37) from feature/add-special-win into develop

Reviewed-on: #37

docs/02-setup-main-game/05-main-scene/14-special-win.md

@@ -0,0 +1,170 @@
+---
+sidebar_position: 14
+---
+
+# Special Win Setup
+
+---
+
+## Overview
+
+Special Wins are high-value reward events in slot games, cagegorized based on the payout threshold:
+
+| Win Type  | Trigger Threshold     |    Preview     |
+|-----------|-----------------------|----------------|
+| **Big Win**   | Medium payout         | ![Big](../img/05-main-scene/special-win-big.png) |
+| **Super Win** | High payout           | ![Super](../img/05-main-scene/special-win-super.png) |
+| **Mega Win**  | Maximum payout        | ![Mega](../img/05-main-scene/special-win-mega.png) |
+
+Each type delivers increasing visual excitement to highlight significant player rewards.
+
+---
+
+## Implementation
+
+### Core Components
+
+The special win system consists of three main components:
+
+| Component | Purpose |
+|-----------|---------|
+| `hyper-special-win-initializer` | Handles system initialization and setup |
+| `hyper-present-special-win` | Manages animation sequences and display logic |
+| `hyper-special-win-label-point-effect` | Controls win amount visualization |
+
+![Component Architecture](../img/05-main-scene/special-win-in-game.png)
+
+#### Coin Effect System
+
+The coin shower effect uses prefab variants for different markets:
+
+![Base Coin Asset](../img/05-main-scene/special-win-coin.png)
+
+| Submodule   |   Theme |    Preview    |
+|-------------|---------------|---------------|
+| `hyper-coin-shower-international` | International | ![International Version](../img/05-main-scene/special-win-coin-internation.png) |
+| `hyper-coin-shower-chinese` | Chinese | ![Chinese Version](../img/05-main-scene/special-win-coin-chinese.png) |
+
+:::tip
+- Position the Special Win node as per game design
+:::
+
+---
+
+### Asset Configuration
+
+#### 1. Static Resources
+
+Store static assets in platform-specific directories:
+
+| Platform | Path | Preview |
+|----------|------|---------|
+| Desktop  | `assets/textures/desktop/preloads/special-wins` | ![Desktop](../img/05-main-scene/special-win-folder-desktop.png) |
+| Mobile   | `assets/textures/mobile/preloads/special-wins`  | ![Mobile](../img/05-main-scene/special-win-folder-mobile.png) |
+
+🔗 [View Platform Asset Structure](http://localhost:3000/docs/cagegory/game-asset-structure)
+
+---
+
+#### 2. Animation Setup
+
+##### Special Win Animation Flow
+
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 'fontSize': '25px', 'fontFamily': 'arial' }}}%%
+graph TD
+    %% Win Types with Thresholds
+    SW[Special Wins] --> BW["Big Win"]
+    SW --> SPW["Super Win"]
+    SW --> MW["Mega Win"]
+
+    %% Big Win stages with flow
+    BW --> BWI[bigwin-in]
+    BWI --> BWL[bigwin-loop]
+    BWL --> BWO[bigwin-out]
+
+    %% Super Win stages with flow
+    SPW --> SPWI[superwin-in]
+    SPWI --> SPWL[superwin-loop]
+    SPWL --> SPWO[superwin-out]
+
+    %% Mega Win stages with flow
+    MW --> MWI[megawin-in]
+    MWI --> MWL[megawin-loop]
+    MWL --> MWO[megawin-out]
+
+     %% Legend nodes
+    L0["Feature Name"]-->L1["Win Types"] --> L2["In State"] --> L3["Loop State"] --> L4["Out State"]
+    class L0 specialWin
+    class L1 winType
+    class L2 inStage
+    class L3 loopStage
+    class L4 outStage
+
+    %% Style definitions
+    classDef inStage fill:#e6f3ff,stroke:#666,font-size:25px
+    classDef loopStage fill:#fff2cc,stroke:#666,font-size:25px
+    classDef outStage fill:#f8cecc,stroke:#666,font-size:25px
+    classDef winType fill:#d5e8d4,stroke:#82b366,font-size:25px
+    classDef specialWin fill:#fff4dd,stroke:#ff0000,font-size:25px
+
+    class BWI,SPWI,MWI inStage
+    class BWL,SPWL,MWL loopStage
+    class BWO,SPWO,MWO outStage
+    class BW,SPW,MW winType
+    class SW specialWin
+
+    %% Adjust node spacing
+    linkStyle default stroke-width:4px,stroke:#ff0000
+```
+    ![Type Names](../img/05-main-scene/special-win-type-name.png)
+
+##### Step 1: Add Animation Resources
+
+Place animated assets in the following directories:
+
+| Platform | Path | Preview |
+|----------|------|---------|
+| Desktop  | `assets/textures/desktop/postloads/anim-special-win` | ![Desktop](../img/05-main-scene/special-win-folder-desktop-anim.png) |
+| Mobile   | `assets/textures/mobile/postloads/anim-special-win`  | ![Mobile](../img/05-main-scene/special-win-folder-mobile-anim.png) |
+
+##### Step 2: Configure Animation Settings
+
+| Setting         | Example |
+|------------------|---------|
+| Static Fallback  | ![Static](../img/05-main-scene/special-win-static.png) |
+| Loop Animation   | ![Loop](../img/05-main-scene/special-win-loop.png) |
+
+🔗 [View Animation Provider Setup](http://localhost:3000/docs/setup-main-game/main-scene/system#animation-provider-setup)
+
+:::tip
+- Move assets to `custom-scale/` directory to resolve image quality issues
+- Asset paths may vary by project configuration
+:::
+
+##### Step 3: Font Configuration
+
+- **Path:** `assets\game-assets\fonts\preloads\main-game\fnt-special-win`                       
+- Follow these steps to configure fonts for special win displays:         
+
+1. **Package Font Assets**
+   - Import font files into project
+
+   ![Font Packaging](../img/05-main-scene/special-win-pack-font.png)
+
+2. **Font Integration**
+   - Add font asset to special win component
+
+   ![Font Integration](../img/05-main-scene/special-win-font.png)
+
+3. **Layout Settings**
+
+   - Configure text alignment           
+   - Adjust font size and spacing               
+
+   ![Font Layout](../img/05-main-scene/special-win-font-align.png)
+
+
+:::tip
+Customize font styles based on each game's design.
+:::

docusaurus.config.ts

@@ -31,6 +31,10 @@ const config: Config = {
     locales: ['en'],
   },
 
+  markdown: {
+    mermaid: true
+  },
+
   presets: [
     [
       'classic',
@@ -48,6 +52,10 @@ const config: Config = {
       } satisfies Preset.Options,
     ],
   ],
+  themes: [
+    // ...existing themes if any...
+    '@docusaurus/theme-mermaid'
+  ],
 
   themeConfig: {
     // Replace with your project's social card

package-lock.json

@@ -3646,6 +3646,28 @@
         "react-dom": "^18.0.0 || ^19.0.0"
       }
     },
+    "node_modules/@docusaurus/theme-mermaid": {
+      "version": "3.7.0",
+      "resolved": "https://registry.npmjs.org/@docusaurus/theme-mermaid/-/theme-mermaid-3.7.0.tgz",
+      "integrity": "sha512-7kNDvL7hm+tshjxSxIqYMtsLUPsEBYnkevej/ext6ru9xyLgCed+zkvTfGzTWNeq8rJIEe2YSS8/OV5gCVaPCw==",
+      "license": "MIT",
+      "dependencies": {
+        "@docusaurus/core": "3.7.0",
+        "@docusaurus/module-type-aliases": "3.7.0",
+        "@docusaurus/theme-common": "3.7.0",
+        "@docusaurus/types": "3.7.0",
+        "@docusaurus/utils-validation": "3.7.0",
+        "mermaid": ">=10.4",
+        "tslib": "^2.6.0"
+      },
+      "engines": {
+        "node": ">=18.0"
+      },
+      "peerDependencies": {
+        "react": "^18.0.0 || ^19.0.0",
+        "react-dom": "^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/@docusaurus/theme-search-algolia": {
       "version": "3.7.0",
       "resolved": "https://registry.npmjs.org/@docusaurus/theme-search-algolia/-/theme-search-algolia-3.7.0.tgz",

package.json

@@ -17,6 +17,7 @@
   "dependencies": {
     "@docusaurus/core": "3.7.0",
     "@docusaurus/preset-classic": "3.7.0",
+    "@docusaurus/theme-mermaid": "^3.7.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",