Clickable Areas Plugin for RPG Maker MV

Disclaimer: This plugin was written mostly by AI. 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 unique designated image indexes for each button, as well as hover detection for button hover effects and the like.

(The above GIF shows a rough example of the hover script functions running scripts to alter the images in a pseudo-menu. The mouse areas themselves do not require images and can be invisible.)

How to Use

Areas are defined through AddMouseArea(ID, X1, Y1, X2, Y2, Picture file name/hex color, Picture Opacity, Priority, Disable Touch Movement, Mouse Press Script, Mouse Release Script, Mouse Hover Enter Script, Mouse Hover Leave Script, Enabled, Keyboard Up ID, Keyboard Down ID, Keyboard Left ID, Keyboard Right ID), with a working example being:

AddMouseArea(1, 100, 100, 200, 200, "#3dc7d9", 255, 1, true, "$gameMessage.add('Mouse Pressed!');", "$gameMessage.add('Mouse Release!');", "$gameMessage.add('Mouse Entered!');", "$gameMessage.add('Mouse Left!');", true, 2,3,4,5);

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
• Picture Name - String with the image file name (without extension) that the area should display (anchored to top left at original image size). Empty string means no image. Can enter a hexadecimal color value such as "#ffa4c6" to instead display a solid color to visualize the whole area.
• Opacity - Value from 0 to 255, determines the transparency of the image or hex color fill.
• 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. Priority also determines image layering order (higher=on top)
• 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, "#3dc7d9", 255, 1, true, "", "", "", "", true, 0,0,0,0);
• Enabled - If true (default), the area will execute its scripts as normal. If false, the scrips for the area will not execute.
• Keyboard Navigation IDs - used to designate which area to 'navigate' to when pressing directional keys. In order, they define the up, down, left, and right directions. Use 0 or other invalid ID to block navigation in a particular direction.

Areas can be deleted with RemoveMouseArea(ID);

Areas can have their priority and touch movement blockage redefined with RedefineMouseArea(ID, Priority, true/false); 

Areas can have their dimensions and location moved with MoveMouseArea(ID, X1, Y1, X2, Y2, Frames, “Easing”); Easing is a string value, and it supports 'none', 'in', 'out', and 'inout'.

Areas can have their images changed with RedefineMouseAreaImage(ID, “Picture”, Frames); The Picture argument should be a string that contains either nothing for no image, the file name of the image in the img folder (no file extension), or a hexadecimal color value with a # prefix. The image or color will fade over the designated number of frames (0 for instant). If fading to/from nothing, the fade out/in will take the full number of frames. Fading from one image to another will fade out for half the frames and fade in for the other half of the frames.

Area can have their image opacity changed with FadeMouseAreaImageOpacity(ID, Opacity, Frames). Opacity should be an integer value from 0 to 255.

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;” });

Scripts can be remotely run with RemoteRunMouseAreaScript(ID, “scriptType”). ScriptTypes are pressScript, releaseScript, enterScript, leaveScript.

Areas can be temporarily enabled/disabled (scripts will not execute when disabled and pictures will become invisible) through EnableMouseArea(ID); and DisableMouseArea(ID);

Keyboard navigation can be enabled or re-disabled through EnableKeyboardNavigation(); and DisableKeyboardNavigation();

Keyboard directional targets can be redefined through  RedefineMouseAreaNavigation(ID, {upId: targetID, downId: targetID, leftId: targetID, rightId: targetID});

Notes:

• Mouse Areas can have graphics or be invisible. Graphics can either be pictures or designated colors.
  • Note: pictures will not stretch to fit the area, and will be anchored to the top left corner of the area. The scripts will (or won't) execute based on the defined area coordinates, not the visible picture dimensions (unless using a hex color fill).
• Mouse Areas will persist between map transitions. Manually remove them with the RemoveMouseArea(ID); function when they are no longer needed.
• When moving the mouse area with MoveMouseArea, the hover functions will not trigger if the area passes over (or leaves/intercepts) a completely stationary cursor. Movement of the mouse will trigger the hover effects as expected.
• 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 events, 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.
• Any touch movement routes in progress when the mouse moves over an area with touch movement disabled will be canceled (the player character will halt their movement) in order to prevent a bug where the touch movement route would fail to clear and cause the player to rapidly interact with their destination (possibly triggering a destination event every frame).
• Enabling/Disabling an area will disable all script functions. Split the area into two or more equally overlapping areas with equal priority if you wish to separately enable or disable the script functions. Alternatively, use the RedefineMouseAreaScripts function to alter or erase a script function.
• Keyboard navigation begins disabled, and can be enabled through EnableKeyboardNavigation(); When navigating with arrow keys or WASD, it will attempt to mimic the behavior of the mouse moving out and into areas by triggering the hover enter end exit scripts. Moving the mouse will trigger the hover exit script of the area 'selected' by the keyboard navigation (mimicking if the mouse jumped from the selected area to the current location of the cursor). If the mouse is over an area, keyboard navigation will begin from that area, otherwise it will start at the area with the lowest ID value. Space and Enter will trigger both of the click events (click down and click release) of the selected area at the same time. Character movement and interaction is not automatically disabled during keyboard navigation of areas.