Plug₂in for RPG Maker MV and MZ

This is an easy-to use pattern rumble plugin for RPG Maker MV and MZ.

Now completely rewritten in 0.2 for easier maintenance, with more powerful API and including a built-in Options sub-menu to deal with connection and configuration.

There is also now a convenient online Pattern Composer (which should be installable using the itch.io desktop app).

The base price is still free, but please consider leaving a tip if you use this commercally. It was a lot of work.

The plugin works both in standalone games and web deployments.
It works with the stock version of NW.js in MZ (MV: update it) and instead uses Intiface to connect to Xbox 360 style gamepads (Windows only) as well as a wide variety of vibrating and oscillating sex toys (cross-platform).

Read https://buttplug-developer-guide.docs.buttplug.io/intro/buttplug-ethics.html before starting and always respect the player's maximum intensity settings.

The https://intiface.com/ server must be running on port 12345 to connect. When running in the browser, connections to localhost must be allowed.

The minified/binary files in the archive (in older versions) are verbatim from buttplug - npm (npmjs.com) (version 1.0.17), from the dist/web/ folder, and you can replace them with fresh copies if necessary.
Generally speaking, you only need to extract the archive into your plugins folder though.

A note on compatibility:

I had to add delete process.versions.node; for this to work, as https://github.com/rust-random/getrandom doesn't work correctly in NW.js without the Node Crypto module otherwise. (This removes the package versions table entry for Node.js at runtime, to make getrandom not detect it and use the browser API instead.)

If this plugin causes issues with others, it's most likely because of that.
The latest version doesn't need this workaround!

Tested with RPG Maker MV Version 1.6.2.
Tested with RPG Maker MZ Version 1.7.0.

Parameters:

Name for Intiface:
    The application name to show in the intiface server GUI.
    (Defaults to game title.)

Stop on Title/Stop on Game Over:
    Automatically stop all activity when reaching certain screens.

End on Title/End on Game Over:
    Automatically end all activity when reaching certain screens, without cancelling the current pattern queue. These default to true.

Options Entry:
    Adds an additional entry to the Options menu for configuration (see screenshots).
    The texts of this entry and the menu are also configurable.

Plugin Command:

     PlugPlug connect
         # Connect to all available devices (and pulse each briefly to confirm).

     PlugPlug disconnect
         # Stop all devices and disconnect from Intiface.

     PlugPlug config
         # Opens the interactive configuration screen (pauses gameplay).

     PlugPlug config vibe strength <multiplier>
         # Set global vibe strength multiplier. 0.0 - 26.0. Default: 1.0

     PlugPlug config vibe duration <multiplier>
         # Set global vibe duration multiplier: 0.0 - infinity. Default: 1.0

     PlugPlug config vibe pause <multiplier>
         # Set global vibe pause duration multiplier: 0.0 - infinity. Default: 1.0

     PlugPlug config osci strength <multiplier>
         # Set global oscillation speed multiplier. 0.0 - 26.0. Default: 1.0

     PlugPlug config osci duration <multiplier>
         # Set global oscillation duration multiplier: 0.0 - infinity. Default: 1.0

     PlugPlug config osci pause <multiplier>
         # Set global oscillation pause duration multiplier: 0.0 - infinity. Default: 1.0

Configuration works offline and is now saved automatically, if you use the plugin command API or when changed through the included options screen. Use ConfigManager.save(); after changing them from JavaScript.

Vibration commands now use a queue and block until reached or completed.
The queues for vibration and oscillation run independently in parallel.

     PlugPlug vibe pulse <on-duration> <off-duration> <pattern>
         # Vibrate once, then pause as specified. Now resumes the repeated pattern afterwards!

     PlugPlug vibe start <on-duration> <off-duration> <pattern>
         # Set a vibration pattern to repeat until told otherwise.

     PlugPlug vibe start requireN <required-count> <off-duration> <pattern>
         # Like "start", but will repeat <required-count> times before continuing to process the queue.

     PlugPlug vibe sync
           # Wait for the current vibration queue to catch up.

     PlugPlug vibe end
           # End vibration after the current queue.

     PlugPlug osci pulse <on-duration> <off-duration> <pattern>
         # Oscillate once, then pause as specified. Now resumes the repeated pattern afterwards!

     PlugPlug osci start <on-duration> <off-duration> <pattern>
         # Set an oscillation pattern to repeat until told otherwise.

     PlugPlug osci start requireN <required-count> <off-duration> <pattern>
         # Like "start", but will repeat <required-count> times before continuing to process the queue.

     PlugPlug osci sync
           # Wait for the current oscillation queue to catch up.

     PlugPlug osci end
           # End oscillation after the current queue.

     PlugPlug end
           # Independently end vibration and oscillation cleanly after the current queue.

     PlugPlug stop
         # Stop all motion imediately.

     PlugPlug async .../PlugPlug sync
         # Commands can be prefixed with "async" to not block. You can use "PlugPlug sync" to only wait for the current queues without doing anything else.

Many commands can be suffixed with "now" to cancel the existing queue and active pattern immediately. See the plugin help text for more information.

About Parameters:

     <multiplier>
         # A decimal number, scalar and unit-less.

     <on-duration>
         # The playback duration of the pattern, in seconds.

     <off-duration>
         # The pause between patterns.

     <pattern>
         # A pattern definition.

     <required-count>
         # An integer.

There are two possible types of patterns:

- Constant strength (decimal numbers from 0 to 1), for example 0.9
- More complex patterns defined using the letters A through Z (case-insensitive) as well as the . character. 'A' will use the lowest possible non-zero intensity, 'Z' will use the maximum intensity (1.0) and '.' turns off vibration.

A single pattern is applied to all vibration features at once. Otherwise, linear interpolation is used to distribute the patterns across the device, and the strongest influence at each feature "wins".

Examples:

     PlugPlug vibe start 0.3 0 0.5
         # Constant half intensity.

     PlugPlug vibe pulse 1 0 0.8 0
         # 1-second pulse with constant 80% intensity,
         # concenctrated on the first motor.

     PlugPlug vibe start 2.5 0 ZZZ...ZZ....ZZZ...
         # Strong pulsed vibration.

     PlugPlug vibe start 5 0 Vbvbvbvbvb..
         # Alternating strong and weak vibration, with a pause at the end.

     PlugPlug vibe pulse 10 0 mm...mm
         # Two slow medium strength vibrations, with a pause.

     PlugPlug vibe start 1 2 rrrrrrrr
         # Relatively strong vibration,
         # but it is not recommended to unnecessarily repeat the pattern.

     PlugPlug vibe start 3.0 0 X.X.X.X.X. Y.Y.Y.Y.
         # Two patterns in parallel, with mismatched timings.
         # (The total duration will be the same.)

     PlugPlug vibe pulse 0.5 0 0 abfjmpsvyz
         # A curved ramp pattern,
         # concentrated on the last motor.

Oscillators and vibrators behave differently in response to input changes! In most cases, it's necessary to test with and fine-tune both separately for each scene!
Note that Intiface now supports customising the range of output values, so usually you should still make use of the full range even if your test device doesn't behave well at low intensities.

The durations likely won't be entirely accurate and timings may drift a bit, as I tried to make sure the game keeps running no matter what.

It's now easier to use multiple patterns/multiple motors: Patterns are automatically interpolated across devices with differing feature count! Where a device has mixed features (like oscillators that also vibrate), the interpolation happens over each group separately since buttplug can automatically split the features.

JS API:

     All commands are available through the global `PlugPlug` object.
     Just concatenate the command identifiers and pass all parameters in parentheses.

For example:

     `PlugPlug.config.vibe.strength(0.8);`
         # Set global vibe strength multiplier.

     `PlugPlug.connect();`
         # Connect to all devices.

     `PlugPlug.vibe.start(3, 2, 0.2, 'Vb.vb.vb.vb.vb.');`
         # Play back the patterns 0.2 and `Vb.vb.vb.vb.vb.`
         # focused on the first and last features of each device,
         # stretched over three seconds,
         # then pause for two seconds. Repeat indefinitely.

Blocking commands return promises, which means you can wait on their completion from JavaScript.

What about RPG Maker MZ?

There are plugin command declarations for RPG Maker MZ.

What about (linear, rotation…)?

While it would be easy to add additional commands for those interactions, as they are already supported by Intiface, I don't have any test devices for those features.

I'm not comfortable with releasing software that controls mechanical actuators without testing it thoroughly.

How to make a configuration menu?

A configuration menu for players is now included! Please direct them to the Options menu, which will have an additional entry by default when using this plug₂in, or use the PlugPlug config command to show this screen directly.

You can modify this menu by adjusting the global Scene_PlugPlugOptions and Window_PlugPlugOptions classes, or replace it entirely by hooking PlugPlug config and/or proving your own Options menu entry.