How m5kro/rpg-maker-macos-launcher works
1. This repo is a macOS desktop launcher for RPG Maker games, written in Python and packaged with PyInstaller. Its job is not to run games itself, but to detect what kind of RPG Maker game a folder contains and then hand it off to the correct native runtime.
2. The main application logic lives in main.py. That file is the orchestration layer: it presents the launcher UI, accepts a game directory, inspects the game’s metadata, and then decides which execution path to take.
3. Game-type detection is file-driven. The README says the launcher checks for package.json, Game.ini, and RTP_RT, which are the key markers for the supported RPG Maker families. That detection step is the central branching point in the architecture.
4. The launcher then routes to one of three runtime families:
- nwjs for RPG Maker MV/MZ-style games,
- mkxp-z for XP/VX/VX Ace-style games,
- EasyRPG for RPG Maker 2000/2003 games.
These are external engines, not Python modules, so the app acts as a native coordinator around separate executables.
5. There is a runtime acquisition/update flow as well. The README states the launcher downloads NW.js, mkxp-z, and EasyRPG, so the app depends on network access to fetch engine binaries before launching a game. That makes “runtime management” a distinct subsystem from “game launch” itself.
6. evbunpack is used to unpack game_en.exe when present. That means the launcher also has a small extraction/deobfuscation step for certain Windows-distributed RPG Maker games before handing the folder to the engine.
7. The JavaScript files (bg.js, disable-child.js, disable-net.js, Cheat_Menu.js) and Cheat_Menu.css are engine-side patches/customizations, most likely for the NW.js-based path. They appear to modify the game runtime behavior and UI: disabling child windows, disabling network access, and injecting a cheat menu overlay.
8. EasyRPG-Standalone is a bundled runtime directory, likely containing the assets or app wrapper needed to ship EasyRPG as a self-contained macOS experience. This suggests the repo includes both launcher code and some prebuilt runtime packaging material.
9. The .spec files define separate PyInstaller build targets for x64, arm64, and Universal2 macOS binaries. Architecture-wise, that means the project is designed to ship as a native Mac app with different output builds depending on CPU architecture.
10. The project boundaries are clean: the Python launcher owns detection, downloading, extraction, and process launch; the external engines own actual game execution; and the JS/CSS files only affect the NW.js game-runtime layer. That separation is the key thing to capture in an architecture diagram.
Main entry points: main.py Main app · Cheat_Menu.js Cheat menu JS · EasyRPG-Standalone Standalone bundle · bg.js Background script
Components 17
Launcher app
Python orchestration, detection, and process launch
- Main app · UI and orchestration entrypoint
main.py - Detect game · Inspects game folder markers to classify RPG Maker family
- Unpack EXE · Extracts game_en.exe when needed
- Fetch runtimes · Downloads engine binaries before launch
- Launch game · Hands the selected folder off to the chosen runtime
Runtime layer
External engines and bundled runtime assets
- NW.js · Native engine path for RPG Maker MV/MZ games
- mkxp-z · Native engine path for RPG Maker XP/VX/VX Ace games
- EasyRPG · Native engine path for RPG Maker 2000/2003 games
- Standalone bundle · Bundled EasyRPG runtime assets for self-contained macOS delivery
EasyRPG-Standalone
NW.js patches
Injected scripts and UI customizations for NW.js-based games
- Background script · Runtime-side behavior tweak for NW.js games
bg.js - Block child windows · Prevents child-window behavior in the game runtime
disable-child.js - Block network · Disables network access in the game runtime
disable-net.js - Cheat menu JS · Injects a cheat menu overlay or UI hook
Cheat_Menu.js - Cheat menu CSS · Styles the cheat menu overlay
Cheat_Menu.css
Build outputs
PyInstaller targets for macOS architectures
- x64 spec · Build recipe for Intel macOS
RPG-Maker-Launcher-x64.spec - arm64 spec · Build recipe for Apple Silicon macOS
RPG-Maker-Launcher-arm64.spec - Universal2 spec · Build recipe for universal macOS binary
RPG-Maker-Launcher-Universal2.spec
Connections 22
- Main app → Detect game: classifies · Reads folder markers and chooses a runtime family
- Main app → Unpack EXE: prepares · Optionally unpacks Windows-distributed game executables
- Main app → Fetch runtimes: ensures · Acquires runtime binaries before launching
- Detect game → NW.js: routes to · MV/MZ-style game folders go to NW.js
- Detect game → mkxp-z: routes to · XP/VX/VX Ace-style game folders go to mkxp-z
- Detect game → EasyRPG: routes to · 2000/2003-style game folders go to EasyRPG
- Main app → Launch game: starts · Launches the chosen engine with the selected game folder
- Launch game → NW.js: executes · Uses the NW.js runtime for MV/MZ games
- Launch game → mkxp-z: executes · Uses mkxp-z for XP/VX/VX Ace games
- Launch game → EasyRPG: executes · Uses EasyRPG for 2000/2003 games
- Fetch runtimes → NW.js: fetches · Downloads NW.js binaries
- Fetch runtimes → mkxp-z: fetches · Downloads mkxp-z binaries
- Fetch runtimes → EasyRPG: fetches · Downloads EasyRPG binaries
- Standalone bundle → EasyRPG: packages · Provides the bundled standalone runtime assets
- Background script → NW.js: patches · Injects runtime behavior changes into NW.js games
- Block child windows → NW.js: patches · Disables child-window behavior in NW.js games
- Block network → NW.js: patches · Disables network access in NW.js games
- Cheat menu JS → NW.js: extends · Adds cheat menu behavior to the NW.js layer
- Cheat menu CSS → Cheat menu JS: styles · Provides presentation for the cheat menu overlay
- x64 spec → Main app: builds · Produces the Intel macOS launcher app
- arm64 spec → Main app: builds · Produces the Apple Silicon macOS launcher app
- Universal2 spec → Main app: builds · Produces the universal macOS launcher app