Merge pull request 'add setup game asset structurre' (#77) from add-setup-game-asset-structure into develop

Reviewed-on: #77

docs/04-game-asset-structure/01-default-assets-structure.md

@@ -3,5 +3,365 @@ sidebar_position: 1
 ---
 
 # Default Asset Structure
+---
+
+## Overview
+
+|        | Core Asset | Game Asset |
+| :--:   | :---------- | :---------- |
+|<img width="400"/>![Overview](./img/overview.png) | - Contains all the necessary game modules.<br/>- Reviewing the [Add submodules](../setup-the-project/add-submodules) for details. | - Contains all the necessary game assets.<br/>- Reviewing the [Create Game Folder Structure](../setup-the-project/create-game-folder-structure) for details. |
+
+## Asset Folder Structure
+
+### Asset Loading Manager
+
+#### Preloads Asset
+
+Refers to the process of loading necessary game resources (such as images, audio, animations, prefabs, etc.) into memory before they are needed in the game.
+
+❓ Why Preload Asset?
+
+🔹Reduce runtime lag: Prevents the game from stuttering or freezing when assets are loaded on demand.<br/>
+🔹Improve user experience: Ensures smooth transitions between scenes or when many resources are needed quickly.<br/>
+🔹Better memory management: Allows you to control exactly when and what to load into memory.
+
+#### Postloads Asset
+
+Refers to the process of loading resources after the game or a scene has already started running. This is often used to optimize initial loading time and to progressively load non-critical assets in the background.
+
+❓ Why Use Postloads Asset?
+
+🔹Faster initial loading: Only essential assets are preloaded; the rest can be loaded later.<br/>
+🔹Better performance on low-end devices: Distributes memory usage more efficiently.<br/>
+🔹Allows dynamic content loading: You can load content only when it’s actually needed (e.g., when entering a specific area or level).
+
+**Example:** Assets used for background.
+
+🔹Preloads Asset contains static image with low capacity.<br/>
+🔹Postloads Asset contains animation with higher capactity.
+
+![Asset Loading Manager](./img/assets-loading-manager.png)
+
+### Asset Platform Manager
+#### 💻 Desktop Asset
+
+Refer to visual, audio, or data resources that are specifically designed to take advantage of the performance, resolution, and user interaction available on desktop computers and laptops.
+
+🔹High-resolution textures and sprites<br/>
+🔹Advanced visual effects (particles, lighting, shaders)<br/>
+🔹High-quality audio files (uncompressed or lightly compressed)<br/>
+🔹UI/UX elements optimized for mouse and keyboard<br/>
+🔹Assets that support large resolutions (Full HD, 2K, 4K)<br/>
+
+❓ Why use Desktop-Specific Assets?
+
+🔹Performance optimization: Desktops can handle larger and more detailed assets due to stronger hardware.<br/>
+🔹Enhanced experience: Larger screens and precise input devices allow for more complex and polished visuals.<br/>
+🔹Scalability: Developers can utilize advanced shaders, visual effects, or input schemes not suitable for other platforms.
+
+#### 📱Mobile Asset
+
+Refers to images, audio, and other data that are specifically designed or adjusted to meet the hardware limitations, screen sizes, and memory constraints of smartphones and tablets.
+
+🔹Smaller and optimized images (compressed textures).<br/>
+🔹UI/UX tailored for touch input and smaller screens.<br/>
+🔹Simplified effects with reduced use of heavy shaders.<br/>
+🔹On-demand asset loading to minimize memory usage.
+
+❓ Why Optimize Assets for Mobile?
+🔹Hardware limitations: Mobile devices have less RAM and GPU power compared to desktops → assets must be lightweight.<br/>
+🔹Storage size constraints: Mobile apps are often limited in total install size.<br/>
+🔹Better performance & stability: Lighter assets improve game loading speed, reduce crashes, and enhance compatibility across different devices.
+
+**Example:** Assets used for background.
+
+ - Assets used for desktop have larger size and capacity than mobile.
+
+![Asset Platform Manager](./img/assets-platform-manager.png)
+
+#### Custom Scaler
+
+##### Overview
+
+This script generates custom scaling ratios for assets in a Cocos Creator project, particularly handling different scaling needs for desktop and mobile platforms.
+
+##### Configuration Steps
+
+###### Create the Script
+
+- Name the script: `custom-scale-data`
+- Location: `assets/game-assets/scripts/custom-scaler/`
+
+###### Configure the Script
+
+- Refer to the following image for a general setup example:
+
+    ![General Assets Custom Scaler](./img/genernal-custom-scaler.png)
+
+    ```js
+    // custom-scale-data.js
+    cc.CustomScaler.CustomScaleRatio["uuid0"] = 0.75;
+    cc.CustomScaler.CustomScaleRatio["uuid1"] = 0.7;
+    cc.CustomScaler.CustomScaleRatio["uuid2"] = 0.58;
+    ```
+
+##### Asset Scaling Rules
+
+Assets in the project should be scaled according to their type and location:
+
+| Asset Type      | Asset Path Contains | Condition                                 | Scale Ratio |
+|-----------------|---------------------|-------------------------------------------|-------------|
+| Font files      | `fnt-`              | -                                         | 1.0         |
+| Desktop assets  | `desktop`           | Inside `custom-scale` folder              | 1.0         |
+| Desktop assets  | `desktop`           | Outside `custom-scale` folder             | 0.75        |
+| Mobile assets   | `mobile`            | Inside `custom-scale` folder              | 0.7         |
+| Mobile assets   | `mobile`            | Outside `custom-scale` folder             | 0.58        |
+
+**Folder structure:**
+
+```plaintext
+assets/
+├── fnt-arial.png (.jpg)              # remains at 1.0
+├── desktop/
+│   ├── sprite.png (.jpg)             # scaled to 0.75
+│   └── custom-scale/
+│       └── sprite.png  (.jpg)        # remains at 1.0
+└── mobile/
+    ├── sprite.png  (.jpg)            # scaled to 0.58
+    └── custom-scale/
+        └── sprite.png  (.jpg)        # remains at 0.7
+```
+:::tip
+Assets inside the `custom-scale` folder maintain their original quality, ensuring clear and sharp rendering.
+:::
+
+**Example:**
+
+![Assets Custom Scaler](./img/assets-custom-scaler.png)
+
+#### Prefabs
+
+| Desktop Prefab | Mobile Prefab |
+|:--------------:|:-------------:|
+| ![Prefabs Desktop](./img/prefabs-desktop.png) | ![Prefabs Mobile](./img/prefabs-mobile.png) |
+
+
+
+### Asset Features Manager
+
+#### Main Game Asset
+
+##### Overview
+
+Main game assets are stored in the `main-game` folder, organized by platform and loading type:
+
+```plaintext
+    assets/
+    └── game-assets/
+        ├── Font/
+        |    └──main-game
+        ├── Sound/
+        |    └──main-game
+        └── textures/
+            ├── desktop/
+            │   ├── preload/        # Load at startup
+            |   |       └──main-game   
+            │   └── postload/       # Load later
+            |           └──main-game   
+            |
+            └── mobile/
+                ├── preload/        # Load at startup
+                |       └──main-game   
+                └── postload/       # Load later
+                        └──main-game   
+```
+
+- `desktop` and `mobile`: Separate folders for each platform.
+- `preload`: Needed right away.
+- `postload`: Can load after startup.
+- Everything is organized under `main-game`.
+
+
+##### Platform-Specific Structures
+
+| Sound Example | Font Example |
+|:-------------:|:-----------:|
+| ![sound-main-game](./img/sound-main-game.png) | ![font-main-game](./img/font-main-game.png) |
+
+| Desktop Structure | Mobile Structure |
+|:-----------------:|:---------------:|
+| ![Desktop Asset Structure](./img/assets-structure-desktop.png) | ![Mobile Asset Structure](./img/assets-structure-mobile.png) |
+
+:::tip
+When a feature is activated, its assets are loaded directly, bypassing the main game asset folders.
+:::
+
+---
+
+#### Feature Game Asset
+
+##### Overview
+
+Feature game assets (e.g., free-game, pickup, bonus, gamble) are stored in a folder named after the feature, and organized by platform (`desktop`, `mobile`) and loading type (`preload`, `postload`).
+
+**Folder structure:**
+```plaintext
+    assets/
+    └── game-assets/
+        ├── Font/
+        |    └──free-game
+        ├── Sound/
+        |    └──free-game
+        └── textures/
+            ├── desktop/
+            │   ├── preload/        # Load at startup
+            |   |     └──free-game   
+            │   └── postload/       # Load later
+            |        └──free-game   
+            |
+            └── mobile/
+                ├── preload/        # Load at startup
+                |     └──free-game   
+                └── postload/       # Load later
+                    └──free-game   
+```
+##### Platform-Specific Structures
+
+| Feature Game Example | Desktop Structure | Mobile Structure |
+|:-----------:|:-----------------:|:---------------:|
+| ![Feature Game](./img/feature-assets.png) | ![Desktop Asset Structure](./img/feature-assets-desktop.png) | ![Mobile Asset Structure](./img/feature-assets-mobile.png) |
+
+---
+
+#### Localized Assets
+
+The `localizes/` folder stores language-specific assets (e.g., `zh`, `th`, `id`, etc.), allowing the game to display the correct fonts and textures based on the selected language.
+
+##### Folder structure:
+
+```plaintext
+    assets/
+    └── game-assets/
+        ├── fonts/
+        │   ├── localizes/       # Fonts for each language
+        │   └── preloads/        # Default fonts (usually English) loaded at startup
+        └── textures/
+            ├── desktop/
+            │   ├── localizes/   # Desktop textures for each language
+            │   ├── postloads/   # Desktop textures loaded after startup (default: en)
+            │   └── preloads/    # Desktop textures loaded at startup (default: en)
+            └── mobile/
+                ├── localizes/   # Mobile textures for each language
+                ├── postloads/   # Mobile textures loaded after startup (default: en)
+                └── preloads/    # Mobile textures loaded at startup (default: en)
+```
+
+- Assets in `localizes/` are organized by language code (e.g., `zh`, `th`, `id`).
+- Sprites in `preloads/` and `postloads/` use English (`en`) as the default language.
+
+![Location](./img/localizes-assets.png)
+
+---
+
+#### Meta JSON Merger
+
+##### Purpose
+
+Merges JSON metadata files under library/imports/ into one fullMetaData.json.
+
+![Purpose](./img/merge-json-assets.png)
+
+###### Excludes:
+
+- cc.SceneAsset 
+- cc.Prefab
+
+```json
+{
+  "asset1.json": { /* metadata */ },
+  "asset2.json": { /* metadata */ }
+}
+```
+---
+
+#### Texture Compression Tool
+
+##### Purpose
+
+Manages and applies compression settings to game textures.
+
+![Compression](./img/compress-over.png)
+
+##### Compression Settings
+| Description | Action Compress Texture |
+|:----------- |:----------------------:|
+| Compresses all textures in:<br/>- `assets/Core`<br/>- `assets/game` | ![Compression](./img/compress-texture.png) |
+| Compresses all textures in:<br/>- `assets/game` only | ![Compression](./img/compress-texture1.png) |
+| Removes all compression settings | ![Compression](./img/compress-texture2.png) |
+
+**Example:**  
+Compression settings for PNG and JPG formats:
+
+![Compression Settings](./img/compress-setting.png)
+
+##### Workflow
+
+1. **Query** texture assets by UUID
+2. **Apply** compression settings to their meta data
+3. **Save** updated meta files
+4. **Log** progress and handle errors in console
+
+##### Benefits
+
+* Reduces texture file sizes
+* Speeds up builds and runtime loading
+* Supports platform-specific formats
+* Batch processing for efficiency
+
+---
+
+#### Remove Packable Texture Tool
+
+##### Overview
+
+Removes the `packable` flag from all texture assets to prevent automatic atlas packing.
+
+![Remove Packable](./img/remove-packable-texture.png)
+
+
+##### Why Remove Packable
+
+Removing the `packable` flag gives you:
+- **Better memory management** – load/unload textures individually
+- **Prevents automatic atlas generation** – useful for large or dynamic textures
+
+###### Use Cases
+- Large background images
+- Special effects (particles, dynamic textures)
+- Render textures
+- Dynamically loaded assets
+- High-res UI elements with custom compression needs
+
+##### Query Texture
+
+- Scans `db://assets/**/*` for all texture assets.
+
+**Example:**   
+
+Compression settings for PNG and JPG formats:               
+![Remove Packable](./img/remove-packable.png)
+
+---
+### Result
+:::tip
+When running the Extension Tool, you can:
+- Add or update textures
+- Add new messages
+- Update existing messages in the game
+:::
+
+After running the Extension Tool, the console will display a summary of the processed textures and any changes made.
+
+![Result console](./img/result-console.png)
+
 
-> To be added

package-lock.json

@@ -8091,9 +8091,9 @@
       }
     },
     "node_modules/docusaurus-lunr-search": {
-      "version": "3.6.1",
-      "resolved": "https://registry.npmjs.org/docusaurus-lunr-search/-/docusaurus-lunr-search-3.6.1.tgz",
-      "integrity": "sha512-ms2FWYzR7OrvS2x0/HSPaAenAATrBenGpCwWpjmpK8SnUpqygVPvuss2RG5l2ZuMxpKFP0rhEnEy8Kx4lSQimw==",
+      "version": "3.6.0",
+      "resolved": "https://registry.npmjs.org/docusaurus-lunr-search/-/docusaurus-lunr-search-3.6.0.tgz",
+      "integrity": "sha512-CCEAnj5e67sUZmIb2hOl4xb4nDN07fb0fvRDDmdWlYpUvyS1CSKbw4lsGInLyUFEEEBzxQmT6zaVQdF/8Zretg==",
       "license": "MIT",
       "dependencies": {
         "autocomplete.js": "^0.37.1",