Mouse System Ex

TDDP – MouseSystemEx lets you set and change custom mouse cursors during gameplay and event interaction; enables mouse interaction to trigger events without the player character; show icons next to the mouse, and much more.

Commercial use Free. See Terms of use page for details.
A big thank you to Degica for making this plugin free for commercial use for everyone!
Latest version 1.8.2
Last updated 2015-12-14
Dependencies None
Discussion topic Official RPG Maker Forums
Download Download from GitHub
Print / PDF
Print Friendly, PDF & Email

Important: About filenames

It’s very important that none of your custom cursor files have spaces in their filenames. This is due to how custom cursors are displayed using CSS rules, and spaces in filenames just don’t work reliably. So when you choose filenames for your custom cursor graphics, please use only letters, numbers and underscores ( _ ), to ensure compatibility with all browsers and environments.

Custom Cursor options

Parameters: Use Custom Cursor?, Custom Cursor Image and Custom Cursors Folder

Parameters: Use Custom Cursor?, Custom Cursor Image and Custom Cursors Folder

Use Custom Cursor?

Option Description
true Enables the custom cursor
false Disables the custom cursor (default)

Custom Cursor Image

Value Description Default
Text The name of the custom cursor image file. default

The images used for custom cursors must be in the PNG ( .png ) file format, and can be up to 128×128 pixels, but if you plan to deploy to browsers for online play, for maximum browser compatibility a maximum resolution of 32×32 pixels is recommended. You may omit the file extension from this value (the .png part).

Custom Cursor Folder

Value Description Default
Text The path to the folder where the custom cursor images are found.
Must end with a forward slash ( / ). Relative to your project's root folder.

Cursor offsets

You might want to show the cursor offset to the “click point” of the cursor (by default the upper left corner of the image). For example if you want to show a crosshair were the center of the image is the center of the cursor, you can do this by appending _x and/or _y coordinates to your cursor filenames. As a visual example:

Using offsets in filename.

Using offsets in filename.

The _xN and _yN should be at the end of the filename, before the extension ( .png ). When you specify this cursor in the engine, you simply omit the _x and _y parts. Using the above example crosshair cursor looks like this in the editor:

Using a cursor with offsets.

Using a cursor with offsets.

Changing the custom mouse cursor during gameplay

You can change the custom mouse cursor graphic during gameplay in several ways.

Using notetags on events

To change the custom cursor when the mouse is hovering over an event, use the following notetag either in the event’s “Note” box, or in a Comment event command:

hover_cursor filename;

Notetag: hover_cursor filename;

This will swap to the “filename.png” image file when the mouse hovers over the event. You can omit the file extension (.png) if you want, in which case the plugin will assume the .png extension and add it automatically. You can see this in the Comment box in the picture above.

Important: If the notetag is placed in a Comment box on an event page it only acts for that page. If you place it in the event’s Note box, then it acts for all pages of the event, but can be overridden on a per-page basis using a Comment box.

See the Notetags section for more info.

Using Plugin Commands

You can also use Plugin Commands to change the default custom mouse cursor image, as well as reset it to the option you set in the plugin parameters. This can be used for things like minigames, where you want a new custom cursor to appear all the time, even when a player is not interacting with events, or if you want to have a custom cursor for different characters.


This sets a new custom mouse cursor.

SetCustomCursor filename.png

Plugin Command: SetCustomCursor filename.png


This resets the custom cursor to the one you set in the plugin parameter “Custom Cursor Image”.


Plugin Command: ResetCustomCursor


Notetags can be placed two places:

  • In an event’s Note box, in which case they will act for all pages of that event
  • In a Comment event command anywhere on an event’s page, in which case they will act only when that page is active. Page notetags will override the event’s Note notetag if the property they affect is the same.

Cursor and icon

These notetags let you show an icon next to the mouse cursor when hovering over events that contain them. For specifying an icon you have two choices: use an icon index directly, or use a Mouse Icon Tag.

hover_icon x;

Notetag: hover_icon 5;

Notetag: hover_icon 5;

Where 5 is the wanted icon index of the icon you want to show.

icon_offset x y;

Notetag: icon_offset 0 0;

Notetag: icon_offset 0 0;

This will offset the icon’s X and Y positions in pixels, overriding the default settings you set in the plugin options.


Notetag: hide_cursor!

Notetag: hide_cursor!

This command will hide the mouse cursor when it’s over this event.


Notetag: no_auto_cursor!

Notetag: no_auto_cursor!

This will make it so any automatic cursor changes you’ve set up in the Auto Change Cursors options is not performed.

Mouse event activation

These notetags let the player interact with the event using the mouse cursor instead of the player character. There are three options:


Notetag: click_activate!

Notetag: click_activate!

Triggers the event by clicking on it.


Notetag: click_activate!

Notetag: hover_activate!

Triggers the event when the mouse hovers over the event.


Notetag: leave_activate!

Notetag: leave_activate!

Triggers the event when the mouse leaves the event.

The three notetags listed above can be customized in the “Interact To Activate” parameters options. See the Interact To Activate options section.


You can use the following notetag command to make an event set its Self Switch to a given value when the user clicks/taps on it:

Notetag: click_switch A true;

Notetag: click_switch A true;

Where A is the Self Switch to manipulate and true is the true/false value. The notetag can be typed in the Note field and event Comments, just like the others in this plugin.

Hover Select options

Parameters: Highlight On Hover and Hover SE Cooldown

Parameters: Highlight On Hover and Hover SE Cooldown

Highlight On Hover

Option Description
true Enableshighlighting menu items on hover
false Disables highlighting menu items on hover(default)

If set to true the default operation of the mouse changes to automatically highlight a menu item when the mouse is over it, and you then only have to click it once to activate it. The default MV mouse functionality requires one click to highlight a menu item and then another click to select it.

Hover SE Cooldown

Value Description Default
Number Sets a cooldown(in frames) between each time the Cursor sound effect from the MV Database System tab can beplayed. 4

This is set to 4 by default so as to not play too many instances of the sound effect at once when moving the mouse over multiple menu items quickly in a row, which can otherwise sound jarring. Depending on the sound effect you use you might want to increase or decrease this value.

Auto Change Cursors options

Parameters: Auto Change Cursors

Parameters: Auto Change Cursors

These options let you specify custom cursor files that are to be automatically activated when the mouse is over an event that contains specific event commands.

All the values are text entries for the filename to use as a custom cursor. As in other settings you can omit the .png file extension. In the image above you can see an example of possible settings here.

Auto Change Icons options

Parameters: Auto Change Icons

Parameters: Auto Change Icons

These options let you specify icons to show next to the cursor when the mouse is over an event that contains specific event commands.

All the values can either be icon indexes or tags specified in the Mouse Icon Tags options.

Mouse Icons options


Parameters: Mouse Icons

Hide Cursor

Option Description
true Will hide the mouse cursor when an icon is shown.
false Will keep showing the mouse cursor when an icon is shown. (default)

Icon Offset X

Value Description Default
Number The X offset to show icons atrelativetothe mouse cursor's top-left corner. 9

Icon Offset Y

Value Description Default
Number The Yoffset to show icons at relativetothe mouse cursor's top-left corner. 14

Mouse Icon Tags options

Prameters: Mouse Icon Tags

Prameters: Mouse Icon Tags

Icon Tag 1-15

Value Description Example
Text Create a named tag binding to an icon index to use in your hover_icon notetag. quest: 191

These settings act as convenient tags you can use instead of icon indexes when using the Mouse Hover Icons notetag. Anything before the colon : becomes the tag to be used in the notetag; the number after it is the icon index to that will be used. You’d type this custom notetag into the Note field or a Comment field:

Notetag: hover_icon quest;

Notetag: hover_icon quest;

Using tags for icons that are used repeatedly means that it’s easier to change the icon for these events later on by just changing the corresponding Mouse Icon Tags, instead of having to go to each and every event and edit the icon index if you change your mind which to use. It’s also more readable.

Customizeable Notetags options

Parameters: Customizeable Notetags

Parameters: Customizeable Notetags

These options let you customize some of the notetags used.

No Auto Cursor Notetag

Value Description Default
Text Customize the notetag that is used to disable automatic cursor switching. no_auto_cursor!

No Auto Icon Notetag

Text Customize the notetag that is used to disable automatic icon switching. no_auto_icon!

Click Notetag

Text Customize the notetag that enables an event to be activated by a touch or mouse click. click_activate!

Hover Notetag

Text Customize the notetag that enables an event to be activated when the mouse moves over it. hover_activate!

Leave Notetag

Text Customize the notetag that enables an event to be activated when the mouse leaves after having moved over it. leave_activate!

You should choose a notetag which you won’t normally write in a comment meant only for your own benefit, so using underscores and an exclamation mark can be useful to make sure you don’t accidentally type out the notetag.

Useful script calls

Below is a list of useful script calls and what they give you in return when called. These can be used for your conditional branches, variables, or anything else you need them for.

Important: All script calls must be prepended with the following:

This means that if the script call listed is cursorImage, you would have to type it like this in the script call:

script call Returns description
cursorImage Text The filename for the current custom cursor image being used.
customCursorPath Text The local folder path the plugin uses to find the image files used for custom cursors.
conditionsValidForMouseHoverCheck() True / False Whether the engine is ready to check for mouse hover checks. This returns true if the following conditions are met:

  • The current scene is started
  • The current scene is a map
  • The current map is defined
  • There is data for the current map
  • There are no blocking events running


Version Changes
  • Fixed bug with the SetCustomCursor plugin command
  • Fixed bug where click events would activate if you clicked through a menu, after closing it.
  • Fixed a bug where event order was incorrect for click activation.
  • Mouse click, hover and leave activate now activate all events under the mouse, not just the topmost. This also affects cursor changes and icons; the topmost event will overwrite those below if conflicts arise.
  • Internal “namespace” structure changed for brevity, remains the same functionally and externally
  • Externalized getting events from xy coords to its own method to make compatibility easier for other plugins that interact with this one
  • Code comments added to more complex methods, also as part of the effort to provide full JSDoc compliant comments for all plugins. This will be rolled out to all custom methods in plugins gradually as it takes time and is of lower priority right now.
1.7.0 Now supports cursor offsets in filenames. See Cursor offsets for more information. Also internal restructuring for better accessibility for other plugins to interact with the startup processes.
1.6.2 Added Battle Processing Cursor and Battle Processing Icons for auto cursor/icon switching when hovering over events with these event commands in them.
The plugin no longer requires a specific filename to work, as it fetches its parameters in an alternative manner now.
1.6.1 Added option for No Auto Icon notetag.
1.6.0 Now changes cursors using prefetched CSS properties and a .json file for a list of cached cursors useable on all platforms. This fixes inconsistencies, loading delays and bugs.
1.5.10 Added auto icons and fixed a bug where mouse move position wasn’t updated for icon placement when an event was active
1.5.9 Fixed bug where click activation on events still fired off valid destination marker. Also renamed internals to match plugin name properly, and minor improvements to code commenting.
1.5.8 Added local and web mode checks to updating the mouse cursor, since local node webkit solution requires a forceful refresh due to a bug where we can’t properly check if the mouse left and re-entered the window.
1.5.7 Code documentation updates, internal structure changes and optimization. SetCustomCursor and ResetCustomCursor now work as intended.
1.5.6 All anon funcs are now registered on the TDDP_MouseSystem object for future compatibility.
1.5.5 Fixed problem with parsing comments; removed restriction on multiline comments.
1.5.4 Added more auto hover cursors and optimized lookup for them.
1.5.3 Fixed issue where custom mouse cursor updated in menus based on map
1.5.2 Fixed issue where custom cursor and mouse icons didn’t update if mouse moved over another event without any space in between them.
1.5.1 Not checking for events under mouse while $gameMessage has text on wait.
1.5.0 Notetag for click_switch SWITCH true/false; implemented
1.4.0 Merged in the Highlight Menu Item On Hover functionality from another plugin of mine, now a part of this one permanently.
1.3.0 Added support to change custom cursor on hover or with a Plugin Command. Vastly optimized fetching of notetag data by extending Game_Event instead of when hovering over events.
1.2.0 Added support for a custom cursor with options.
1.1.0 Added support for the Note field for events, which acts globally for all pages.
1.0.3 Added hide_icon! notetag and icon_offset 0 0; notetags and help.
1.0.2 Fixed bug with icon bitmap not being cleared due to typo.
1.0.1 Added Mouse Icon Tags.
1.0.0 Initial stable release.