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.
A big thank you to Degica for making this plugin free for commercial use for everyone!
|Discussion topic||Official RPG Maker Forums|
|Download||Download from GitHub|
|Print / PDF|
Table of Contents
- 1 Important: About filenames
- 2 Custom Cursor options
- 3 Cursor offsets
- 4 Changing the custom mouse cursor during gameplay
- 5 Notetags
- 6 Hover Select options
- 7 Auto Change Cursors options
- 8 Auto Change Icons options
- 9 Mouse Icons options
- 10 Mouse Icon Tags options
- 11 Customizeable Notetags options
- 12 Useful script calls
- 13 Changelog
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
Use Custom Cursor?
|true||Enables the custom cursor|
|false||Disables the custom cursor (default)|
Custom Cursor Image
|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
|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.
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:
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:
Changing the custom mouse cursor during gameplay
You can change the custom mouse cursor graphic during gameplay in several ways.
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:
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.
This resets the custom cursor to the one you set in the plugin parameter “Custom Cursor Image”.
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.
Where 5 is the wanted icon index of the icon you want to show.
icon_offset x y;
This will offset the icon’s X and Y positions in pixels, overriding the default settings you set in the plugin options.
This command will hide the mouse cursor when it’s over this event.
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:
Triggers the event by clicking on it.
Triggers the event when the mouse hovers over the event.
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:
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
Highlight On Hover
|true||Enables highlighting 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
|Number||Sets a cooldown (in frames) between each time the Cursor sound effect from the MV Database System tab can be played.||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
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
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
|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
|Number||The X offset to show icons at relative to the mouse cursor's top-left corner.||9|
Icon Offset Y
|Number||The Y offset to show icons at relative to the mouse cursor's top-left corner.||14|
Icon Tag 1-15
|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:
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.
These options let you customize some of the notetags used.
No Auto Cursor Notetag
|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!|
|Text||Customize the notetag that enables an event to be activated by a touch or mouse click.||click_activate!|
|Text||Customize the notetag that enables an event to be activated when the mouse moves over it.||hover_activate!|
|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:
|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:
|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.|
Page last modified: January 17, 2016