Battler Flipbooks Core MV + MZ

This plugin provides infrastructure to temporarily replace a battler's sprite with a flipbook animation, loading these animations reliably, and for transitioning between the animations seamlessly.

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.

There should be enough documentation, including basic parameter structure definitions, to DIY a controller for your use-case if you're familiar with RPG Maker MV or MZ plugin development and JavaScript classes, but I hope you will still consider my premade add-in and layer plugins for this system. They are priced in a way that buying them should be immediately worth the time you save on the initial implementation of each provided feature.

This page details common functionality implemented by the Core, which is shared by most of my layers (here in recommended load order):

• Conditional Battler Flipbooks: TBA

• Battler Idle Fidget Flipbooks: TBA
• Battler Action Flipbooks: TBA

Additional features can be made available to all layers at once by add-ins like the following:

• Battler Flipbooks Delay Loaded: TBA

• Battler Flipbook Callback Events: TBA
• Meta Conditionals for Battler Flipbook Events¹: TBA

¹ Event conditionals are technically possible with just the core, so this will be about making them easier to write and providing composable meta events. This won't be included with the Events Core due to the feature's relative complexity.

(I am splitting these up and staggering the release to make this system more affordable and easier for me to manage. The whole project is multiple hundred hours of work, so basic access would be too expensive for my taste if priced reasonably in a single package.)

General Hints

• You can double-click the divider between the Name and Status columns to see the full plugin names quickly.
• Start simple! Even a single-cel pose can look great if displayed for the right amount of time.
• For short or fast animations, use smaller differences or less detailed cels.
  • For larger pose changes and more complex animations, make sure the frames are visible long enough that someone less familiar with them can parse most of them!
  • If the animation appears very often, you can use a short cel delay 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!
• Shorthand expansions are not customisable in the plugin parameters, but are usually easy to edit in the respective plugin source code.
  • Search for expandShorthand.
  • You can use https://regex101.com/ to debug regex expressions if you select ECMAScript mode there.

Flipbooks Core Cheat Sheet

Timing / Hooks

Largely determined by dependent plugins, but resources are released automatically on Scene_Battle.prototype.terminate (i.e. whenever a battle ends).

JS Callback Arguments

Purpose	Identifier	Type
Who or what may be animated?	battler	Game_Battler
Which are they?	index	number

Shorthands

Category	Subcategory	Identifier	Type
Game State¹	Switches	Sw…²	boolean
	Variables	Var…²	number
battler	State	St…², isDeathStateAffected, isDualWield, isAutoBattle, isGuard, isSubstitute, isPreserveTp, isHidden, isAppeared, isDead, isAlive, isDying, isRestricted, isConfused, isActor, isEnemy	boolean
Options	canInput, canMove, canAttack, canGuard	boolean
Buffs & Debuffs¹	mhpBuff, mmpBuff, atkBuff, defBuff, matBuff, mdfBuff, agiBuff, lukBuff, anyBuff	number
Buff State¹	mhp…, mmp…, atk…, def…, mat…, mdf…, agi…, luk…, any… …Is… …BuffAffected, …DebuffAffected, …BuffOrDebuffAffected, …MaxBuffAffected, …MaxDebuffAffected, …BuffExpired	boolean
Properties	hp, mp, tp, mhp, mmp, atk, def, mat, mdf, agi, luk, hit, eva, cri, cev, mev, mrf, cnt, hrg, mrg, trg, tgr, grd, rec, pha, mcr, tcr, pdr, mdr, fdr, exr	number
Phase¹	isSelected, isUndecided, isInputting, isWaiting, isActing, isChanting, isGuardWaiting	boolean

¹ Translated to method calls.
² where … is an integer.

Animation Callback Arguments

These are  available in the Home override... coordinate expressions, in addition to the general JS Arguments and Shorthands.

Category	Type	Identifier	Explanation
animated sprite	Sprite_Battler	sprite
current animation	FlipbookAnimation	animation
timing info³	number	frame	Logical animation frame index, negative during the intro.
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.

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

frame and timelineFrame may well be non-integer numbers (except during BattlerFlipbookState..advance, as noted by plugins where this matters)!

Filter Infrastructure

The following filters will usually be available across layer plugins to determine which flipbook is applied to a given battler in the respective situation:

• By actor or enemy, directly or by custom note tag.
• By tags of the preceding flipbook (globally across layers).
  • Also exclusions.
• By equipped weapon(s), also by type(s), optionally also for enemies.
• By equipped armour(s), also by type(s), optionally also for enemies.
• By States the battler is affected by.
  • Also exclusions.
• By Switches.
  • Also exclusions.
• By free-form shorthand and/or plain JavaScript condition.

Effect Infrastructure

The following optional side-effects are available across most of my layer plugins, configurable per flipbook:

• Flipbook tags, a powerful system to determine which animations can follow and interrupt each other.
  • This gives you nearly the power of animation state machines in more generic game engines, in terms of transitioning animations smoothly into each other.
• Sprite home position override according to a formula, either additive or absolute.
• Cycle interruptions of lower-priority layers, allowing you to e.g. jump into a flinch without delay but transition out of it seamlessly into an idle animation.
• Blocked sprite effects, like 'whiten', 'blink', 'collapse', 'bossCollapse' and 'instantCollapse'. This stops the engine from interfering with your animated enemies.
• Blocked sprite motions, like 'guard', 'spell', 'skill', 'item', 'thrust', 'swing', 'missile', 'damage', 'evade', 'victory' and 'escape'. This turns off specific side-view actor spritesheet animations when needed.

Animation Infrastructure

Each animation is normally made up of three parts, each (or all!) of which may be empty and can have distinct frame delays:

• an intro
• a repeated middle section (with configurable repetition limit)
• an outro

Battler Flipbooks Core provides a consistent animation timeline interface for use by add-ins and layers alike and can dynamically shorten an animation by omitting further repetitions, which makes it easier to create controller plugins that maintain the flow of battle.

Additionally, the common playback speed of animations can be varied dynamically alongside RPG Maker's built-in fast-forward feature or by hooking this plugin's API's static speed getter, even at fractional rates, without affecting individual animation playback logic.

Animations' resources are reserved and loaded in the background during each battle, and playback can configurably wait until the respective animation is ready, so playback is reliable without increasing initial battle load times.

Caution

This is not a video sprite streaming plugin. This means that using a large number of distinct animation frames can require a large amount of memory. (Reused cels are reused even across distinct layers, however.)

Refer to each controller plugin's documentation for more information on memory use and optimisation options.

Load Order

This plugin (Battler Flipbooks Core) must be loaded after any plugins that reimplement the battle system from scratch, like YEP_BattleEngineCore or (most likely) VisuMZ_1_BattleCore.

Layers should be loaded after status pose plugins like YEP_X_WeakEnemyPoses to have higher priority than them.

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

Default speed:

Multiplier for how quickly to play flipbook animations by default during battle.

There can be a little (sub-frame) drift when animations end if using speeds that aren't a whole-number fraction of 1, but this shouldn't be noticeable.

Fast-forward speed:

Multiplier for how quickly to play animations, applied when fast-forwarding during battle. (By default when holding "Shift" or "Enter".)

There can be a little (sub-frame) drift when animations end if using speeds that aren't a whole-number fraction of 1, but this shouldn't be noticeable.

Limit frame skip:

Limits performance-related frame skipping done by the RPG Maker renderer during battle.

This does not affect the game or animation logic, but may be helpful to avoid visually missing cels at high animation frame rates.

Iff enabled, use the "Limit:" parameter to control how many game frames may still be skipped for each frame that is shown on screen. This should be lower than the lowest animation frame delay you want to ensure is visible.

Plugin Commands

This plugin does not expose any plugin commands.

JavaScript API

(You can skip this part unless you'd like to make custom layers or add-ins.)

This plugin unconditionally sets the global variable TS_Battler_Flipbooks_Core when first loaded, through which all API members are available.

For detailed JS API endpoint documentation, please refer to the type annotations and JSDoc comments inside the .d.ts file for this plugin.

The plugin source is unobfuscated and not precompiled, so it should be very readable too, if necessary.

For Layers

You can find an example layer plugin under CC0 here on GitHub, which should make it easier to get started.

• Layers should create derived classes extending each of HomeOverride, FlipbookAnimation, Flipbook, FlipbooksRule and FlipbooksRuntime.
  • BattlerFlipbookState should usually not be extended this way.
  • Override the static methods at the top of each class to introduce the derived classes to each other, where applicable!
• FlipbooksRule can be initialised from parsed plugin parameters - there are matching RPG Maker plugin parameter structures and a decodeParameters helper function to get you started in this regard.
  • I recommend adding parameters that control conditions to the rule and parameters that control effects to the flipbook structure, to keep everything consistent between different layer plugins.

Once the rules are hydrated into live objects, the layer can instantiate its runtime class using these rules and any additional parameters. It should then expose an API containing its parameters, class constructors, hooks (for example as ...core.makeHook(() => api, …),, if this plugin here is available as core and the constructed hook holder will be api) and any other methods necessary to interact with and extend that plugin.

Note: When overriding methods, make sure to still call the super. method even if it is empty! This ensures that add-ins will function correctly with your layer plugin.

For Add-ins

Add-ins will generally hook the core's API methods to change their behaviour or add features that should be available in all layer plugins.

Hint: The .prototype.initialize methods are good places to parse note tags only once. Make sure that your custom code executes *after* the original implementation, then examine this.note. Like with the other validated properties, you can assume that this field will have been initialised to its correct type at this point.

Hint: If needed, you can also use .prototype.initialize to late-hook other prototype methods to manipulate their derived implementations. However, if you do so, make sure to apply the hook only once for each this.constructor and to use a recursion flag to avoid running your hook twice! Additionally, please do expose a method that other plugins can hook to subscribe to your hook holder objects if you do go ahead with this approach.

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

Additionally, you may copy and relicense the plugin parameter structure definitions below (That is: the block comments beginning with `/*~struct~`), as long as you, nearby in your plugin source code, mention their origin and point out your modifications.

hi! Thank you for the great script. Is it possible for you to make a video showing how to use this? I'm not sure how to apply what's inside the tool. Do I need to download something else besides this Core? Please understand that I am using a translator.

@base TS_Battler_Flipbooks_Core

@param rules
@text Rules...
@desc Animation rules for actors and enemies. The first full match is used.
@type struct<FlipbooksRule>[]
@default []

'use strict';

const core = TS_Battler_Flipbooks_Core;

const parameters = PluginManager.parameters(NAME_OF_THE_LAYER_PLUGIN);
core.decodeParameters(parameters);

class MyRule extends core.FlipbooksRule {
    // Custom conditions can be added here.
}

// Hydrate rules from decoded parameter objects:
parameters.rules = parameters.rules.map(dpo => new MyRule(dpo));

// Using a derived runtime with its own name improves error messages:
class MyRuntime extends core.FlipbooksRuntime { }

// Create the runtime instance:
const runtime = new MyRuntime({
    rules: parameters.rules,

    // Other options. I normally have these in parameters, but this are okay defaults:
    enableHomeOverride: false, // Use `true` to use "Home override..." function!

    // These make the Layer work better with some other plugins:
    compatibilityTweaks: true,
    spriteSizeTweak: true,
    spriteSizeTweakUsePoseForPointer: true,
    spriteActorUpdateAppearTweak: true,
    spriteActorUpdateDisappearTweak: true,
});

const api = window.MyPlugin = {
    ...core.makeHook(() => api, BattleManager, function setup() {
        const result = api.oldSetup.apply(this, arguments);

        for (const battler of BattleManager.allBattleMembers()) {
            runtime.applyRules(battler, {}); // <- You can pass named parameters here.
        }

        return result;
    }),
};

const oldSetup = BattleManager.setup;
BattleManager.setup = function () {
    const result = api.oldSetup.apply(this, arguments);

    for (const battler of BattleManager.allBattleMembers()) {
        runtime.applyRules(battler, {}); // <- You can pass named parameters here.
    }

    return result;
};