diff --git a/docs/04-game-asset-structure/01-default-assets-structure.md b/docs/04-game-asset-structure/01-default-assets-structure.md index fe6ee71..ce0cbd6 100644 --- a/docs/04-game-asset-structure/01-default-assets-structure.md +++ b/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 | +| :--: | :---------- | :---------- | +|![Overview](./img/overview.png) | - Contains all the necessary game modules.
- Reviewing the [Add submodules](../setup-the-project/add-submodules) for details. | - Contains all the necessary game assets.
- 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.
+🔹Improve user experience: Ensures smooth transitions between scenes or when many resources are needed quickly.
+🔹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.
+🔹Better performance on low-end devices: Distributes memory usage more efficiently.
+🔹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.
+🔹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
+🔹Advanced visual effects (particles, lighting, shaders)
+🔹High-quality audio files (uncompressed or lightly compressed)
+🔹UI/UX elements optimized for mouse and keyboard
+🔹Assets that support large resolutions (Full HD, 2K, 4K)
+ +❓ Why use Desktop-Specific Assets? + +🔹Performance optimization: Desktops can handle larger and more detailed assets due to stronger hardware.
+🔹Enhanced experience: Larger screens and precise input devices allow for more complex and polished visuals.
+🔹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).
+🔹UI/UX tailored for touch input and smaller screens.
+🔹Simplified effects with reduced use of heavy shaders.
+🔹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.
+🔹Storage size constraints: Mobile apps are often limited in total install size.
+🔹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:
- `assets/Core`
- `assets/game` | ![Compression](./img/compress-texture.png) | +| Compresses all textures in:
- `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 \ No newline at end of file diff --git a/docs/04-game-asset-structure/img/assets-custom-scaler.png b/docs/04-game-asset-structure/img/assets-custom-scaler.png new file mode 100644 index 0000000..fa4af58 Binary files /dev/null and b/docs/04-game-asset-structure/img/assets-custom-scaler.png differ diff --git a/docs/04-game-asset-structure/img/assets-loading-manager.png b/docs/04-game-asset-structure/img/assets-loading-manager.png new file mode 100644 index 0000000..495121f Binary files /dev/null and b/docs/04-game-asset-structure/img/assets-loading-manager.png differ diff --git a/docs/04-game-asset-structure/img/assets-platform-manager.png b/docs/04-game-asset-structure/img/assets-platform-manager.png new file mode 100644 index 0000000..ff58f8e Binary files /dev/null and b/docs/04-game-asset-structure/img/assets-platform-manager.png differ diff --git a/docs/04-game-asset-structure/img/assets-structure-desktop.png b/docs/04-game-asset-structure/img/assets-structure-desktop.png new file mode 100644 index 0000000..8c4e247 Binary files /dev/null and b/docs/04-game-asset-structure/img/assets-structure-desktop.png differ diff --git a/docs/04-game-asset-structure/img/assets-structure-mobile.png b/docs/04-game-asset-structure/img/assets-structure-mobile.png new file mode 100644 index 0000000..c97656b Binary files /dev/null and b/docs/04-game-asset-structure/img/assets-structure-mobile.png differ diff --git a/docs/04-game-asset-structure/img/compress-over.png b/docs/04-game-asset-structure/img/compress-over.png new file mode 100644 index 0000000..3c41444 Binary files /dev/null and b/docs/04-game-asset-structure/img/compress-over.png differ diff --git a/docs/04-game-asset-structure/img/compress-setting.png b/docs/04-game-asset-structure/img/compress-setting.png new file mode 100644 index 0000000..5405b8c Binary files /dev/null and b/docs/04-game-asset-structure/img/compress-setting.png differ diff --git a/docs/04-game-asset-structure/img/compress-texture.png b/docs/04-game-asset-structure/img/compress-texture.png new file mode 100644 index 0000000..ff3fb7d Binary files /dev/null and b/docs/04-game-asset-structure/img/compress-texture.png differ diff --git a/docs/04-game-asset-structure/img/compress-texture1.png b/docs/04-game-asset-structure/img/compress-texture1.png new file mode 100644 index 0000000..09dc4aa Binary files /dev/null and b/docs/04-game-asset-structure/img/compress-texture1.png differ diff --git a/docs/04-game-asset-structure/img/compress-texture2.png b/docs/04-game-asset-structure/img/compress-texture2.png new file mode 100644 index 0000000..eb9e9f9 Binary files /dev/null and b/docs/04-game-asset-structure/img/compress-texture2.png differ diff --git a/docs/04-game-asset-structure/img/feature-assets-desktop.png b/docs/04-game-asset-structure/img/feature-assets-desktop.png new file mode 100644 index 0000000..ff17d17 Binary files /dev/null and b/docs/04-game-asset-structure/img/feature-assets-desktop.png differ diff --git a/docs/04-game-asset-structure/img/feature-assets-mobile.png b/docs/04-game-asset-structure/img/feature-assets-mobile.png new file mode 100644 index 0000000..4c35ef9 Binary files /dev/null and b/docs/04-game-asset-structure/img/feature-assets-mobile.png differ diff --git a/docs/04-game-asset-structure/img/feature-assets.png b/docs/04-game-asset-structure/img/feature-assets.png new file mode 100644 index 0000000..0b43a1d Binary files /dev/null and b/docs/04-game-asset-structure/img/feature-assets.png differ diff --git a/docs/04-game-asset-structure/img/font-main-game.png b/docs/04-game-asset-structure/img/font-main-game.png new file mode 100644 index 0000000..05203a4 Binary files /dev/null and b/docs/04-game-asset-structure/img/font-main-game.png differ diff --git a/docs/04-game-asset-structure/img/genernal-custom-scaler.png b/docs/04-game-asset-structure/img/genernal-custom-scaler.png new file mode 100644 index 0000000..0ba0c9d Binary files /dev/null and b/docs/04-game-asset-structure/img/genernal-custom-scaler.png differ diff --git a/docs/04-game-asset-structure/img/localizes-assets-zh.png b/docs/04-game-asset-structure/img/localizes-assets-zh.png new file mode 100644 index 0000000..33ca388 Binary files /dev/null and b/docs/04-game-asset-structure/img/localizes-assets-zh.png differ diff --git a/docs/04-game-asset-structure/img/localizes-assets.png b/docs/04-game-asset-structure/img/localizes-assets.png new file mode 100644 index 0000000..fde40d6 Binary files /dev/null and b/docs/04-game-asset-structure/img/localizes-assets.png differ diff --git a/docs/04-game-asset-structure/img/merge-json-assets.png b/docs/04-game-asset-structure/img/merge-json-assets.png new file mode 100644 index 0000000..1f954be Binary files /dev/null and b/docs/04-game-asset-structure/img/merge-json-assets.png differ diff --git a/docs/04-game-asset-structure/img/overview.png b/docs/04-game-asset-structure/img/overview.png new file mode 100644 index 0000000..2e357ba Binary files /dev/null and b/docs/04-game-asset-structure/img/overview.png differ diff --git a/docs/04-game-asset-structure/img/prefabs-desktop.png b/docs/04-game-asset-structure/img/prefabs-desktop.png new file mode 100644 index 0000000..5531fa5 Binary files /dev/null and b/docs/04-game-asset-structure/img/prefabs-desktop.png differ diff --git a/docs/04-game-asset-structure/img/prefabs-mobile.png b/docs/04-game-asset-structure/img/prefabs-mobile.png new file mode 100644 index 0000000..0bbc0ea Binary files /dev/null and b/docs/04-game-asset-structure/img/prefabs-mobile.png differ diff --git a/docs/04-game-asset-structure/img/remove-packable-texture.png b/docs/04-game-asset-structure/img/remove-packable-texture.png new file mode 100644 index 0000000..0647ae1 Binary files /dev/null and b/docs/04-game-asset-structure/img/remove-packable-texture.png differ diff --git a/docs/04-game-asset-structure/img/remove-packable.png b/docs/04-game-asset-structure/img/remove-packable.png new file mode 100644 index 0000000..ff8aad0 Binary files /dev/null and b/docs/04-game-asset-structure/img/remove-packable.png differ diff --git a/docs/04-game-asset-structure/img/result-console.png b/docs/04-game-asset-structure/img/result-console.png new file mode 100644 index 0000000..53a3fd2 Binary files /dev/null and b/docs/04-game-asset-structure/img/result-console.png differ diff --git a/docs/04-game-asset-structure/img/sound-main-game.png b/docs/04-game-asset-structure/img/sound-main-game.png new file mode 100644 index 0000000..3e83ce3 Binary files /dev/null and b/docs/04-game-asset-structure/img/sound-main-game.png differ diff --git a/package-lock.json b/package-lock.json index 51f703c..2a25849 100644 --- a/package-lock.json +++ b/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",