Battler Entrance Flipbooks MV + MZ

This plugin allows you to animate battlers newly entering into battle. You can also use it to set up one basic looping sprite animation per battler per battle.

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 pause/delay the message window and/or first turn while the intro of a non-hidden battler's animation is playing. This is configurable per flipbook.

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.)
• BattleManager.setup: Applies Entrance Flipbook rules at the very start of battle.
  • However, animations are generally paused for hidden battlers.
• Secondary Hooks:
  • Window_Message.prototype.update: To optionally pause/delay messages.
  • BattleManager.updateTurn: To optionally delay turns.
  • Game_Battler.prototype.removeState:To end or clear animations early.
  • Scene_Battle.prototype.terminate: To reset preload-related state.

JS Callback Arguments

Unchanged from Battler Flipbooks Core.

Shorthands

Unchanged from Battler Flipbooks Core.

General Hints

• Start simple! Even a two- or three-cel entrance can look great if displayed for the right amount of time.
• The enemy effect 'appear' is blocked by entrance flipbooks by default. You can re-enable the fade-in for an enemy that appears half-way into the battle by selecting the Block effects: parameter in their entrance flipbook and pressing the delete key on your keyboard to remove its value.
• For short entrances, 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 entrance animations.
• 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, unless the hue feature is modified to use the cached default-hue bitmap and a shader effect to change the hue!

Ideas

• You can use the battler's index in the shorthand or JS condition to set up alternatives with subtly different timing or speed. This lets you avoid identical enemies moving in sync.
  • Note that the relative start timing of distinct animations can vary due to their resources becoming available at different times.
    
• To exclude battlers from animating under a specific condition, you can use a higher-priority rule with an empty or deleted flipbook. You can use this rule for any number of distinct battlers, or even all of them at once.
• Rules can be based on battler equipment, so you can also use this to replace your actor sprites based on what they are wearing.
  • To do this, use a single cel for the animation's repeating section and set the repeat limit as high as possible.

Load Order

Battler Entrance 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.

Plugin Parameters

Entrance Rules...

Defines rules by which to apply entrance flipbooks to battlers, at the very start of battle.

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 entrance 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 entrance 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), Battler Entrance 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.

Plugin Commands

This plugin does not expose any plugin commands.

JavaScript API

This plugin unconditionally sets the global variable TS_Battler_Entrance_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 entranceRules property is aliased to runtime.rules.

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

EntranceHomeOverride, EntranceAnimation, EntranceFlipbook, EntranceRule, EntrancesRuntime

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.

oldSetup, oldWindow_MessageUpdate, oldUpdateTurn, oldTerminate, oldRemoveState,
newSetup, newWindow_MessageUpdate, newUpdateTurn, newTerminate, 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 EntranceRuntime 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/battler-entrance-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.