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 7e70a43..28969b3 100644 --- a/docs/04-game-asset-structure/01-default-assets-structure.md +++ b/docs/04-game-asset-structure/01-default-assets-structure.md @@ -79,6 +79,178 @@ Refers to images, audio, and other data that are specifically designed or adjust ![Asset Platform Manager](./img/assets-platform-manager.png) -### Asset Feature Manager +#### 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 -#### Feature Game Asset \ No newline at end of file + +##### 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) | + +#### Localizes Asset + +`localizes/` là nơi lưu trữ assets của các ngôn ngữ khác nhau như : ZH, TH, ID..v.v + +```plaintext + assets/ + └── game-assets/ + ├── fonts/ + │ ├── localizes/ # Localized font files + │ └── preloads/ # Fonts loaded at startup + └── textures/ + ├── desktop/ + │ ├── localizes/ # Localized textures for desktop + │ ├── postloads/ # Desktop textures loaded after startup + │ └── preloads/ # Desktop textures loaded at startup + └── mobile/ + ├── localizes/ # Localized textures for mobile + ├── postloads/ # Mobile textures loaded after startup + └── preloads/ # Mobile textures loaded at startup +``` +sprite trong `preloads`, `postloads`: defaut là en + +![Location](./img/localizes-assets.png) + + 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-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/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/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/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