Cocos Creator version: 3.7.2.
This issue was unusual because it never appeared in local or staging tests. It occurred only in production, where it could freeze the entire game.
Cause
The scene contained many character-cache atlases because several Label components used Cache Mode = CHAR. The generated texture atlas became larger than WebGL’s maximum supported texture size, causing rendering failures or crashes.
Confirm the diagnosis
Preview the game in a browser and inspect the console for a warning such as:
1 | [Warning] Font atlas texture size exceed MAX_TEXTURE_SIZE |
Solutions
- Limit the cached atlas size. This is a commonly suggested approach, although I have not tested its exact configuration.
- Set Label Cache Mode to
NONE. This avoids the oversized atlas but may reduce performance because system-font text must be redrawn frequently. - Use a Bitmap Font. For relatively static text, BMFont gives predictable atlas sizes, efficient rendering, and avoids uncontrolled cache growth.
- Optimize dynamic atlas management. Do not merge every label and icon into one atlas. Split content across smaller atlases and limit both tile size and atlas count.
| Scenario | Recommended approach |
|---|---|
| Large amounts of dynamic multilingual text | Cache Mode = NONE |
| Mostly fixed UI with little dynamic text | Bitmap Font |
| Moderate text with controlled atlas limits | Cache Mode = CHAR with size limits |
| Complex scenes with many dynamic nodes | Dynamic-atlas optimization |
