@rutan/rpgmaker-vxace-web-player-template

Browser player template and RGSS3-compatible runtime for RPG Maker VX Ace Web.

Overview

This package contains the browser runtime used to run converted RPG Maker VX Ace games. It provides the HTML/Vite player template, the JavaScript bridge, and the RGSS3-compatible Ruby runtime layer built on ruby.wasm and PixiJS.

Most users do not use this package directly. The converter packages copy the built template into a browser-ready distribution:

• @rutan/rpgmaker-vxace-web-converter-cli
• @rutan/rpgmaker-vxace-web-converter-core

Use this package directly only when you need to locate the bundled player template or customize the player integration.

Installation

npm install @rutan/rpgmaker-vxace-web-player-template

Usage

Use With the Converter

The recommended path is to use the converter CLI:

vxace-web-convert ./my-vxace-game \
  --out ./dist/my-web-game \
  --game-id author-name:game-name

The converter copies this player template into the output directory and writes the converted game files under game/ by default.

Locate the Template Directory

Library integrations can use getPlayerTemplateDir() to locate the built template files.

import { getPlayerTemplateDir } from '@rutan/rpgmaker-vxace-web-player-template';

const templateDir = getPlayerTemplateDir();
console.log(templateDir);

converter-core uses the same template directory by default when convertToDistribution() is called without a custom templateDir.

Runtime Behavior

The built player loads game/manifest.json by default. The manifest describes the game id, title, screen size, virtual gamepad mode, resources, packs, and fonts.

At boot time, the runtime:

1. loads the game manifest
2. preloads manifest fonts
3. initializes the Ruby WASM runtime
4. installs RGSS3-compatible browser APIs
5. reads the script archive configured by Game.ini
6. evaluates the guest scripts generated by RPG Maker VX Ace

In development mode, the player also accepts ?game_dir=<name> for switching the game directory and ?guest=0 for loading only the runtime bootstrap.

Custom Save Storage

By default, save files are stored in IndexedDB. A deployment can provide a platform-specific save backend by defining window.RPGVXAceWeb.saveStorageAdapter before the player runtime starts.

<script src="./save-adapter.js"></script>
<script type="module" src="./assets/index.js"></script>

window.RPGVXAceWeb = window.RPGVXAceWeb || {};
window.RPGVXAceWeb.saveStorageAdapter = {
  async saveBinaryBase64(gameId, filename, base64) {
    await platform.storage.save(`${gameId}/${filename}`, base64);
  },

  async loadSavedBinaryBase64(gameId, filename) {
    return (await platform.storage.load(`${gameId}/${filename}`)) ?? null;
  },

  async getSavedDataInfo(gameId, filename) {
    const info = await platform.storage.info(`${gameId}/${filename}`);
    return info ? { filename, updatedAt: new Date(info.updatedAt).toISOString() } : null;
  },

  async listSavedData(gameId) {
    const prefix = `${gameId}/`;
    const files = await platform.storage.list(prefix);
    return files.map((file) => ({
      filename: file.name.slice(prefix.length),
      updatedAt: new Date(file.updatedAt).toISOString(),
    }));
  },

  async deleteSavedData(gameId, filename) {
    await platform.storage.delete(`${gameId}/${filename}`);
  },
};

The RGSS/Ruby side does not need to change. Calls such as save_data, load_data, File.open, Dir.glob, and File.mtime continue to use the runtime compatibility layer.

Development

pnpm install
pnpm --filter @rutan/rpgmaker-vxace-web-player-template run dev

The development server runs on http://localhost:8080.

Build the package and template:

pnpm --filter @rutan/rpgmaker-vxace-web-player-template run build

The Vite template build is written to dist/template.

Testing

# Unit tests
pnpm --filter @rutan/rpgmaker-vxace-web-player-template run test:unit

# Browser tests
pnpm --filter @rutan/rpgmaker-vxace-web-player-template run test:browser

See docs/browser-testing.md for browser testing details.

Current Status and Limitations

This runtime is under development and does not yet guarantee full compatibility with all RPG Maker VX Ace games.

• RTP (Run Time Package) is not supported. Games must include required RTP assets before conversion.
• MIDI and WMA playback are not supported. Convert those assets to browser-supported audio formats such as OGG before deployment.
• Movie playback, including VX Ace .ogv movie files, is not supported yet.
• The runtime uses Ruby 4.0 through ruby.wasm, while RGSS3 is based on Ruby 1.9.2. Some Ruby language and standard library compatibility differences may remain. Standard libraries available in RGSS3, such as dl, may not be available.

License

MIT License.

RPG Maker VX Ace, RTP assets, and converted game assets are subject to their own licenses and terms. Make sure you have the rights to distribute any game data and assets included in a web deployment.