Connect your RPG Maker MZ game to the rpg.actor character registry. Players log in with their AT Protocol handle and play as their own character, with stats and sprites pulled from their personal data server.
Setup
- Extract the zip into your project's
js/plugins/folder. You should see sixRPGACTOR_*.jsfiles. - Open the Plugin Manager in RPG Maker MZ and add each plugin in the order listed below.
- Configure the plugins to match your project's needs.
- Playtest as a desktop build (NW.js). The login overlay should appear on new game.
OAuth needs the NW.js desktop runtime for the localhost callback server.
Plugin Load Order
Add these in the Plugin Manager in this exact order. Core and Login are required; the rest are optional.
| Plugin | Purpose | |
|---|---|---|
RPGACTOR_Core | Required | AT Protocol core: auth, XRPC, identity, party, game variables |
RPGACTOR_Login | Required | OAuth login overlay with profile preview, session reauth |
RPGACTOR_NPC | Optional | Registry NPCs: spawning, wanderers, pinned characters, dialogue |
RPGACTOR_Posts | Optional | Post viewer, compose window, social escape codes |
RPGACTOR_Sprites | Optional | Sprite pipeline: PDS records, character selector, face generation |
RPGACTOR_Stats | Optional | Stat sync: read and write player stats across games |
Core must always be first. Login goes immediately after Core. The optional plugins can follow in any order, but NPC depends on Sprites and Stats at runtime for full functionality.
What You Get
Player Login
Players enter their Bluesky handle, authorize via OAuth in their browser, and their character loads into your game with stats, sprite, and avatar face graphic.
Persistent Stats
Level, HP, class, and core parameters sync to the player's own AT Protocol repository. Progress carries between games.
Living NPCs
Populate your world with real rpg.actor users. Wandering NPCs spawn by region, pinned NPCs attach to map events by DID, and every NPC carries their real profile and sprite.
Custom Sprites
Player sprites load from their PDS as standard RMMZ character sheets (144×192 PNG). Avatars convert into face graphics for dialogue.
Plugin Parameters
Each plugin is configured through the RPG Maker MZ Plugin Manager. Expand a plugin below to see its settings. For full technical details, see the Developer Guide.
RPGACTOR_Core
| Parameter | Default | Description |
|---|---|---|
mainActorId | 1 | Which database actor represents the player character |
startVariableId | 1 | First of 20 consecutive game variables filled with player profile data (handle, DID, follower count, etc.) |
staticActorCount | 4 | Actor IDs above this number are reserved for dynamic party members (NPC joins) |
RPGACTOR_Login
| Parameter | Default | Description |
|---|---|---|
showOnNewGame | true | Show the login overlay automatically on new game |
reauthOnLoad | true | Prompt re-login when the session has expired on save load |
allowLoginSkip | false | Let players skip login entirely (not just go offline) |
clientId | http://localhost | OAuth client identifier (loopback for desktop, hosted URL for web) |
continueCommonEvent | 0 | Common event to run after successful login (0 = none) |
RPGACTOR_NPC
| Parameter | Default | Description |
|---|---|---|
spawnRegionId | 2 | Map region ID for registered NPC spawning |
wandererRegions | 3,4 | Comma-separated region IDs for wanderer placement |
wandererCount | 2 | How many wanderers to spawn per region |
mustHaveSprite | true | Only spawn wanderers who have a PDS sprite uploaded |
Pin an NPC to a specific map event with the note tag <rpgactor_pin:did:plc:xxx>
RPGACTOR_Posts
No parameters. Once loaded, the plugin adds social escape codes for use in Show Text commands:
| Escape Code | Returns |
|---|---|
\BSKYPOST[n] | Text of cached post #n |
\BSKYLIKE[n] | Like count |
\BSKYRT[n] | Repost count |
\BSKYRPLY[n] | Reply count |
\BSKYAUTH[n] | Author handle |
\BSKYDATE[n] | Post date |
RPGACTOR_Sprites
No parameters. Handles the sprite pipeline automatically:
- Downloads character sheets from each player's PDS (
actor.rpg.sprite) - Saves sprites to
img/characters/as$bsky_handle(the$prefix marks a single-character sheet) - Converts AT Protocol avatars into RMMZ face graphics (144×144 in a 576×288 sheet)
RPGACTOR_Stats
No parameters. Syncs the rmmz key inside each player's actor.rpg.stats record. Tracked stats:
| Stat | Example |
|---|---|
| level, class, xp | 5, "Warrior", 1250 |
| hp / maxHp, mp / maxMp | 38/45, 12/20 |
| atk, def, mat, mdf, agi, luk | 18, 14, 8, 10, 12, 9 |
| hit, eva, cri | 95, 5, 4 (stored 0–100) |
| tp / maxTp | 50 / 100 |
The plugin always fetches the full record first, merges the RMMZ data, then writes it back. Other system keys (D&D, DCC, custom, etc.) are preserved.
Plugin Updates
These plugins are under active development. New features, bug fixes, and compatibility improvements are slowly shipping.
Check the version number in the download card above to see if you're current.
Found a bug? Have a feature request? Let us know:
Send Feedback
Further Reading
- Game Jam – April 2026 jam with prizes for games using the plugins
- Developer Guide: Full Plugin Reference – auth flow, NPC commands, and technical details
- REST API – for non-RPG Maker engines (Godot, Unity, web apps)
- Systems Reference – all 6 stat systems and their fields
- Licenses & Disclosure – credits, acknowledgements, and legal information