Battler Flipbook Events Core MV + MZ

This plugin provides add-in infrastructure to enhance Battler Flipbooks animations by attaching synchronised callbacks and resources to preload.

Requires Battler Flipbooks Core.

This is a core-only plugin. To use it, additional JavaScript plugins are required.

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

The functionality of this Core can be expanded by "B.Fl.Ev. Add-in" plugins, which should be loaded before all "B.Fl. Layer"-plugin or other controllers.

This page here describes common features usually usable in combination with all Events add-in plugins. For added functionality provided by add-ins and other dependent plugins, see each plugin's own page instead:

Battler Flipbook Events Core Cheat Sheet

Note Tag Location

In each Flipbook Animation's Note.

Note Tag Syntax

By default: <condition:key:parameters>, where

• condition is one of:
  1. An integer like 0, interpreted as the targeted timeline frame, with the intro before 0 and mapping each repetition onto the same single-repeat range directly followed by the outro, or
  2. a decimal number generally from -1.0 up to and including 2.0, interpreted as tSections threshold where 0.0 is the start of each repetition and 1.0 is the start of the outro, or
  3. a Boolean JS expression.
     • Shorthands, including the layer's, are normally available here.
• key is a unique identifier for the type of callback event.
  • See event add-ins for specific options.
• parameters is passed to the event add-in for further interpretation.
  • May contain additional :.

Whitespace around each part is discarded ahead of further tag processing.

General Hints

• Callbacks within each Note are all evaluated each frame in order of their appearance in the Note, so when using decimal numbers as conditions and two events trigger on the same logical animation frame, their effects are ordered top-down instead of by the value their conditions are parsed as.
  • Try to write tags in the same order that you expect the animation events to trigger whenever possible.
• Unless you need perfectly frame-aligned timing, prefer a decimal number over an integer as condition, as the former usually doesn't have to be adjusted when you change the frame delay of an animation.
• Even when animations are played back at a fractional speed, their frames and callbacks advance in integer animation frame steps. Frame advances are not skipped when fast-forwarding or due to performance-related engine frame render skips, so callback events will trigger reliably barring outside interference.
• Callbacks at 2.0 (or just below, falling on the same frame) or the integer frame index one past the last outro frame trigger when the animation is cleared naturally from reaching its end, on the first visible frame of the battler's following animation or default image.
• Callbacks at *above* -2.0 and at *at most* 2.0 (with decimal part), or at 0 (without decimal part), or using a JS expression like true as condition, are called even for empty animations.
• Tags are collected once when each Flipbook and Animation is created, usually when a Battler Flipbooks layer plugin is loaded. To add additional callbacks dynamically, please use this plugin's JavaScript API.

Caution

Refer to each event add-in plugin's documentation for more information on memory use and optimisation options.

Callback Arguments

These identifiers are available in the condition and may be available as part of expressions inside the event tag parameters, depending on the Events add-in implementing that tag. (See individual add-ins for details.)

Callback arguments are calculated only once each logical animation frame for all events which are present on one active battler animation.

Category	Type	Identifier	Explanation
animated sprite	Sprite_Battler | undefined	sprite	This should be unavailable only under rare circumstances, but it may happen.
animated battler	Game_Battler	battler
battler index	number	index	This is battler.index(), the index of battler within their own party. Should be an integer ≥ 0.
current animation	FlipbookAnimation	animation
timing info¹	number	frame	Logical animation frame index, negative during the intro. Here an integer.
		timelineFrame	Same as frame, but each repeat occupies the same range starting at 0, followed directly by the outro.
		tSections	Fractional number from -1.0 to 2.0, where the intro spans -1.0 to just before 0.0, each repeat spans 0.0 to just before 1.0 and the outro spans 1.0 to just before 2.0.
		tFull	A fractional number from 0.0 to just before 1.0, tracking the progress through the animation's full undisturbed runtime.
		tSectionsBeforeFrame	Like tSections, but calculated from timelineFrame - 1 instead of timelineFrame<code>.
other		...callbackArgs	Other callback arguments supplied by the specific Battler Flipbooks layer or an add-in plugin. These may replace any of the above, though that too should be documented in the respective plugin.

¹ Timing info values may fall outside the given ranges when observed under different circumstances (usually through additional plugins)!
Timing info values may skip or not reach all values when an animation is interrupted. frame and tFull are likely to skip part of their unrolled repeating section after an animation is scheduled to end early.

Load Order

This plugin requires and must be loaded after TS_Battler_Flipbooks_Core.

Event add-ins (usually "B.Fl.Ev. Add-in") must be loaded after this plugin and should be loaded before all plugins that instantiate the Flipbooks runtime (usually "B.Fl. Layer"s).

Recommended load order for my Battler Flipbooks plugins:

Filename	Description
TS_Battler_Flipbooks_Core	…
…	(B.Fl. Add-in) …
TS_Battler_Flipbook_Events_Core	(B.Fl. Add-in) …
…	(B.Fl. Events Add-in) …
…	(B.Fl. Layer) …

All add-ins should be loaded before all layers (that they should interact with), as they may be used during layer instantiation.

The order of add-ins usually doesn't matter.

Layers should be ordered from least to most situational - for example, you should load "Entrance Flipbooks" first and then "Reaction Flipbooks" below it, so that the latter has higher priority and can correctly interrupt a battler's default idle loop (if Entrance Flipbooks is used that way).

Plugin Parameters

Tag prefix:

Require a specific (RegExp!) sequence at the start of each animation event callback tag, just before condition in the note tag format above.

For example, if you set this to event *:, the space character before * can appear any number of times, so the format of animation callback event note tags changes from <…:…:…> to, for example, any of <event:…:…:…> or <event :…:…:…> or <event :…:…:…>.

Plugin Commands

This plugin does not expose any plugin commands.

JavaScript API

This plugin unconditionally sets the global variable TS_Battler_Flipbook_Events_Core when first loaded, through which all API members are available. For detailed JS API endpoint documentation, please refer to the JSDoc comments included with the source code of this plugin.

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, 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.

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 acquired at https://tamschi.itch.io/battler-flipbooks-core .

Once you have acquired it, you may redistribute and sublicense this plugin file as part of games you create. You may not 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.

Additionally, you may redistribute this file alongside its matching .d.ts file, both only unchanged and free of charge under this same license, as long as you at least equally present the above link as the original download location as alternative to your copy of this file and make that link freely available without any additional login or membership requirement compared to viewing any advertisement of your copy of this file.