Description
'unload <type> [asset] [permanent]'
'unload character <id> [sprite] [permanent]'
'unload block <block_id> [permanent]'
'unload all [permanent]'The unload action allows you to release assets from memory when they are no longer needed. This is crucial for managing memory usage in long games or games with many high-resolution assets.
Action ID: Unload
Reversible: No (Reverting does nothing)
Requires User Interaction: No
Parameters
| Parameter | Description |
|---|---|
type |
The category of the asset (see Supported Categories below). |
asset |
(Optional) The specific asset to unload. If omitted, all assets of the specified type will be unloaded. |
id |
When unloading a character, the character’s ID. |
sprite |
(Optional) When unloading a character, the specific sprite to unload. If omitted, all sprites for the character are unloaded. |
block_id |
When using unload block, the ID of the preload block to unload. |
all |
Special keyword to unload ALL cached assets. |
permanent |
(Optional) If included, audio assets will also be removed from persistent storage (IndexedDB). |
Supported Categories
The unload action supports the same categories as the Preload action:
Default Audio Categories
music- Background music trackssoundsorsound- Sound effectsvoicesorvoice- Voice clips
Default Image Categories
scenesorscene- Scene backgroundsimagesorimage- General imagescharacters- Character sprites (uses special syntax, see examples)
Note: Singular forms (sound, voice, scene, image) are aliases for their plural counterparts.
Examples
Unload a specific song
'unload music theme_song'Unload all scenes
'unload scenes'Unload a specific character sprite
'unload character y happy'Unload all sprites for a character
'unload character y'Unload a block of assets
'unload block Chapter1'Unload everything (e.g., at end of chapter)
'unload all'The permanent Flag
By default, unload only removes assets from the in-memory cache. For audio assets, the decoded audio buffers are also stored in IndexedDB for faster loading in future sessions.
Adding the permanent flag will also remove audio assets from IndexedDB:
// Only removes from memory cache (will reload faster next time from IndexedDB)
'unload music theme_song'
// Removes from both memory AND IndexedDB (will need to re-download and decode)
'unload music theme_song permanent'
// Clear all audio from persistent storage
'unload all permanent'This is useful when:
- The player has completed a section and won’t return
- You want to free up storage space
- You’re updating assets and need to force a fresh download
Memory Management Best Practices
Chapter-based Unloading
For games with distinct chapters or scenes, use preload blocks and unload them when no longer needed:
monogatari.action('Preload').blocks({
'Chapter1': {
music: ['intro_theme', 'peaceful'],
scenes: ['hometown', 'school']
},
'Chapter2': {
music: ['dramatic', 'battle'],
scenes: ['castle', 'dungeon']
}
});
// In your script
monogatari.script({
'Chapter1End': [
'The hero leaves their hometown...',
'unload block Chapter1',
'preload block Chapter2 blocking',
'jump Chapter2Start'
]
});Unloading Unused Characters
When characters leave the story permanently:
'y:happy The adventure continues without me. Goodbye!',
'hide character y',
'unload character y' // Frees all y's sprites from memoryFull Memory Clear
At major story transitions:
'unload all',
'preload block NewArc blocking',
'show scene new_beginning'Related Actions
- Preload - Load assets into memory before they’re needed