CE Plugin Commands and Scoped Variables MV

With this plugin for RPG Maker MV, you can make Common Events callable as Plugin Commands, with parameters passed in the same line. You can also scope Variables, Switches and JavaScript globals to the current Command list interpreter and its children, so that changes there don't affect other code and vice versa.

No JavaScript required! Common Events whose names start with the configured "CE Plugin Command Prefix" become available automatically as Plugin Commands.

CE Plugin Commands shadow Plugin Commands of the same name if the latter are provided by a plugin that is located earlier in the load order than this one.

What you can do with this

• Write more concise code, and have your Common Event calls checked automatically as they run:
  • You can pass booleans, strings and integers inline as literal arguments after the name of the CE Plugin Command, and you can also pass the values of Variables and Switches (both by ID and name) and JavaScript expressions.
  • Not-passing a required argument or trying to use a Variable or Switch that does not exist causes an Error, which is fast and easy to track down. You can similarly ensure not too many arguments were given.
• Easily use recursion!
  • Variables, Switches and JS Globals can be scoped at any layer of the Command script call stack, not just at the root of CE Plugin Commands.
  • They don't interfere up or down into other versions of themselves, even if created in the same Common Event.
    • (However, do note that any hooks set on Variable or Switch changes will still trigger, and will additionally trigger in many cases where a Command list using them takes multiple frames to complete. This is not an issue in vanilla RPG Maker MV, but may interfere with other plugins that observe such changes.)
• Use temporary variables for independent parallel execution:
  • Each parallel call stack has its own copies of scoped variables, so you can start a Common Event many times at once and not worry about cross-talk between them.
  • The scoped version of Variables, Switches and global JavaScript variables are discarded when exiting the Command list that created them.

Command Syntax

(Each argument without <> or []. The name of each built-in Command is configurable.)

• scopedVar <Variable ID or name without spaces> [function parameter ID] [default]
• scopedSwitch <Variable ID or name without spaces> [function parameter ID] [default]
• scopedJsGlobal <Variable ID or name without spaces> [function parameter ID] [default]
• limitArgs <maximum count (number)>
• <Common Event name without Command Prefix (trimmed)> [...args]

In this list, <>-arguments are required and []-arguments are optional.

A ce plugin command name must not contain spaces.

Arguments are interpreted as follows, in order of decreasing precedence:

123 or +123 or -123	An integer or ID.
true	Boolean true/Switch ON.
false	Boolean false/Switch OFF.
singleWord (not starting with {)	A text string containing only that word.
{:quoted string}	A string that may contain spaces, without the leading :. Ends with the first } not followed by a non-space character.
{var:n} or {var:Variable Name}	The value of Variable with ID n or the first variable called* "Variable Name".
{switch:n} or {switch:Switch Name}	The value of Switch with ID n or the first switch called* "Switch Name".
{js:JS expression}	Evaluates JS expression as expression in a strict mode JavaScript Function body.

* Variable and Switch names are trimmed before the lookup, so the name of the Variable or Switch must not start or end with whitespace characters like spaces.

Loading a non-boolean into a Switch using scopedSwitch first converts the value into a real boolean by JavaScript truthiness rules. See https://developer.mozilla.org/en-US/docs/Glossary/Truthy for more information.

It's possible to load string arguments into Variables. You can use this to insert words or short phrases into text shown to the player.

Plugin Parameters

All parameters are annotated with meta data to provide in-editor explanations.

• CE Plugin Command Prefix (string): Common Events whose names start with this prefix are callable as CE Plugin Commands.
• scopedVarCmd (string / Plugin Command name): Used to scope Variables.
• scopedSwitchCmd (string / Plugin Command name): Used to scope Switches.
  
• scopedJsGlobalCmd (string / Plugin Command name): Used to scope global JavaScript variables (that is: properties of window).
  
• limitArgsCmd (string / Plugin Command name): Only valid in a CE Plugin Commands that was called as such. Throws if there are more arguments than indicated.
  
• Use scoped Vars in messages? (boolean): If true, \V[n] escape sequences in messages are replaced earlier, when the message is scheduled by the Command. This ensures that messages will "see" scoped variables visible at, for example, their respective Show Text command.
  

Compatibility Notes

This plugin was tested on RPG Maker MV 1.6.2. It uses only the public RPG Maker API, so it should have good future compatibility throughout minor engine updates (i.e. those that don't change the first digit of the version number).

Should there be an issue in the future, please let me know so that I can develop a fix!

f you develop on Windows and deploy for Linux, you must first update the NW.js runtime in the nwjs-lnx folder to at least version 0.29.4 (to match other targets, but ideally use the newest stable version)! You can find more information and a tutorial for this here. It's fast, easy, and also fixes many other problems for your players.