Equipment Change Hook MV

This plugin lets you hook any Actor equipment changes, injecting a Common Event immediately after that change (blocking the current event script until done).

The hook also applies to other Actor equipment changes, like from the equipment menu, and runs eagerly there. You can distinguish this using the isInEagerProcessing… parameters.

It also allows you to receive various related information through configurable Switches, Variables and global JavaScript variables.

Making further changes to equipment from the hook is fine, but please be careful about accidentally creating an infinite loop.
You can easily avoid this by using one of the wasCausedByCommand… parameters to exit the hook early, if you don't need to chain automatic equipment changes together. Otherwise, make sure to branch e.g. on slot index or equipment item ID to ensure finite chaining.

What you can do with this

A few examples of what's easy to make with this plugin:

• Play distinct equip sounds for different equipment.
• Make further equipment changes, visible immediately in the Equip menu without flickering.
• Add or remove a Status depending on the equipment, applied without closing the menu.
• Change Variables and/or Switches when the player changes their equipment.
• Schedule a message or dialogue to occur once the menu is closed.

Note that these may by default be delayed if the handler is already busy processing a previous change, for example due to a Show Text Command blocking until the menu is closed. There is now a way to change this behaviour, but doing so could make working with this plugin more complicated.

Commands

This plugin does not add additional commands.

Parameters

I set up parameter types, so you can easily configure the Common Event, Switches and Variables using the relevant editor GUI. JavaScript globals are set as properties on the window, so they are easily accessible in conditions.

Hooks

onEquipmentChanged (Common Event): Handler that runs after each equipment change.

Control Flow Information

wasCausedByCommand… (Switch / JS global key): Indicates whether a Command caused the equipment change.

isInEagerProcessing… (Switch / JS global key): Indicates when the handler is running eagerly outside the normal command interpreter flow. This occurs for example when the player changes equipment through the equipment menu and allows you to take an action "instantly" afterwards.
Note that any yielding command, like Show Text…, will cause the remainder of the handler to run in parallel processing mode.

Actor Information

actorId… (Variable / JS global key): Set to the affected Actor's ID.

actorName… (Variable / JS global key): Set to the affected Actor's name.

Slot Information

slotIndex… (Variable / JS global key): Set to the affected equipment slot index. Starts at 0!

equipmentTypeId… (Variable / JS global key): Set to the affected equipment slot's Equipment Type's ID.

equipmentTypeName… (Variable / JS global key): Set to the affected equipment slot's Equipment Type's Name.

Equipment Information

oldClass… (Variable / JS global key): (Hacky!) Set to the "class" of the equipment that was unequipped. This should be either "weapon", "armor" or "".

oldId… (Variable / JS global key): Set to the ID of the equipment that was unequipped.

oldName… (Variable / JS global key): Set to the name of the equipment that was unequipped.

newClass… (Variable / JS global key): (Hacky!) Set to the "class" of the equipment that was equipped. This should be either "weapon", "armor" or "".

newId… (Variable / JS global key): Set to the ID of the equipment that was equipped.

newName… (Variable / JS global key): Set to the name of the equipment that was equipped.

Global Options

Diff "Equip → Optimize"? (boolean, default: true): Pauses the hook while optimising equipment, then runs it only for changed slots.

Advanced Options

No Mutex? (boolean): Deactivates the critical section between concurrent equipment changes. (See below.)
The hook is scheduled as normal when the equipment change is caused by a Command, so this only changes behaviour involving Common Events active in parallel, like those caused by equipment changes in the menu.

JavaScript API

This plugin unconditionally sets the global variable TS_Equipment_Change_Hook when loaded.

There, the following hookable and externally callable functions are available:

startDiff()

Starts a new diff, during which the equipment change hook will not be called.

Diffs may be entered recursively, but only the outermost causes the hook to run for changes.

Make sure you use try…finally to always reliably call .stopDiff():

TS_Equipment_Change_Hook.startDiff();
try {
    // Update equipment here.
} finally {
    TS_Equipment_Change_Hook.stopDiff();
}

stopDiff()

Closes a previously started equipment change diff.

Iff this was the outer-most diff, changes are detected by item class and ID and the hook is scheduled for each change detected this way.

Iff no diff was open, an Error is thrown.

Scheduling

This plugin comes with a rudimentary scheduler and runs the handler as critical section to ensure smooth operation. This means:

The specified Common Event will:

• run exactly once for each equipment change,
• run to completion before starting for the next equipment change,
• block a triggering Command list until it completes,
  • unless already in scope of the equipment change handler, in which case it will run immediately after any currently running or previously queued handlers on this interpreter instead,
• when not triggered by a Command, run eagerly until it is blocked or yields, then complete in parallel as possible (but retaining exclusivity even while yielded).

As handlers scheduled for parallel processing and the critical section mutex are not persisted, manual saving is disabled while handlers are scheduled to run in parallel or are currently running.
This usually isn't an issue, but is noticeable when the player changes equipment in the equipment screen and onEquipmentChanged does not complete before the player can return to the menu, or if onEquipmentChanged has a pause that allows opening the main menu.

You can avoid this using either the isInEagerProcessing… parameter(s) to conditionally not use commands that yield (like for example Show Text), or by dispatching further processing through a Switch or Variable, which can be set instantly.

Notes

Certain actions cause a number of equipment changes to happen at once. The hook still runs for each of those changes separately.

One example of this is the 'Optimize' command in the equipment menu, which first (tries to) unequip each item in order and then equips each optimal item from the inventory. This action can also be repeated very easily by the player.

As such, if you'd like to play back for example a visual effect or sound cue when equipping or unequipping an item, it's usually better to instead set a Switch or Variable in the hook and then execute the effect only once elsewhere.

Compatibility Notes

This plugin was tested on RPG Maker MV 1.6.2, uses only the public RPG Maker API as far as possible, and does not use any platform-specific APIs.

Parameters marked with (Hacky!) access a piece of data not part of the public API (Game_Item._dataClass), which is slightly more likely to change with RPG Maker updates.

The hook itself invokes command117 (Common Event) from JavaScript by setting Game_Interpreter._params directly. This is likely not part of the public API, but seems like the most compatible way to inject a Common Event, still letting other plugins hook into that as normal.

If you develop on Windows and deploy for Linux, you must first update the NW.js runtime in the nwjs-lnx folder to at least version 0.29.4 (to match other targets, but ideally use the newest stable version)! You can find more information and a tutorial for this here. It's fast, easy, and also fixes many other problems for your players.