Clickable Areas Plugin for RPG Maker MV

 Disclaimer: This plugin was written mostly by ChatGPT. I will attempt to provide support if bugs or other issues are encountered, and new versions for bug fixes and additional features will likely be released. Some reference code for the mouse hover syntax was sampled from Tor Damian Design’s Mouse System Ex plugin, and they have been credited appropriately.

What is this?

This plugin allows for ‘Mouse Areas’ to be defined on the game screen that can execute custom scripts when:

• The left mouse button is clicked down in the area.
• The left mouse button is released in the area (requires having been clicked down within the area).
• The cursor enters the area.
• The cursor leaves the area.

A single defined Mouse Area can hold scripts for all four of the above functions. Scripts can be left blank if one or more functions are not required.

My main motivation for this plugin was to more easily create custom GUI menus without some of the limitations that other plugins such as YEP Picture Common Events and KageDesu’s VPlayer had in regards to requiring a separate image for each clickable area, as well as hover detection for button hover effects and the like.

How to Use

Areas are defined through AddMouseArea(ID, X1, Y1, X2, Y2, Priority, Disable Touch Movement, Click Down Script, Click Release Script, Mouse Enter Script, Mouse Leave Script), with a working example being:

AddMouseArea(1, 100, 100, 200, 200, 1, true, "$gameMessage.add('Mouse Pressed!');", "$gameMessage.add('Mouse Release!');", "$gameMessage.add('Mouse Entered!');", "$gameMessage.add('Mouse Left!');"); 

The arguments, in order, are:

• ID – Integer value. Used to reference the Mouse Area for other functions. Keep this unique from other existing Mouse Areas, or they will be overwritten.
• X1, Y1, X2, Y2 – Screen coordinate values. X1 and Y1 define the top-left coordinate, and X2 and Y2 define the bottom-right coordinate. An area covering the whole (default) RPG Maker screen would be 0, 0, 816, 624
• Priority – Integer value. Multiple Mouse Areas can be overlapped in partial or completely when defined. Areas with equal priority can have their scripts execute at the same time, while areas with higher priorities will block all overlapping lower-priority areas from firing their scripts. Lower-priority areas can still run their scripts if the mouse is outside of the higher-priority area.
• Disable Touch Movement: If false, clicking in the area will have the player attempt to move to the underlying spot as normal. If true, the player will not attempt to move to the spot clicked. Touch Movement will re-enable itself once the mouse leaves the area.
• Scripts – Defined in double quotes “”. Leave the script blank (empty quotes) if the function is not needed. The argument order for the scripts is the mouse pressed down, the mouse released, the mouse cursor entered, and the mouse cursor leaving an area. An area with no scripts attached will look like AddMouseArea(1, 100, 100, 200, 200, 1, true, "", "", "", "");

Areas can be deleted with RemoveMouseArea(ID);

Areas can have their boundary area and priority redefined with RedefineMouseArea(ID, X1, Y1, X2, Y2, Priority);

Areas can have their scripts redefined with RedefineMouseAreaScripts(ID, { typeOfScript: "Script;" });

• Replace ‘typeOfScript’ with pressScript, releaseScript, enterScript, and leaveScript to denote which script function you are replacing. Any undefined script functions will be left alone.
• The syntax to replace multiple script functions in one function call is: RedefineMouseAreaScripts(ID, { firstScript: "Script;", secondScript: “Script;” });

Notes:

• Mouse Areas are invisible. Graphics are optional, and have to be handled using the default RPG Maker image system or another image/video plugin.
• Mouse Areas will persist between map transitions. Manually remove them with the RemoveMouseArea(ID); function when they are no longer needed.
• Redefining the Mouse Area boundaries will instantly move the area. Changing or morphing the area over time (ex: a moving clickable target) is currently not directly supported, but there is theoretically no hard limit to how many times per second the RedefineMouseArea(); function can be called.
• The mouse release script will not execute if the mouse was clicked down outside of the area, moved into the area, and then released. Similarly, the script will not execute if the mouse is clicked down in the area, moved outside of the area, and then released. However, the mouse release script will still fire if the mouse is clicked down inside the area, moved outside the area, moved back inside the area, and then released.
• If the Mouse Area is deleted through its own click event, the script for the mouse leaving the area will not execute. However, if the Mouse Area is deleted through its own click down event, the click release event will still execute.
• Touch Movement should still be restored in the event the cursor was in the Mouse Area when it is deleted.