Which route fits an RPG Maker MZ game?

A plugin. MZ has no analytics feature and no HTTP call for your own data; its core scripts use XMLHttpRequest only to load data files. A plugin is a JavaScript file in js/plugins/ that you turn on in the Plugin Manager.

The desktop build runs in NW.js, which gives the page Node.js modules. The plugin uses the Node https module there, because a Node request sends no Origin header and the collector accepts it as a native build. The web build uses the browser fetch().

Sources: RPG Maker MZ help, Output Formats and Enabling Plugins; Node.js documentation, https.request(); Manalens app events documentation.

What must every RPG Maker MZ event contain?

One JSON envelope, the same one the Godot and Unity SDKs send. POST it to /v0/events on your collector with two headers: x-publishable-key and Content-Type: application/json. The body is {"events": [...]} with 1 to 50 events. A good request returns {"accepted":N}.

  • type "track", an event name in snake_case, channel "app" and version (your tracker version, up to 32 characters).
  • message_id: a new UUID version 4 for each event. Keep it on a retry. The collector counts each message_id once.
  • anonymous_id: one UUID version 4 per install, saved on the device. The collector checks the version digit, so a random hex string of the same length is refused.
  • session_id: 1 to 64 characters of letters, digits and . _ : -. Start a new one after 30 minutes without play.
  • original_timestamp: the time of the event in ISO 8601 UTC, such as 2026-11-09T10:00:00Z. It can be up to 7 days old, and at most 10 minutes in the future.
  • context.app.platform (windows, macos, linux, web, android, ios or other) and engine "other". Add storefront, app_version and build to filter reports by build.
  • properties: a flat object of strings, numbers, booleans or null.

Sources: Manalens app events documentation.

How do I send events from RPG Maker MZ?

Save this file as js/plugins/Manalens_Analytics.js and turn it on in the Plugin Manager. The header comment uses the MZ annotations: @target MZ, @plugindesc, @param, @command and @arg. The plugin keeps its state in one save object, mana_state, written with StorageManager.saveObject().

StorageManager is part of the MZ core scripts (js/rmmz_managers.js in your project), not a documented public API. saveObject() and loadObject() return Promises. Check the file in your own MZ version if a call fails.

JavaScript (js/plugins/Manalens_Analytics.js)

/*:
 * @target MZ
 * @plugindesc Sends game events to Manalens.
 * @param endpoint
 * @default https://YOUR_COLLECTOR_ENDPOINT/v0/events
 * @param key
 * @default YOUR_PUBLISHABLE_KEY
 * @command consent
 * @text Set analytics consent
 * @arg value
 * @type boolean
 * @default true
 * @command track
 * @text Track event
 * @arg event
 * @type string
 */
(() => {
  const NAME = 'Manalens_Analytics', FILE = 'mana_state', WEEK_MS = 7 * 24 * 3600 * 1000;
  const P = PluginManager.parameters(NAME);
  let st = { consent: false, anonId: null, firstOpenAt: null, queue: [] };
  let backoff = 2000, retryAt = 0, sending = false, booted = false;
  const uuid4 = () => {
    const b = crypto.getRandomValues(new Uint8Array(16));
    b[6] = (b[6] & 0x0f) | 0x40; b[8] = (b[8] & 0x3f) | 0x80;
    const h = Array.from(b, x => x.toString(16).padStart(2, '0')).join('');
    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
  };
  const session = uuid4();
  const platform = () => !Utils.isNwjs() ? 'web'
    : ({ win32: 'windows', darwin: 'macos', linux: 'linux' })[process.platform] || 'other';
  const persist = () => { if (booted) StorageManager.saveObject(FILE, st).catch(() => 0); };
  const headers = { 'Content-Type': 'application/json', 'x-publishable-key': P.key };

  function post(body, done) {
    if (Utils.isNwjs()) {
      const req = require('https').request(P.endpoint, { method: 'POST', headers }, res => { res.resume(); done(res.statusCode); });
      req.on('error', () => done(0));
      req.end(body);
    } else {
      fetch(P.endpoint, { method: 'POST', headers, body }).then(r => done(r.status), () => done(0));
    }
  }
  function flush() {
    if (!st.consent || sending || Date.now() < retryAt) return;
    st.queue = st.queue.filter(e => Date.now() - Date.parse(e.original_timestamp) < WEEK_MS);
    const batch = st.queue.slice(0, 50);
    if (!batch.length) return;
    sending = true;
    post(JSON.stringify({ events: batch }), code => {
      sending = false;
      if (code === 0 || code >= 500 || code === 408 || code === 429) {
        retryAt = Date.now() + backoff; backoff = Math.min(backoff * 2, 300000); return;
      }
      st.queue.splice(0, batch.length); backoff = 2000; persist(); flush();
    });
  }
  function track(event, properties = {}) {
    if (!st.consent || !booted) return;
    if (!st.anonId) st.anonId = uuid4();
    st.queue.push({ type: 'track', event, channel: 'app', version: '0.1.0',
      message_id: uuid4(), anonymous_id: st.anonId, session_id: session,
      original_timestamp: new Date().toISOString(),
      context: { app: { platform: platform(), storefront: 'steam', app_version: '1.4.0', build: '571', engine: 'other' },
        locale: navigator.language || 'en', library_name: 'my-game', library_version: '1.4.0' },
      properties });
    st.queue = st.queue.slice(-500);
    persist();
  }
  function startSession() {
    const first = !st.firstOpenAt;
    if (first) st.firstOpenAt = new Date().toISOString();
    track('game_open', { is_first_open: first, first_open_at: st.firstOpenAt });
    track('session_start');
    flush();
  }
  function setConsent(on) {
    st.consent = on;
    if (!on) { st.anonId = null; st.queue = []; }
    persist();
    if (on) startSession();
  }
  PluginManager.registerCommand(NAME, 'consent', a => setConsent(a.value === 'true'));
  PluginManager.registerCommand(NAME, 'track', a => { track(a.event); flush(); });

  const _start = Scene_Boot.prototype.start;
  Scene_Boot.prototype.start = function() {
    _start.call(this);
    StorageManager.loadObject(FILE).then(s => { if (s) st = s; }).catch(() => 0)
      .then(() => { booted = true; if (st.consent) startSession(); });
  };
  setInterval(flush, 15000);
  document.addEventListener('visibilitychange', () => { if (document.hidden) flush(); });
  window.Manalens = { track, flush, setConsent };
})();

Sources: RPG Maker MZ plugin course, annotations; RPG Maker MZ core scripts, rmmz_managers.js; Node.js documentation, https.request(); MDN, fetch().

How do I track events from my events and scripts?

Use the plugin commands in any event page: Set analytics consent from your title screen or options menu, and Track event for story beats. For events with properties, use a Script command and call window.Manalens.track().

Use the event conventions where they fit: level_start and level_complete for dungeons or chapters, resource for gold earned and spent, and purchase for real money. The Game KPIs board reads these names.

JavaScript (Script event command)

// Script event command (Event Commands, page 3, Script):
Manalens.track('level_complete', { level: 'forest_dungeon', attempt: 1, score: 1200 });
Manalens.track('resource', { flow: 'sink', currency: 'gold', amount: 250, item: 'potion' });
Manalens.flush();

// Title screen choice "Share anonymous play data?":
// Yes: Plugin Command, Manalens_Analytics, Set analytics consent, value = true
// No:  Plugin Command, Manalens_Analytics, Set analytics consent, value = false

Sources: RPG Maker MZ plugin course, annotations; Manalens app events documentation.

What changes for web, desktop and mobile builds?

The MZ help lists three output formats: Windows, macOS and web browsers. Android and iOS builds come from the web build and a third-party wrapper.

  • Windows and macOS (NW.js): the Node https request sends no Origin header, so no CORS rules apply. The save object is a file named mana_state.rmmzsave in the save folder next to the game.
  • Web: the browser sends an OPTIONS preflight because of the x-publishable-key header. The collector answers it for your project domain, its subdomains and Allowed origins. *.itch.zone is allowed by default, so itch.io HTML5 uploads work. MZ web play needs WebGL.
  • Web storage: StorageManager saves to localforage (IndexedDB) under a key that includes the game ID from the database. It is per browser and per site.
  • Mobile wrappers: the WebView page has its own origin. Find it in the wrapper docs and add it to Allowed origins. Use an https:// endpoint, because Android and iOS block cleartext HTTP by default.

Sources: RPG Maker MZ help, Output Formats; RPG Maker MZ core scripts, rmmz_managers.js; MDN, Preflight request; Manalens app events documentation.

What are the RPG Maker MZ gotchas?

These come from the MZ core scripts, so check js/rmmz_managers.js and js/rmmz_scenes.js in your own project version.

  • Do not call StorageManager from the top level of the plugin. On the web it builds the save key from the game ID in the database, which is not loaded yet. The plugin waits for Scene_Boot.prototype.start.
  • loadObject() behaves differently per build: on NW.js it rejects when there is no file, and on the web it resolves null. Always add .catch() and check for null.
  • PluginManager.parameters() looks up the plugin by its file name. If you rename Manalens_Analytics.js, change NAME in the code too, or every parameter comes back empty.
  • Plugin command arguments arrive as strings. A boolean @arg gives "true" or "false", which is why the code compares a.value === "true".
  • Save data is compressed and the core warns when one save passes 50,000 bytes. Keep the queue short; the plugin keeps at most 500 events.

Sources: RPG Maker MZ core scripts, rmmz_managers.js and rmmz_scenes.js; RPG Maker MZ plugin course, annotations.

How do I check that RPG Maker MZ events arrive?

Send one batch from a development build and read the response status. On the web, open the browser developer tools and check that the OPTIONS preflight succeeds. In NW.js, press F8 to open the developer tools and read the console.

  1. Create a test project in Manalens and copy its Publishable key.
  2. Run a desktop playtest (Game, Playtest) and a web deployment on a local server, with localhost in Allowed origins.
  3. Send game_open and session_start from the RPG Maker MZ build, then check that the response is {"accepted":2}.
  4. Open the activity feed and check that platform, build and engine are set on the events.
  5. Switch off the network, play for a minute, switch it on, and check that the queued events arrive once.
  6. Replace the test key with the production Publishable key before you ship.

Sources: Manalens app events documentation.

How do I start?

Manalens is the analytics and growth engine built for games. Drop the plugin into js/plugins, ask for consent on the title screen, and use the Game KPIs board to see where players stop in your story.

Sources: Manalens product documentation.

Frequently asked questions

Does RPG Maker MZ have built-in analytics?

No. MZ has no analytics feature and no HTTP call for your own data. Write a small plugin in js/plugins that posts events to /v0/events with your Publishable key. Use the Node https module in the NW.js desktop build and the browser fetch() in the web build.

Where does the plugin save the player ID?

In its own save object, mana_state, written with StorageManager.saveObject(). On Windows and macOS it is a file in the save folder next to the game. On the web it is in IndexedDB through localforage. It is separate from the save slots, so loading a save keeps the ID.

Why does the plugin use Node https on desktop?

Because a Node request sends no Origin header, so the collector treats it as a native build and accepts it with the Publishable key. The web build has to use fetch(), and the browser then sends a CORS preflight that the collector answers for allowed hosts such as *.itch.zone.

Can I send events from the event editor?

Yes. The plugin adds two plugin commands: Set analytics consent and Track event. For events with properties, add a Script command and call Manalens.track() with a name and a flat object, then Manalens.flush(). Use snake_case names such as level_complete so the Game KPIs board reads them.

Sources and implementation