Asset Pruning

The asset pruning system removes unused assets from your packaged game to reduce file size and improve load times.

Overview

Asset pruning is an optional feature of the packaging script that scans your game data and code to identify which assets are actually referenced, then removes everything else from the final package.

Enable it with the -PurgeAssets flag:

./build-package.ps1 -Target windows -PurgeAssets

How It Works

The pruning system scans multiple sources to build a comprehensive list of used assets:

1. RPG Maker Data Files

• All .json files in data/ are scanned for string references

• Every string value in the JSON is added to the "used strings" set

• This catches references to images, audio, effects, etc.

2. React Build Files

• All .js, .css, and .json files in menus/build/ and js/ are scanned

• Regex patterns match asset paths like img/, audio/, movies/, effects/, fonts/

• Both full paths and filenames are captured

3. System Assets

• Scans for loadSystem() calls in code to preserve Window.png, IconSet.png, etc.

• Example: loadSystem("Window") → preserves img/system/Window.png

4. Battleback Detection

Special logic for battlebacks since they can be referenced in multiple ways:

System-level defaults:

• Reads data/System.json → battleback1Name and battleback2Name

Map-specific battlebacks:

• Scans all data/Map*.json files for battleback1Name and battleback2Name

• Preserves battlebacks set on individual maps

Engine terrain defaults: The engine has hardcoded terrain-to-battleback mappings. The pruning system preserves these common defaults:

• Grassland, Forest, Cliff, Wasteland, DirtField, Desert, Snowfield, Clouds, PoisonSwamp

• Castle1-3, DemonCastle1-3

• Ship, GrassMaze

• Cobblestones1-5

• Crystal, IceCave, Lava1-2, RockCave

5. Effekseer Effects

• Reads data/Animations.json for effectName references

• Preserves .efkefc files and their associated textures/models

• Effect textures and models are safelisted (never removed)

Safelist Rules

Certain assets are automatically preserved even if not explicitly referenced:

• effects/Texture/* - All effect textures

• .efkmodel, .efkmat, .efktex files - Effect model/material files

Output

After pruning completes, two files are generated in the output directory:

asset-manifest.txt

A tab-separated list of all kept assets with their reference sources:

img/battlebacks1/Grassland.png    data/System.json; data/Map001.json
img/characters/Actor1.png         data/Actors.json
audio/bgm/Theme1.ogg             data/System.json; data/Map003.json

asset-mapping.json

A detailed JSON mapping for programmatic analysis:

{
  "img/battlebacks1/Grassland.png": [
    "data/System.json",
    "data/Map001.json"
  ],
  "img/characters/Actor1.png": [
    "data/Actors.json"
  ]
}

Verification

After running with -PurgeAssets:

1. Check the console output:

   [pack] Purged unused assets: 47
   [pack] Wrote asset manifest: C:\...\dist\package\asset-manifest.txt

2. Review asset-manifest.txt to verify important assets were kept

3. Test your packaged game thoroughly, especially:

   • All maps (for battlebacks)

   • All battles (for enemy/actor graphics, battlebacks)

   • All menus (for iconsets, windowskins)

   • Special effects (Effekseer animations)

Common Issues

Asset was incorrectly removed

Cause: The asset isn't referenced in a way the scanner detects.

Solutions:

1. Add an explicit reference in code:

   // In an override or custom file:
   ImageManager.loadBitmap("img/pictures/", "MyCustomImage");

2. Reference it in a data file (create a dummy map note, event comment, etc.)

3. Modify the safelist in build-package.ps1 to preserve specific patterns

Battleback missing in battle

Cause: Battleback referenced indirectly through terrain or plugin commands.

Solution:

• Check data/System.json and your map files have correct battleback1Name/battleback2Name

• If using dynamic battleback changes (plugin commands), ensure the script runs before pruning

• Add battleback names to the engine defaults list in build-package.ps1 if needed

Performance impact

Q: Does pruning slow down the build?

A: Yes, slightly. Pruning adds 5-15 seconds to scan all files and check assets. Skip -PurgeAssets during development; use it only for final release builds.

Statistics

Typical savings with -PurgeAssets on a default RMMZ project:

• Without pruning: ~500MB (includes all default assets)

• With pruning: ~150-250MB (depends on what you actually use)

• Reduction: 50-70% smaller package size

Actual savings vary based on:

• How much default content you removed from your project

• How many custom assets you added

• Whether you use many sound effects, music tracks, or large images

Best Practices

1. Always test the pruned build thoroughly before distributing

2. Keep the asset-manifest.txt for debugging if players report missing graphics

3. Use pruning only for release builds, not development

4. Run without -PurgeAssets first to verify packaging works

5. Review the "Purged unused assets" count - if it's 0, your game might reference everything (unlikely)

Technical Details

Matching Logic

Assets are kept if ANY of these match:

• Full relative path matches (e.g., img/battlebacks1/Grassland.png)

• Filename matches (e.g., Grassland.png)

• Basename matches (e.g., Grassland)

This multi-level matching ensures assets are preserved even if referenced inconsistently in your data.

Special File Handling

Tileset metadata:

• .tilesetmeta.json files are kept if their paired tileset image is referenced

Engine requirements:

• Core system files are never removed even if not explicitly found

See Also

• Packaging Guide - Main packaging documentation

• Production Checklist - Pre-release testing