RPG Maker MV/MZ Script Call Reference - In-Depth Guide for MV & MZ

RPG Maker MV/MZ Script Call Reference

Table of Contents

• General Script Calls{#general-script-calls}
• Movement{#movement}
• Screen Effects & Pictures{#screen-effects-pictures}
• Audio & Video{#audio-video}
• Scene Control{#scene-control}
• System Settings{#system-settings}
• Map{#map}
• Battle{#battle}
• Events & Interpreters{#events-interpreters}
• Party & Inventory{#party-inventory}
• Actors & Enemies{#actors-enemies}
• Plugins{#plugins}
• Examples & Quick References{#examples-quick-references}

---

General Script Calls

MV and MZ expose a rich set of script calls that let developers interface directly with the core engine, the interpreter, and game objects. The following sections summarize core examples and their usage, preserving the exact syntax shown in the original reference. The examples demonstrate how to manipulate messages, party data, switches, variables, items, actors, enemies, and more within an MV/MZ project.

Message

• Show Text: Uses the message window to display dialogue with facial images and backgrounds. For example:

$gameMessage.setFaceImage('Actor1', 0);
$gameMessage.setBackground(0);
$gameMessage.setPositionType(2);
$gameMessage.setSpeakerName('\c[6]\n[1]');
$gameMessage.add('I am \c[6]\n[1]\c[0]!');

• Show Choices: Display a set of options and capture the chosen index via a callback. Example:

$gameMessage.setChoices(['A','B','C'], 2, -1);
$gameMessage.setChoiceBackground(1);
$gameMessage.setChoicePositionType(1);
$gameMessage.setChoiceCallback(n => {
  $gameVariables.setValue(1, n);
});

• Show Scrolling Text: A multi-line narrative that scrolls. Example:

var text = [
  'People have been coming to the wise man,',
  'complaining about the same problems every time.',
  'One day he told them a joke and everyone roared',
  'in laughter.'
].join('\n');
$gameMessage.setScroll(3, false);
$gameMessage.add(text);

• Wait for the message to finish: this.setWaitMode('message');

Change Party & Items

• Change Gold: $gameParty.gainGold(amount); // +1000 gold");
• Change Items: $gameParty.gainItem($dataItems[itemId], amount);
• Remove Items: $gameParty.loseItem($dataItems[12], 1);
• Change Weapons/Armors: gainItem/loseItem on weapons/armors, with optional includeEquip flag to affect equipped items as well.

Change Party Members & HP/MP/TP/EXP

• Change HP: target.setHp(value); or target.gainHp(value);
• Change MP/TP: battler.gainMp(value); battler.gainTp(value);
• Change State: battler.addState(stateId); battler.removeState(stateId);
• Recover All: battler.recoverAll(); or $gameParty.members().forEach(actor => actor.recoverAll());

Change EXP, Level, Parameters, Skills

• Change EXP: actor.gainExp(value);
• Change Level: actor.changeLevel(level, show);
• Change Parameters: battler.addParam(paramId, value);
• Change Skill: actor.learnSkill(skillId); actor.forgetSkill(skillId);
• Change Equipment: actor.changeEquipById(etypeId, itemId);

Change Name & Profile

• Change Name: actor.setName(name);
• Change Nickname: actor.setNickname(nickname);
• Change Profile: actor.setProfile(profile);

Control Switches & Variables

• Control Switches: $gameSwitches.setValue(switchId, value);
• Control Variables: $gameVariables.setValue(variableId, value);
• Range loops: for (var n = id1; n <= id2; n++) { operation }
• Random: Math.randomInt(n) and Math.random() for randomization.

Note

• The reference includes many cross-links to MV/MZ differences and notes for plugins, pointers to MDN/W3Schools, and examples of how to call functions in script contexts. The examples illustrate both MV (older style) and MZ (newer style) usage.

---

Movement

Movement-related script calls drive how characters (player, followers, events) move around the map. Range of commands include transferring, setting positions, movement routes, pathfinding, and various route controls.

• Transfer Player: $gamePlayer.reserveTransfer(mapId, x, y, direction, fadeType)
• Set Vehicle Location: vehicle.setLocation(mapId, x, y)
• Set Event Location: $gameMap.event(eventId).locate(x, y)
• Set Event Location (Swap): character1.swap(character2)
• Scroll Map: $gameMap.startScroll(direction, distance, speed)
• Set Movement Route: character.forceMoveRoute(moveRoute)
• Pathfinding: this.findDirectionTo(x, y) along with movement function calls like moveStraight, moveDiagonally, moveTowardPlayer, moveAwayFromPlayer, moveRandom, and others depending on target coordinates.

You can also query passability and collisions to plan safe routes, check bounding conditions, and coordinate multiple actors.

Anchor note: Each header includes an in-page anchor for intra-page linking, with IDs derived from the section titles. This helps users navigate to subtopics quickly.

---

Screen Effects & Pictures

The reference covers a broad spectrum of screen effects (fade, tint, flash, shake, weather) and picture control (show/move/rotate/tint/erase). Examples include:

• Fade Out/ Fade In: $gameScreen.startFadeOut(frames) / $gameScreen.startFadeIn(frames)
• Tint Screen: $gameScreen.startTint([red, green, blue, grey], frames)
• Shake Screen: $gameScreen.startShake(power, speed, frames)
• Change Weather: $gameScreen.changeWeather(type, power, frames)
• Show Picture: $gameScreen.showPicture(pictureId, name, origin, x, y, scaleX, scaleY, opacity, blendMode)
• Move Picture: $gameScreen.movePicture(pictureId, origin, x, y, scaleX, scaleY, opacity, blendMode, frames, easing)
• Rotate Picture: $gameScreen.rotatePicture(pictureId, speed)
• Tint Picture: $gameScreen.tintPicture(pictureId, [red, green, blue, grey], frames)
• Erase Picture: $gameScreen.erasePicture(pictureId)

These calls cover both the Map screen and Battle screen elements, which use separate image sets for pictures.

---

Audio & Video

The script calls support BGM/BGS/ME/SE and Movie playback. MV and MZ differences are documented for how to set, fade, or play media.

• Play BGM: AudioManager.playBgm({ name, volume, pitch, pan })
• Fadeout BGM: AudioManager.fadeOutBgm(seconds)
• Play BGS/ME/SE: AudioManager.playBgs(...), AudioManager.playMe(...), AudioManager.playSe(...)
• Stop SE: AudioManager.stopSe()
• Play Movie: interpreter.command261([movieName])

There are also commands for setting and querying current BGM, BGS, ME, and other audio engine features.

---

Scene Control

Scene transitions cover Battle, Shop, Name Input, Menu, Save/Load, and more. Example calls include:

• Start Battle: BattleManager.setup(troopId, canEscape, canLose) and SceneManager.push(Scene_Battle)
• Open Shops: SceneManager.push(Scene_Shop); SceneManager.prepareNextScene(goods, purchaseOnly)
• Open Menu: SceneManager.push(Scene_Menu)
• Open Save Screen: SceneManager.push(Scene_Save)
• Goto/Return to Title: SceneManager.goto(Scene_Title)
• Scene Manager helpers: SceneManager._scene, Scene_Base checks, and push/pop stacks.

The reference also covers save game routines (DataManager.saveGame, DataManager.loadGame), and the interplay with the system state (Map, Audio, etc.).

---

System Settings

Includes changes to BGM/BGS/ME, window tones, and save/menu/encounter controls.

• Change Battle BGM: $gameSystem.setBattleBgm(bgm)
• Change Victory/Defeat ME: $gameSystem.setVictoryMe(me), $gameSystem.setDefeatMe(me)
• Change Vehicle BGM: vehicle.setBgm(bgm)
• Save Access: $gameSystem.enableSave(), $gameSystem.disableSave()
• Menu Access: $gameSystem.enableMenu(), $gameSystem.disableMenu()
• Encounter: $gameSystem.enableEncounter(), $gameSystem.disableEncounter()
• Window Tone: $gameSystem.setWindowTone([red, green, blue])

The documentation notes compatibility concerns for versions and plugins beyond the base MV/MZ engines.

---

Map

Map-related calls include tile, tile data, parallax, tileset changes, map display name toggles, and camera controls.

• Map ID: $gameMap.mapId()
• Map Display Name: $gameMap.displayName(), enable/disable via enableNameDisplay(), disableNameDisplay()
• Change Tileset / Parallax / Battleback
• Get Location Info: terrainTag, eventIdXy, tileId, regionId
• Map Camera Coordinates: $gameMap.displayX(), $gameMap.displayY()
• Relocate Map Camera: $gameMap.setDisplayPos(x, y)
• Player/Followers camera focusing, screen centering for Player/Followers

---

Battle

Battle section covers how to start battles, apply effects, and handle results. Methods include:

• BattleManager.setup(troopId, canEscape, canLose)
• BattleManager.setEventCallback(callback)
• Show Battle Animation: $gameTemp.requestAnimation(targets, animationId, mirror)
• Force Action / Abort Battle, etc.

The document provides explicit examples for applying damage, healing, state changes, and battle outcomes for both actors and enemies.

---

Events & Interpreters

This area covers how to interact with map events, common events, labels, jumps, script calls, and event commands. There are sections for Event Page 1-3, Movement, Action Commands, and the interaction with Map events, as well as the use of the common event system and page lists to drive scripted behavior.

Key commands include:

• Call/Trigger events: event.start(), $gameMap.event(7).start(), etc.
• Common Event: $gameTemp.reserveCommonEvent(id)
• Labels and Jumps: interpreter.command119([label])

This area also documents how to insert commands into the current interpreter, and how to craft script-based event commands that mimic MV/MZ features.

---

Party & Inventory

The reference provides an extensive set of scripts to manage party gold, items, weapons, armors, and inventory data. Highlights include:

• Gold: $gameParty.gold(), $gameParty.gainGold(n), $gameParty.loseGold(n)
• Items/Weapons/Armors: $gameParty.gainItem(item, amount), $gameParty.loseItem(item, amount, includeEquip)
• Inventory State: $gameParty.initAllItems(), $gameParty.items(), $gameParty.weapons(), $gameParty.armors()
• Memorise Inventory: $gameVariables.setValue(variableId, { Armors: Object.assign({}, $gameParty._armors), Items: Object.assign({}, $gameParty._items), Weapons: Object.assign({}, $gameParty._weapons) })
• Restore Inventory: use the saved data to re-apply items to the party in order to recreate state

There are also sections on memorising and restoring inventory categories, and on saving/restoring party members.

---

Actors & Enemies

Sections cover how to get battler references by ID or by position, and how to query current HP/MP/TP, stats, skills, equipment, and more. Examples include:

• Actor by ID: $gameActors.actor(actorId)
• Actor by Position: $gameParty.members()[index]
• Party Leader: $gameParty.leader()
• Enemy by Position: $gameTroop.members()[index]
• Battler checks: battler.hp, battler.mhp, battler.atk, battler.def, battler.agi, battler.luk, battler.mmp, battler.mhp, etc.
• Checks for skills: actor.skills(), actor.usableSkills(), actor.hasSkill(skillId)
• Equipment: actor.weapons(), actor.armors(), actor.equips(), actor.changeEquipById(slot, item)

The MV/MZ script reference also describes how to inspect the Actor/Enemy database records through actor(), enemy(), troop(), and related properties.

---

Plugins

Plugin system overview including headers, parameters, plugin commands, plugin keywords, and how to define plugin params in JSON. It covers:

• Plugin headers: @plugindesc, @author, @param, @desc, @default, @type, etc.
• Plugin commands: PluginManager.registerCommand(pluginName, commandName, function)
• Parameters: Get plugin params via PluginManager.parameters('pluginName')
• JSON parsing: JSON.parse, Number(params['paramName']), parseInt, etc.
• Namespaces and version declarations for plugin compatibility.

The section emphasizes best practices: use a global namespace to prevent clashes, provide versioning, and document your parameters and commands clearly.

---

Examples & Quick References

The document includes a consolidated set of examples showing how to construct scripted events, move routes, and common scenarios such as:

• How to force actions in battle, show messages, and manage inventory with a few MV/MZ idioms.
• How to query and operate on the current map, party, and battlers to achieve complex logic.
• Short snippets for common tasks like saving/loading, changing BGM, and calling plugin commands.

This section serves as a compact reference for developers who want fast access to the most-used API chains without searching through long pages.

---

Note on anchors and internal linking:

• All headers have anchors automatically generated and appended with identifiers in the Markdown content. This enables in-page navigation and a Table of Contents that links to sections via anchors like General Script Calls.
• The content preserves the structure and context of the original script call reference, including MV vs MZ variations where relevant.

If you need the complete verbatim text of the reference, you can use this structure as a mapped export container to preserve data points and facilitate downstream parsing or indexing.