Battler Reaction Flipbooks MV + MZ

This plugin allows you to animate battlers targeted by actions (items and skills) using flipbook animations, and provides access to a large amount of contextual information about the action. This means you can use it to set up specific and varied contextual action, damage, miss, evade and knock-out animations for both enemies and actors. However, counter, reflect, defeat and victory animations can not be triggered by this plugin, as the batter does not become an effective target of an action in those cases.

Requires Battler Flipbooks Core.

In cases where only simple, less differentiated reactions are needed, Occasional Battler Flipbooks is a great alternative at a lower price.

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

A battler's animation can be stopped at any point by removing either of the respective states chosen in the plugin parameters from them. The states do not have to be present first for this to take effect.

In most cases, no scripting or note tags are required (Flipbook rules can be set up using only the mouse.) and cels are chosen in a way that allows you to use the "Exclude unused files" option when deploying your game.

If that alone isn't flexible enough, it's also possible to use custom JavaScript or shorthand conditions, as well as to change (or reuse parts of) the behaviour of this plugin using further JavaScript plugins.

For information about baseline Flipbooks features, please see the Battler Flipbooks Core plugin.

Battler Flipbooks Layer Cheat-Sheet

Timing / Hooks

(Cache management is inherited from Battler Flipbooks Core.)

Reaction Flipbooks are applied when Game_Action.prototype.apply ends, which is what applies a battle action's effects like damage.
Some context for rules' conditions is captured at the beginning of this method instead.

Secondary Hooks:

• Game_Battler.prototype.onTurnEnd: To end or clear animations early
• Game_Battler.prototype.removeState: To end or clear animations early
• Window_BattleLog.prototype.callNextMethod: To delay battle steps, and to end or clear animations early.

JS Callback Arguments

(+ all from Battler Flipbooks Core)

Purpose	Identifier	Type
what?	action	Game_Action
who?/whom?	subject, target, battler (=== target)	Game_Battler
properties²	numRepeats, numTargets, speed³	number
chance²	itemCnt, itemMrf, itemHit, itemEva, itemCri	number (fractions)
effectiveness²	elementRate, lukEffectRate	number (ratio)
usefulness²	hasItemAnyValidEffects	boolean
outcome	result (= target.result())	Game_ActionResult

Shorthands

Category	Subcategory	Identifier	Type
Game State	(unchanged from Flipbooks Core)
Battler/Target	(unchanged from Flipbooks Core)
Action (intention)	Category¹	isSkill, isItem, isForOpponent, isForFriend, isForDeadFriend, isForUser, isForOne, isForRandom, isForAll, isHpEffect, isMpEffect, isDamage, isRecover, isDrain, isHpRecover, isMpRecover, isCertainHit, isPhysical, isMagical, isAttack, isGuard, isMagicSkill, isValid, needsSelection	boolean
Result (may have been effected indirectly)	Outcome	used, missed, evaded, physical, drained, critical, success, hpAffected, statusAffected¹, hit¹	boolean
State Added/Removed¹	st+[id], st-[id], ko+, ko-	boolean
Buffs¹ & Debuffs¹	mhp…, mmp…, atk…, def…, mat…, mdf…, agi…, luk…, any… …Is… …BuffAdded, …DebuffAdded, …BuffRemoved	boolean
Damage Values (negative if healed)	hpDamage, mpDamage, tpDamage	number

Animation Callback Arguments

Unchanged from Battler Flipbooks Core.

¹ Translated to method calls.
² Theoretical effective value, taken once at hooked method's start.
³ May be inaccurate due to variance.

General Hints

• Start simple! Even a two- or three-cel reaction can look great if displayed for the right amount of time.
• For short reactions, use smaller differences or simpler animations.
  • For larger pose changes and more complex animations, make sure they are visible long enough that someone less familiar with them can parse most of them!
  • If an animation appears very often, you can use a short duration with more detail to keep it interesting, but still, make it easy to get the gist.
• You can duplicate cels with Ctrl+C, Ctrl+V to display them longer than others in the same list. This does *not* hurt performance!
• If you configure a state in "Remove state to end/clear:", you can use "Remove State" in skill and item effects (and elsewhere) to shorten or cancel reactions.
  • A good alternative to clearing by removed state is to set up another rule that applies an empty flipbook whenever its occasion and conditions are met.
• Shorthand expansions are not customisable in the plugin parameters, but are easy to edit in the source code. (Search for expandShorthand.) You can use https://regex101.com/ to debug them if you select ECMAScript mode there.
  • Alternatively, you can extend the common shorthand expansion defined in Battler Flipbooks Core with another plugin before loading this one.

Caution

All required images for visible battlers are *cached automatically* (but only iff the respective rule's battler filters can be met by battler participants), so that this plugin won't cause flickering or slow-downs due to cache churn on the web or when the game runs from a slow hard drive.

However, if a rule targets all actors or all enemies (an empty list in either slot), then its poses are kept loaded in memory during ALL battles!
To counteract this, or if a reaction will be used only in a few situations, specify a subject filter using the parameter marked with "*", as this allows the plugin to exclude the rule from battles where it isn't needed, reducing memory use and load times.

Setting the hue of a flipbook-animated battler to a value other than 0 is very likely to cause performance issues in MV, unless the hue feature is modified to use the cached default-hue bitmap!

Ideas

• You can use the tag system to vary the reaction to the 1st, 2nd, 3rd… hit in a multi-hit attack, even if the outcome is the same, as long as each animation is still playing during the next hit. Just tag the first flipbook for example Hit1 and require that same Hit1 in the second rule, and so on.
  • Make sure the follow-up rules have higher priority than the first one by placing them above the latter!
• If you write hpDamage > 0 && isDying in a rule's shorthand condition, then you have created a damage reaction rule that applies only to battlers with low health (checked with damage applied).
  • Conversely you can write hpDamage > 0 && isAlive && !isDying for damage reactions at higher health percentages.
• You can write for example hpDamage > mhp * 0.2 to create a rule for attacks that deal more than 20% damage in a single hit.
• To make a reaction rule remove the current reaction flipbook, you can use a flipbook with no animation frames. You can even delete the flipbook entirely from the rule by pressing 'Del' on your keyboard when the value is selected, which has the same effect.
  • Be sure to set 'Interrupt paused cycles?' to OFF for such rules to prevent visual glitches if no reaction is playing!

Load Order

Battler Reaction Flipbooks must be loaded after Battler Flipbooks Core, and should be loaded after after status pose plugins like YEP_X_WeakEnemyPoses.

Load Battler Reaction Flipbooks after Battler Entrance Flipbooks and Battler Action Flipbooks to have priority over entrance/idle and action animations, respectively.

Plugin Parameters

Reaction Rules...

Defines rules by which to apply reaction flipbooks to battlers targeted by an action in battle. The first rule applies that is enabled and has its requirements met just after the action becomes effective.

Conditions are organised into filter blocks which can be enabled separately.
Please have a look at the screenshots to see the full list of conditions available easily in the parameters GUI. More complex conditions not covered by the specific filters can be written as JavaScript expressions or using the available shorthands listed above.

Individual filter parameters generally have a default "Either"/empty option. Number filters use a threshold system and come with a handy dropdown, so for example hp/mp/tp damage conditions like ">0" or "≤-100%" are only clicks away. Custom numbers are also possible.

Remove state to end:

Iff set to a state, then the "Remove State" effect or command can be used to shorten the active reaction animation on a battler, skipping further loop cycles and transitioning to the outro as soon as possible. The state does not have to be present first: The intent to remove it if present is enough to end the animation.

(Affected by effect probability: The animation is only scheduled to end if the state would actually be removed.)

Remove state to clear:

Iff set to a state, then the "Remove State" effect or command can be used to clear the active reaction animation from a battler. The state does not have to be present first: The intent to remove it if present is enough to remove the animation immediately.

(Affected by effect probability: The animation is only cleared if the state would actually be removed.)

Clear on hide?

Immediately clears the active reaction flipbook from battlers which are hidden using their .hide() method.

Enable 'Home override'?

Whether a battler sprite's _homeX and _homeY properties should be hooked, to enable dynamic battler position changes. This is more likely to cause conflicts than other parts of the plugin, so it's optional.

Require enemy weapons? and Require enemy armors?

These parameters can be used to enable weapon and armor filters, respectively, also for enemies.

However, this is only possible iff .weapons() and .armors() methods, respectively, are added to enemies by another plugin to match actors' API! Enabling these enemy restrictions otherwise can easily crash the game.

Compatibility tweaks?

Iff enabled (as group and individually), Occasional Battler Flipbooks will adjust other plugins' features for more polished results and to avoid glitches.

See the individual parameters for more information.

Each tweak only applies if its targets are detected when this plugin is first loaded, and does nothing otherwise, so they are enabled by default.

JavaScript and Shorthand Conditions

These are JavaScript boolean expressions that, if set, must evaluate to a truthy value for the respective rule to apply to a given battler.

Please see the "Battler Flipbooks Core Cheat-Sheet" in that plugin's help for information on which local identifiers are available in addition to the ones listed above.

Plugin Commands

This plugin does not expose any plugin commands.

JavaScript API

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

There, the following properties are available:

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.

parameters

Parsed plugin parameters, with trailing _ and _files stripped from property names. Values of string properties (originally with trailing _) are trimmed.

The reactionRules property is aliased to runtime.rules.

Individual rules are hydrated into ReactionRule instances. The shorthand and JS conditions are present as functions, therein, and missing arrays and strings are added as empty. Boolean properties are normalised to true or false.

You may inject rules that are not ReactionRule instances as long as they are instances of the core plugin's FlipbooksRule class.

ReactionHomeOverride, ReactionAnimation, ReactionFlipbook, ReactionRule, ReactionsRuntime

Derived classes for this Battler Flipbooks layer, exposed for reuse and modification. Static members and .initialize are used only during initialisation, so changes to them aren't effective for existing rules.

Please see the individual classes' documentation for more information.

oldApply, oldOnTurnEnd, oldHide, oldCallNextMethod, oldRemoveState
newApply, newOnTurnEnd, newHide, newCallNextMethod, newRemoveState

Functions associated with engine hooks installed by this plugin (see above), where old… has the original implementation and new… this plugin's.

The hooks are installed with a small trampoline, which means that changes to these properties are effective at the respective position in the call chain.

Hint: You can temporarily disable a hook by overriding its new… function with its old… version. Prefer using a hook construct with a conditional branch for this purpose instead of changing these properties dynamically!

runtime

The instance of ReactionsRuntime used by this plugin.
Its API is identical to Battler Flipbooks Core's FlipbooksRuntime.

Hooks installed by the core runtime are available as properties of this instance similar to the above.

Compatibility Notes

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

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

This plugin is compatible with YEP_BattleEngineCore (v1.51), as long as it is loaded after that battle engine.

Compatibility with VisuMZ_1_BattleCore (Version 1.73) is likely, but hard to judge conclusively due to its obfuscated source code. (Not great.)

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/battler-reaction-flipbooks .

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.