Packaging (build-package.ps1)

Packaging (build-package.ps1)

build-package.ps1 creates a clean, deployment‑ready bundle of your MZ project with the RPGReact plugin and React UI.

Basics

• Run from the project root.

• Platforms: web, windows, mac.

• Desktop targets include the NW.js runtime when a runtime path can be resolved (see below). Web target does not include a runtime.

Usage

# Show help
./build-package.ps1 -Help

# Web (HTML5)
./build-package.ps1 -Target web

# Windows (runnable; bundles NW.js runtime)
./build-package.ps1 -Target windows -OutDir dist\package-windows

# macOS (runnable; copies .app bundle if available)
./build-package.ps1 -Target mac -OutDir dist\package-mac

Runtime source (desktop)

• The script finds the NW.js runtime in this order:

  1. -RuntimePath parameter

  2. runtimePath in deploy.config.json

  3. Environment variable RMMZ_RUNTIME_PATH

  4. Auto‑discovery: scans the parent directory for Game.exe (Windows) or a .app bundle (macOS)

• If not found for desktop targets, the script fails fast with a clear error.

Config file deploy.config.json includes:

{
  "packageName": "RPGReactGame",
  "runtimePath": "C:\\path\\to\\RMMZ\\export\\ReactMZ",
  "include": [ "index.html", "version.json", "game.rmmzproject", "js", "data", "audio", "img", "fonts", "icon", "movies", "css", "effects", "lib", "menus/build", "menus/shared/types.js", "js/plugins/RPGReact.js" ],
  "exclude": [ "**/*.map", "logs/**", "console.log", "menus/src/**", "menus/node_modules/**", "menus/.vite/**", "**/.DS_Store", "**/Thumbs.db", ".git/**", "**/.gitignore", "agents/**", "workflows/**", "mapgen/**", "mapgen_v1/**", "js/plugins/DevToolsManage.js" ]
}

Important validations

• Ensures index.html, js/, data/, js/plugins/RPGReact.js, menus/build/ exist

• For desktop: ensures package.json exists

• Parses package.json and verifies main points to an existing file (prevents no‑window boot)

Options

• -OutDir (default dist\package) — Output folder

• -ConfigPath (default deploy.config.json) — Include/exclude rules and runtimePath

• -RuntimePath — Path to a desktop runtime (folder containing Game.exe on Windows, or a .app on macOS)

• -PurgeAssets — Remove unused assets from the OUTPUT package by scanning RPG data and React build files (JS/CSS). See Asset Pruning below for details.

Overrides bundling and minification (plugin JS)

• Single source of truth: js/plugins/rpgreact/overrides.manifest.json defines the exact files and order.

• The script concatenates and prepares each listed file, then minifies to:

  • js/plugins/rpgreact/RPGReact.overrides.min.js

• All unminified override sources (including custom/) are removed from the output.

• The main plugin js/plugins/RPGReact.js is minified in place.

• The script fails fast if:

  • The overrides manifest is missing or invalid,

  • A listed file is missing/unreadable,

  • esbuild is not found or minification fails.

Asset Pruning The -PurgeAssets flag removes unused assets from your production build to reduce package size. This is especially important for games using only a subset of the default RMMZ assets.

How it works:

1. Scans all data files (Actors.json, Items.json, Maps.json, System.json, etc.) for asset references

2. Scans React build files (JS/CSS) for dynamic imports and asset paths

3. Includes engine default battlebacks to prevent runtime errors

4. Removes any assets not found in the scan results

Usage:

# Build without pruning (safe for testing)
./build-package.ps1 -Target windows

# Build with asset pruning (production)
./build-package.ps1 -Target windows -PurgeAssets

Output files:

• asset-manifest.txt — List of all kept assets with reasons

• asset-mapping.json — Structured data for debugging

Important notes:

• Always test without -PurgeAssets first to ensure the build works

• Review asset-manifest.txt to verify critical assets weren't removed

• Battlebacks are protected by scanning System.json, all Map files, and including engine defaults

• Assets referenced via plugin commands may not be detected automatically

See Asset Pruning Guide for detailed information on how scanning works, troubleshooting missing assets, and customization.

Typical flow

1. In menus/: yarn install && yarn release (use yarn build for development testing)

2. Ensure your overrides manifest is correct: js/plugins/rpgreact/overrides.manifest.json

3. Project root: ./build-package.ps1 -Target windows

4. Test the build thoroughly in dist\package

5. If testing succeeds, rebuild with -PurgeAssets for production

6. Run from dist\package (or your -OutDir): Game.exe

Important: Always use yarn release for production builds to enable optimizations. Use yarn build only for development testing.

See Also

• Asset Pruning Guide — Comprehensive asset pruning documentation

• Production Checklist — Pre-release testing checklist

• Debugging Guide — Troubleshooting build issues