Unload

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#

Supported Categories#

The unload action supports the same categories as the Preload action:

Default Audio Categories#

• music - Background music tracks
• sounds or sound - Sound effects
• voices or voice - Voice clips

Default Image Categories#

• scenes or scene - Scene backgrounds
• images or image - General images
• characters - 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 memory

Full 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