# m5kro/rpg-maker-macos-launcher architecture

> Architecture diagram of the GitHub repository m5kro/rpg-maker-macos-launcher, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/m5kro/rpg-maker-macos-launcher
- Repository: https://github.com/m5kro/rpg-maker-macos-launcher

## Overview

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`](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/main.py) (Main app), [`Cheat_Menu.js`](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/Cheat_Menu.js) (Cheat menu JS), [`EasyRPG-Standalone`](https://github.com/m5kro/rpg-maker-macos-launcher/tree/main/EasyRPG-Standalone) (Standalone bundle), [`bg.js`](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/bg.js) (Background script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launcher["Launcher app"]
  node_main["Main app<br/>Python launcher<br/>[main.py]"]
  node_detect["Detect game<br/>file-based routing"]
  node_extract["Unpack EXE<br/>evbunpack step"]
  node_download["Fetch runtimes<br/>runtime manager"]
  node_launch["Launch game<br/>process coordinator"]
end

subgraph group_runtime["Runtime layer"]
  node_nwjs[("NW.js<br/>MV/MZ runtime")]
  node_mkxpz[("mkxp-z<br/>XP/VX runtime")]
  node_easyrpg[("EasyRPG<br/>2000/2003 runtime")]
  node_easyrpg_bundle["Standalone bundle<br/>packaged runtime"]
end

subgraph group_patches["NW.js patches"]
  node_bgjs["Background script<br/>NW.js patch<br/>[bg.js]"]
  node_disable_child["Block child windows<br/>NW.js patch<br/>[disable-child.js]"]
  node_disable_net["Block network<br/>NW.js patch<br/>[disable-net.js]"]
  node_cheat_js["Cheat menu JS<br/>NW.js UI patch<br/>[Cheat_Menu.js]"]
  node_cheat_css["Cheat menu CSS<br/>NW.js style patch<br/>[Cheat_Menu.css]"]
end

subgraph group_build["Build outputs"]
  node_spec_x64["x64 spec<br/>PyInstaller target"]
  node_spec_arm64["arm64 spec<br/>PyInstaller target"]
  node_spec_universal2["Universal2 spec<br/>PyInstaller target"]
end

node_main -->|"classifies"| node_detect
node_main -->|"prepares"| node_extract
node_main -->|"ensures"| node_download
node_detect -->|"routes to"| node_nwjs
node_detect -->|"routes to"| node_mkxpz
node_detect -->|"routes to"| node_easyrpg
node_main -->|"starts"| node_launch
node_launch -->|"executes"| node_nwjs
node_launch -->|"executes"| node_mkxpz
node_launch -->|"executes"| node_easyrpg
node_download -->|"fetches"| node_nwjs
node_download -->|"fetches"| node_mkxpz
node_download -->|"fetches"| node_easyrpg
node_easyrpg_bundle -->|"packages"| node_easyrpg
node_bgjs -->|"patches"| node_nwjs
node_disable_child -->|"patches"| node_nwjs
node_disable_net -->|"patches"| node_nwjs
node_cheat_js -->|"extends"| node_nwjs
node_cheat_css -->|"styles"| node_cheat_js
node_spec_x64 -->|"builds"| node_main
node_spec_arm64 -->|"builds"| node_main
node_spec_universal2 -->|"builds"| node_main

click node_main "https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/main.py"
click node_easyrpg_bundle "https://github.com/m5kro/rpg-maker-macos-launcher/tree/main/EasyRPG-Standalone"
click node_bgjs "https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/bg.js"
click node_disable_child "https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/disable-child.js"
click node_disable_net "https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/disable-net.js"
click node_cheat_js "https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/Cheat_Menu.js"
click node_cheat_css "https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/Cheat_Menu.css"
click node_spec_x64 "https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/RPG-Maker-Launcher-x64.spec"
click node_spec_arm64 "https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/RPG-Maker-Launcher-arm64.spec"
click node_spec_universal2 "https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/RPG-Maker-Launcher-Universal2.spec"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_detect,node_extract,node_download,node_launch toneBlue
class node_nwjs,node_mkxpz,node_easyrpg,node_easyrpg_bundle toneAmber
class node_bgjs,node_disable_child,node_disable_net,node_cheat_js,node_cheat_css toneMint
class node_spec_x64,node_spec_arm64,node_spec_universal2 toneRose
```

## Components

### Launcher app

Python orchestration, detection, and process launch

- [Main app](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/main.py): Python launcher · UI and orchestration entrypoint · `main.py`
- **Detect game**: file-based routing · Inspects game folder markers to classify RPG Maker family
- **Unpack EXE**: evbunpack step · Extracts game_en.exe when needed
- **Fetch runtimes**: runtime manager · Downloads engine binaries before launch
- **Launch game**: process coordinator · Hands the selected folder off to the chosen runtime

### Runtime layer

External engines and bundled runtime assets

- **NW.js**: MV/MZ runtime · Native engine path for RPG Maker MV/MZ games
- **mkxp-z**: XP/VX runtime · Native engine path for RPG Maker XP/VX/VX Ace games
- **EasyRPG**: 2000/2003 runtime · Native engine path for RPG Maker 2000/2003 games
- [Standalone bundle](https://github.com/m5kro/rpg-maker-macos-launcher/tree/main/EasyRPG-Standalone): packaged runtime · 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](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/bg.js): NW.js patch · Runtime-side behavior tweak for NW.js games · `bg.js`
- [Block child windows](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/disable-child.js): NW.js patch · Prevents child-window behavior in the game runtime · `disable-child.js`
- [Block network](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/disable-net.js): NW.js patch · Disables network access in the game runtime · `disable-net.js`
- [Cheat menu JS](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/Cheat_Menu.js): NW.js UI patch · Injects a cheat menu overlay or UI hook · `Cheat_Menu.js`
- [Cheat menu CSS](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/Cheat_Menu.css): NW.js style patch · Styles the cheat menu overlay · `Cheat_Menu.css`

### Build outputs

PyInstaller targets for macOS architectures

- [x64 spec](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/RPG-Maker-Launcher-x64.spec): PyInstaller target · Build recipe for Intel macOS · `RPG-Maker-Launcher-x64.spec`
- [arm64 spec](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/RPG-Maker-Launcher-arm64.spec): PyInstaller target · Build recipe for Apple Silicon macOS · `RPG-Maker-Launcher-arm64.spec`
- [Universal2 spec](https://github.com/m5kro/rpg-maker-macos-launcher/blob/main/RPG-Maker-Launcher-Universal2.spec): PyInstaller target · Build recipe for universal macOS binary · `RPG-Maker-Launcher-Universal2.spec`

## Connections

- 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
