Occasional Battler Flipbooks MV + MZ

This Battler Flipbooks layer plugin can trigger animations whenever the specified battler-related JS functions are called. This means you can use it to set up simple unsynchronised action, damage, miss, evade, counter, reflect, knock-out, defeat and victory animations for both enemies and actors, to give a few examples.

Requires Battler Flipbooks Core.

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.

It's possible to delay a battler's next action while such an occasional animation is playing on them, to delay specific battle steps during any animation's intro to give it more breathing room and impact, and/or to shorten animations to preserve a concise flow of battle. This can be chosen for each flipbook separately. The animation can similarly also be stopped when a turn ends.

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.)
• User-specified "occasions": Used to trigger animations.
• User-specified "scopes": Can be used to further specify when exactly  rules can be applied.
• Secondary Hooks:
  • Game_Battler.prototype.removeState: To end or clear animations early.
  • TS_Battler_Flipbooks_Core.canAnimate: To animate even knocked-out enemies while an occasional flipbook is applied to them.
    (This also affects layers with higher priority to some extent.)
  • Sprite_Enemy.prototype.initVisibility: To keep defeated enemies visible while animated.
  • Window_BattleLog.prototype.callNextMethod: To delay battle steps, and to end or clear animations early.
  • Game_Battler.prototype.onTurnEnd: To end or clear animations early.

JS Callback Arguments

(+ all from Battler Flipbooks Core)

Purpose	Identifier	Type
Triggering occasion¹	occasion	string
Contexts when triggered¹	contexts	string[]

¹ Normalised to remove trailing comments and surrounding whitespace and to elide prototype.

Shorthands

Unchanged from Battler Flipbooks Core.

Animation Callback Arguments

Unchanged from Battler Flipbooks Core.

General Hints

• Start simple! Even a two- or three-cel animation can look great if displayed for the right amount of time.
• If a recursive function is used as occasion, then the rule is reapplied on every recursion level. You can avoid this by adding that same function to the same rule as excluded scope (in which case only the outermost call to it applies the rule, and no conditions further than the scope are tested for any nested recursive calls).
• For short flipbooks, 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 animations as needed.
  • 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

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!

The suggested occasions from Game_Unit, Game_Party and Window_BattleLog may behave not as expected, as they are often called in multiple circumstances or unconditionally!

RPG Maker MZ triggers the Game_Battler..select occasion in additional circumstances compared to RPG Maker MV, including for defeated enemies, which can cancel another animation unexpectedly if used. If this is the case then you can filter by battler state or use flipbook tags to disable the rule with the Game_Battler..select occasion when it would conflict.

Ideas

• To create a custom collapse animation for enemies, block the collapse, bossCollapse and/or instantCollapse effects in the flipbook you want to use, and use Game_Battler..performCollapse as the occasion.
• You can use the various Game_Battler..perform… functions as occasions to distinguish between a number of different battle events, like being missed by an action (Game_Battler..performMiss) or just having counter-attacked (Game_Battler..performCounter).
  • The Window_BattleLog..display… functions are also worth looking at and may offer better timing in some cases.
• The BattleManager.invoke… functions can be used as scopes to filter Window_BattleLog..display… occasions, for example to select only normal action use (BattleManager.invokeNormalAction, as opposed to BattleManager.invokeCounterAttack or BattleManager.invokeMagicReflection.)

Load Order

Occasional Battler Flipbooks must be loaded after Battler Flipbooks Core, and should be loaded after any general Flipbooks add-ins and after status pose plugins like YEP_X_WeakEnemyPoses.

Load Occasional Battler Flipbooks after Battler Entrance Flipbooks to have priority over entrance/idle animations.

Plugin Parameters

Occasional Rules...

Defines rules by which to apply occasional flipbooks to battlers, at the end of calls to the specified function(s).

Conditions are organised into filter blocks which can be enabled separately.
See (nested) parameter help for further details.

Remove state to end:

Iff set to a state, then the "Remove State" effect or command can be used to shorten the active occasional 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 occasional 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.)

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_Occasional_Battler_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 occasionalRules property is aliased to runtime.rules.

Individual rules are hydrated into OccasionalRule 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 OccasionalRule instances as long as they are instances of the core plugin's FlipbooksRule class.

OccasionalHomeOverride, OccasionalAnimation, OccasionalFlipbook, OccasionalRule, OccasionalRuntime

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.

normalizeTarget(target: string): string

Removes comments and trims spaces around identifiers. Elides prototype.

This function is read-only to avoid a desync between installed hooks and calls made later by other plugins.

callWithContext<T>(context: string, callback: () => T): T

The tracker shim inserted for context hooks. You can use this to track active contexts, simulate contexts or to temporarily deactivate a context by replacing the logic of this function with just return callback();.

contextHooks, occasionHooks

Hooks installed according to the unique normalised context and occasion targets. Each hook is associated with two properties, with keys starting with old: or new: followed by the normalised target of the hook.

Note: I don't recommend creating hooks programmatically for this plugin.

oldCanAnimate, newCanAnimate

Functions associated with core 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!

oldRemoveState, oldInitVisibility, oldCallNextMethod, oldOnTurnEnd,
newRemoveState, newInitVisibility, newCallNextMethod, newOnTurnEnd

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 OccasionalRuntime 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, 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/occasional-battler-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.