Party Command Hooks MV + MZ

With this plugin, you can automatically store information from Commands in the "Party" category into Switches, Variables and Actors' Names.

You can also have each flip a Switch to ON unconditionally, and specify a Common Event for each to run as handler immediately after the Command.

Additionally, this plugin comes with systems for custom Note Tag data channels and a basic but flexible auto-pluraliser that supports exceptions.

Before deploying for Linux on Windows, you must update MV's NW.js runtime.

Ideas

• You can use this plugin to create templates for, for example, "gained gold" and "received item" messages with very powerful customisation options, including icons and custom text via note tags.
  You can also use the Flag system to reduce how many Common Event slots you need for handlers and combine multiple distinct messages into one template.
  The following message styles are feasible without added JavaScript or item-specific logic this way:

  +------------------------------+
  | Received 3x ⒶBlueberry Twig |
  +------------------------------+
  +--------------------------------------+
  | Gained 5 Gold and 3 Ⓑ Soccer Balls! |
  |                                      |
  | Use this item in battle to start a   |
  | friendly soccer match!               |
  +--------------------------------------+
  +-----------------------------+
  | Thief Arsène Lupin (Lv. 99) |
  | has joined the party!       |
  +-----------------------------+

  (Ⓐ and Ⓑ are stand-ins for Item Icons.)
• You can compare the Variables for "Amount →Ⓥ" and "Actual →Ⓥ" to check for inventory overflow in "Change Items...", "Change Weapons..." and "Change Armor..." Commands!
  If they differ, use a Script Command like $gameParty.gainItem($gameVariables.getValue(●), $gameVariables.getValue(●)); to remove added items, where ● must be replaced by the Variable IDs used for "ID →Ⓥ" and "Actual →Ⓥ" respectively.

Hints

• By separating the lines of a Description, Profile or Note Tag content, you can prefix escape codes before each line. You can use this to display the entire message at once, for example.
• You can also add escape codes to the inserted strings, of course.
• If you write \N[\V[X]] (without backticks) in messages, this is replaced by the Name of the Actor whose ID is read from Variable X, where X must be an unsigned integer. \I[\V[X]] is, where supported, replaced with an Icon whose index is read from Variable X.
• Configured Note Tags can simultaneously control a Switch and grab text or a (generally integer) numerical value, so you can set up distinct logic for special cases.
• You can also use Note Tags with a default to configure articles like a\+[n<<aeio] (Crown) vs. the (King's Crown) conveniently, and to declare classifiers or counters like つ with variants like 本 or 冊 for individual database entries.

Caution

• If there are fewer lines of text than "Lines →Ⓐ" Actors, the Names of the remaining Actors are set to the empty string. If there are more lines than Actors, then not all lines are assigned to Actors.
• Switches are unconditionally set for each Plugin Parameter independently, in order of their appearance, so if one appears in multiple Note Tags for the same Command, then only the last one is observable by Events this way.
  • Party Command Hooks validates its Parameters more thoroughly during Playtest startup and will raise an error if any IDs are reused in a way that's known to cause problems this way.
  • However, it is fine to reuse Switches, Variables and Actors between distinct categories to reduce the number of slots used, as long as you don't plan to combine messages.

Load Order

Party Command Hooks can be loaded at any time. However, if another plugin modifies the effect of a "Party" Command, this modification is more reliably detected if Party Command Hooks is loaded after that plugin.

If you use any plugin that can make Commands in the "Party" category not-instant, then load Party Command Hooks after that plugin!

When in doubt, load Party Command Hooks relatively late.

Expansions

Where noted, this plugin supports the following text expansions:

%%	%
%1	For plurals: Replaced with the singular form. For note tag contents: Replaced with the database entry's Name.
\+[suffix>text]	Iff %1 would end with suffix, then text.
\+[^suffix>text]	Iff %1 would *not* end with suffix, then text.
\+[text<prefix]	Iff %1 would start with prefix, then text.
\+[text<^prefix]	Iff %1 would *not* start with prefix, then text.
\+[abc>>text]	Iff %1 would end with a, b or c, then text.
\+[^abc>>text]	Iff %1 would *not* end with a, b or c, then text.
\+[text<<abc]	Iff %1 would start with a, b or c, then text.
\+[text<<^abc]	Iff %1 would *not* start with a, b or c, then text.

The following characters can not appear in prefix, suffix, text or abc, but may be accepted later on with a minor version update: ^<>/\+-=

Note that the + in \+ above can be replaced by any character sequence except \, the empty string, or a string with leading or trailing spaces using the "Joiner Escape:" plugin parameter.

Plugin Parameters

<plural> Note Tag

Controls which case-sensitive Note Tag to use to set an individual plural Expansion, if any. You can just specify the individual plural directly as in <plural>bison</plural>, but all Note Tag contents also support Expansions.

Plural Rules...

General plural overrides that consist of a Singular and Plural, as well as a Note field that has no effect at runtime with this plugin alone.

The Singular can be verbatim or a JavaScript RegExp literal (/●/●) matched against the singular form. The first matching override is used, iff the chosen <plural> Note Tag was not found in the relevant database entry.

The Plural field supports the Expansions above. Iff Singular is a RegExp literal, then the following replacement string escapes applied before other expansions and escape codes are also supported:

$$	$
$&	The matched substring.
$`	The part of the singular before the match.
$'	The part of the singular after the match.
$n	The (1-indexed) nth RegExp capture group's capture. n must be a non-zero unsigned single or double-digit integer <100.
$<name>	The capture of the RegExp capture group named 'name'.

 (This *almost* matches the behaviour of String.prototype.replace, but not quite: Out-of-bounds double-digit n does not fall back to single-digit, but you can still use e.g. $012 to insert the first capture followed by a literal 2. Second, undeclared named-capture inserts, like out-of-bounds indexed-capture inserts, appear verbatim in the output even if other named capturing groups exist, in order to make mistakes more clearly visible during playtests.)

Joiner Escape...

In case of a conflict, you can replace the + used for prefix- and suffix-conditional Expansions (see above) with a custom literal sequence, or erase it entirely to deactivate these Expansions.

As with all string parameters, leading and trailing whitespace is trimmed.
A single backslash (\) can *not* be used as joiner escape.

--- Change Gold ---, --- Change Items ---, --- Change Weapons ---, --- Change Armors ---, --- Change Party Member ---

These Note parameters only serve as headings for the respective Command hook and are not parsed, but they are still exposed through the JavaScript API (see further below).

Slots and Handlers

Some of the following parameters appear with the same name under multiple headings, but their function is equivalent, so they are listed only once.

Parameters with →Ⓢ designate a Switch slot that is written to, →Ⓥ marks a Variable slot and →Ⓐ an Actor Name slot.

All slots are written to in the order they are listed in whenever the respective Command is used! This includes Note Tags.

Increase? →Ⓢ, "Add"? →Ⓢ

Set to whether the Command is set to "Increase" the item or equipment amount held by the party or to add a party member.

ID →Ⓥ

Set to the database ID of the Item, Weapon, Armor or Actor that is added or removed from the party.

Initialized? →Ⓢ

Set to whether the Actor was (re)initialised by "Change Party Member...".

Membership Changed? →Ⓢ

Set to whether the Actor's party membership changed from the Command.

Name →Ⓐ

Set to the Name of the Item, Weapon or Armor that is added or removed.

For the added/removed Actor's Name, please use \N[\V[●]] instead, where ● should be the slot ID used for "ID →Ⓥ".

Plural →Ⓐ

Set to the expanded plural of a "Name →Ⓐ", "Weapon Type →Ⓐ", "Armor Type →Ⓐ", "Equipment Type →Ⓐ" or "Class Name →Ⓐ".

Default:

Configures the default expansion pattern to form a plural within the respective category. By default this will append -s or -es to the singular.

See "Expansions" above.

Icon →Ⓥ

Set to the database entry's Icon's index number.
Expand with \N[\V[●]] where ● is the Variable ID specified here.

Description →Ⓐ, Profile →Ⓐ

Set to the database entry's full Description or, for Actors, Profile.

Lines →Ⓐ

Multiple Actor Name slots that are each set to one of the parent parameter's lines (split by \n), in order. If there are not enough lines, all remaining slots are set to the empty string.

Weapon Type →Ⓐ, Armor Type →Ⓐ, Equipment Type →Ⓐ

Set to the name of the weapon-, armor- or equipment-type, respectively.

Class Name →Ⓐ

Set to the Actor's Class's Name.

Amount →Ⓥ

Set to the calculated intended change amount, i.e. potentially the value retrieved from a variable. Without further plugins or manual data file edit, this will always be a positive integer.

Actual →Ⓥ

The same as "Amount →Ⓥ" but reflecting the actual effective change (including equipment changes, where applicable).

The resulting value differs from "Amount →Ⓥ" if the party had fewer of the removed thing than intended, or had so many already that adding the intended amount would have taken it past the inventory limit.

Equipped →Ⓥ

The same as "Actual →Ⓥ" but counting only party equipment changes.

Level →Ⓥ

Set to the specified Actor's level as of *after* the "Change Party Member" Command.

Note Tags...

Define custom Note Tags here, which can be used to retrieve additional data from the database entry's Note. (In the case of Actors, their Class's Note is also searched iff the tag wasn't found in the Actor's Note directly.)

This is an array of struct parameters with the following sub-parameters:

Note:	A Note parameter just to take notes. Does nothing.
<…> Note Tag:	Determines the name of the tag to look for.
Present? →Ⓢ	Set to whether the Note Tag was found in the Note.
Value →Ⓥ	Iff the tag-enclosed text is an integer (which may be signed), then set to that value. Otherwise set to 0.
Text →Ⓐ	The tag-enclosed text, or the "Default:" iff there was only an opening but no closing tag.
Lines →Ⓐ	As with the top-level "Lines →Ⓐ" parameters, the lines of "Text →Ⓐ".
Default:	The default value to use for "Value →Ⓥ", "Text →Ⓐ" and "Lines →Ⓐ" iff the tag is missing or has no matching closing tag. Does not affect "Present? →Ⓢ".

The text between the first <…> and the next </…>, where … is the Note Tag's configured name verbatim, is the "tag-enclosed text".

It is trimmed and supports "Expansions" (see above).

Flag: ON→Ⓢ

Unconditionally set to ON/true when the hooked Command is run.

Handler: Ⓒ

A Common Event called immediately after the hooked Command completes. This only runs if the Command actually completed (which is always the case immediately with the unmodified engine, but a plugin could change this).

Plugin Commands

This plugin does not define any Plugin Commands.

JavaScript API

This plugin unconditionally sets the global variable TS_Party_Command_Hooks when first loaded.

There, the following property and functions are available:
(See source code comments for more detailed type information.)

version

Semantic Version-compatible featureLevel and patchLevel information.

I don't reset the patchLevel to 0 when incrementing featureLevel, so that patchLevel alone is enough to determine whether a certain fix is available in each version.

This property is frozen and the object is frozen.

parameters

Parsed plugin parameters, with _-suffixes removed from property keys.

Missing arrays and strings are added as empty, here, and Boolean properties are normalised to true or false.

Slot and handler IDs default to 0.

This property is frozen, but the object is mutable.

BattleCommandDescription

Class that parses and evaluates structural plugin parameters. It's possible for other plugins to extend this class to create more advanced behaviour programmatically. Please refer to the source code for more information.

This property is frozen, but the class is mutable.

SingularPlural, NoteTag

Classes that parse and evaluate structural plugin parameters. It's possible for other plugins to extend these to create more advanced behaviour programmatically. Please refer to the source code for more information.

These properties are frozen, but the classes are mutable.

oldCommand125, oldCommand126, oldCommand127, oldCommand128, oldCommand129, newCommand125, newCommand126, newCommand127, newCommand128, newCommand129

Functions associated with Command hooks installed by this plugin. The hooks use a small "trampoline" that calls the "new…" function, so you can skip the hook very precisely using another plugin when needed.

The numbers refer to Commands as follows:

125	Change Gold
126	Change Items
127	Change Weapons
128	Change Armors
129	Change Party Member

makePlural(singular, pluralDefault, ...notes): string

The function used to pluralise the given singular. In decreasing priority, this will use the expansion pattern specified in:

1. the Items's, Weapon's, Armor's or Actor's Note,
2. the Actor's Class's Note,
3. the first applicable override from "Plural Rules...",
4. the relevant "Default:".

expand(pattern, name): string

This function expands pattern using the specified name and the configured parameters.joinerEscape.

countPartyEquips(dataObject): number

A helper function to count how much of a database entry the party has equipped. Called twice each for relevant hooks, it influences both "Actual →Ⓥ" and "Equipped →Ⓥ".

setSwitch(switchId, value),
setVariable(variableId, value),
setActorName(actorId, value)

These functions are used to write values to the configured slots. They are called unconditionally even if the configured ID is 0.

setUpCommonEvent(interpreter, commonEventId)

Called to set up a child Game_Interpreter to execute a "Handler: Ⓒ".
This is called even if commonEventId is 0.

oldRequestImages, newRequestImages

Only present if Game_Interpreter.requestImages was already available.

Functions associated with hooking the recursive Event resource preloading present only in MV, not in MZ. (MZ only loads resources when setting up an interpreter, which is invoked implicitly during "Handler: Ⓒ" calls.)

Save Contents

This plugin does not store any additional save data.

Compatibility Notes

This plugin was tested on RPG Maker MV 1.6.3 and RPG Maker MZ 1.7.0, uses only the public RPG Maker API as far as possible, and does not use any platform-specific APIs.

This plugin installs only transparent hooks that cannot interfere with other plugins' functions, barring collisions of the "Handler: Ⓒ" functionality. In such cases, please call the intended Common Event manually instead.

This plugin should be compatible with any deployment target available for RPG Maker MV and MZ, including web and most custom ones.

If you notice issues or glitches in combination with other plugins, please tell me about them, and I'll check if a compatibility tweak is feasible.

Copy of License Grant

(as included in the plugin file, aside from line wrapping)

A license for this plugin can be purchased at https://tamschi.itch.io/party-command-hooks .

Once you have purchased it, you may redistribute and sublicense this plugin file as part of games you create. You may not redistribute nor sublicense it separately or as part of an asset- or resource-collection.

You may modify this plugin when including it with your games, as long as the attribution above and this license grant stay intact. If you do so, you must add comments to indicate which changes you made from the original.

Social Media

If you'd like to help me out a bit, I'd hugely appreciate if you could share this page with others who may be interested in this plugin. To make that more convenient, I've created a few social media accounts for updates and announcements:

Announcement on Mastodon (via Elk), Announcement on Bluesky
(Just a moment please, I haven't quite posted these yet.)

I'll continue to post all important updates here on itch.io, of course, and the comments below remain the easiest way to reach me if you have any questions or bug reports.