doc-slot-core-manual/docs/04-game-asset-structure/01-default-assets-structure.md

---
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)

---