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

sidebar_position

sidebar_position
1

Default Asset Structure

---

Overview

	Core Asset	Game Asset
	- Contains all the necessary game modules. - Reviewing the Add submodules for details.	- Contains all the necessary game assets. - Reviewing the 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 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.

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:

  

  // 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:

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:

Prefabs

Desktop Prefab	Mobile Prefab

Asset Features Manager

Main Game Asset

Overview

Main game assets are stored in the main-game folder, organized by platform and loading type:

    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

Desktop Structure	Mobile Structure

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

    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

---

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:

    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.

---

Meta JSON Merger

Purpose

Merges JSON metadata files under library/imports/ into one fullMetaData.json.

Excludes:

• cc.SceneAsset
• cc.Prefab

{
  "asset1.json": { /* metadata */ },
  "asset2.json": { /* metadata */ }
}

---

Texture Compression Tool

Purpose

Manages and applies compression settings to game textures.

Compression Settings

Description	Action Compress Texture
Compresses all textures in: - assets/Core - assets/game
Compresses all textures in: - assets/game only
Removes all compression settings

Example:
Compression settings for PNG and JPG formats:

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.

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:

---

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.