Battler Flipbook Sound Effect Events MV + MZ

This plugin allows you to add sound effects to Flipbooks animations through flipbook animation event note tags. This even works for zero-duration animations that have no frames at all, by setting the condition to `0`, `true` (= each frame + end) or any number with decimal point larger than `-2.0` and at most `2.0`.

Requires Battler Flipbook Events Core.

This is an add-in-only plugin. To use it, at least one Battler Flipbooks layer is required.

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

Sound effects are either empty or consist of a name or parametrised sound expression and any trailing named modifiers. Modifiers are separated by spaces, while parenthesised arguments are separated by commas. (See examples below.)

All modifiers are optional. The cheat-sheet lists their defaults in the overview.

Battler Flipbook Sound Effect Events Cheat Sheet

Common Modifiers

These are accepted by any except the empty sound.

pan=0

Pans the sound the given number of percentage points to the right.
(Negative integers pan to the left.)

pitch=100

Multiplies the sound's pitch with the given percentage.

volume=100

Multiplies the sound's volume with the given percentage.
Defaults to 90 for sound files.

Built-in Sound Expressions

(only whitespace)

Empty/no sound. Defaults to `volume=0` and does not support modifiers.

AnyName123

A sound effect file name without extension or the name of a shared sound. May not contain whitespace.

random(A, B, C, …)

Chooses one of its arguments at random each time.

rotate(A, B, C, …)

Cycles between its arguments.

shuffle(A, B, C, …) shuffle=2

Like random, but picks from the first few arguments and moves the picked one to the end, to avoid close repetitions.

The `shuffle` modifier value is an integer and defaults to half the number of arguments rounded up.

autoPan(A) panStrength=100

Automatically pans the sound left or right according to the position of the battler sprite on screen.

This is calculated only after fully evaluating the sound expression; this expression just creates an `autoPan` property on the returned sound effect data or adds to it according to the given `panStrength`.

Using explicit `autoPan(…)` avoids the effect of `<se-autoPan>` for that sound.

Examples

These assume that no animation event tag prefix was set and that the default event key is used.

<0:se:Absorb1>

Plays the sound 'Absorb1' on the first frame after the intro.
If a repeating part exists, then the sound plays for each repeat.

Defaults to `volume=90` if it refers to a file rather than a shared sound.

<-1.0:se:Absorb1 pan=-10 pitch=110 volume=40>

On the first frame of the intro, plays the sound 'Absorb1'.
Iff there is no intro, then it will play on the first frame of the repeating part, and so on.

The sound is panned 10% to the left, pitched up 10% and its volume is reduced to 40%. Each of these three modifiers is optional and can be used with any built-in sound expression except "no" sound.

<0.0:se:shuffle(A1, A2, A3, A4) shuffle=3>

On the first frame of each repeat, randomly plays one of the first three sounds in its argument list, while moving it to the end of the list.
Iff there is no repeating part, then it will play on the first frame of the outro, and so on.

This causes the sounds to play in a random order but not twice the same in a row. The `shuffle` modifier defaults to half the argument count rounded up.

<1.0:se:>

On the first frame of the outro, plays the silent empty sound.
Iff there is no outro, the silent sound will instead play when the animation ends.

<2.0:se:random(A,,) volume=10>

On average a third of the time when the animation ends, plays sound "A".

In the other two thirds of cases, a silent empty sound is played then.

<-2:se:random(rotate(A pan=-20, A pan=20),)

On the second to last logical animation frame of the intro, with a 50% chance, plays sound "A".
Iff the intro has less than two cels, this sound will not play at all.

The sound alternates between being panned left and right whenever it does play.

<Math.random() < 0.01:se:B>

Each logical animation frame, play sound "B" with a 1% chance.

General Hints

• The default volume may be pretty loud. In most cases, you should reduce it a lot, especially for sounds that are played often.
• Use randomness to break up repetition!
• When using shared sounds, their state is shared between all uses. That means that if you use `rotate(…)` or `shuffle(…)`, their rotations/shuffling is global between all uses of the shared sound.
• The effective playback volume of flipbook sound effects is clamped to the range -100 to 100 (inclusive).

Caution

• Each sound file can be played only once at a time per battler. Playing it again before it ends will stop the previous sound, even if it was constructed by a different sound expression.
• Events are checked in definition order during each frame, so if for example `<2.0000:se:A volume=10>` and `<1.9999:se:B volume=20>` are used in the same animation in this order, then the latter will under most circumstances immediately override the former in the same frame, causing the sound to play only at volume 20.
• To avoid loud noises, each sound file can only be started once each rendered frame by this plugin. If a sound would be doubled-up this way, the second playback is dropped silently even if its parameters differ.
  However, even with these safety measures in place, sounds with matching constant tones or the same sound pitch-shifted slightly may still align if played in parallel starting on different frames. Try to use sounds with these properties only in ways where they won't play in parallel.

Load Order

This plugin (Battler Flipbook Sound Effect Events) must be loaded after Battler Flipbook Events Core.

The included More Shared Sound for Battler Flipbook Sound Effect Events must be loaded after this plugin if it is used.

Flipbook layers that make use of sound effect events must be loaded after either plugin.

Plugin Parameters

Volume:

Volume multiplier applied to all flipbook animation sound effects events enabled by this plugin.

Note that while it's possible to set this up to 500 (percent), the volume of individual sound effects is still limited to 100% during playback.

Pan multiplier:

A percentage multiplier that adjusts the pan of all animation event sound effects. This can also be set to negative values to flip the direction, but there are likely few uses for it.

The general "Pan multiplier:" also affects panning by `autoPan`, but the strength of that can multiplicatively also be adjusted with the child parameter "autoPan multiplier:".

Shared sounds:

A list of pairs of names and reusable sound expressions. These can be used in place of sound file names in other sound expressions.

Only the first expression associated with a name is used, and only shared sounds that were defined previously can be used in later expressions.

Hint: You can shadow a sound file to set up some presets for it. For example, this will reduce the volume of Absorb1 to 40%:

• Name: Absorb1
• Expression: Absorb1 volume=40

As the shared sound "Absorb1" is not yet visible in its own expression, the "Absorb1" there still refers to the sound effect file of that name.

Hint: Sound expression types implemented in other add-ins aren't available in Battler Flipbook Sound Effect Events's "Shared sounds:" yet.
If you would like to use custom sound expression types, then define your shared sounds using More Shared Sounds for Battler Flipbook Sound Effect Events later/further down in the plugin load order, but still before any layers that use them.

Used sounds:

Use this list to declare all sound effect files that you use in animations.

This technically isn't required for this plugin to work, but ensures that "Exclude unused files" won't discard audio used only in this way. It also helps with validation, though the associated console messages can be controlled (turned off) using the child parameters.

If any validation issue was printed to the debug console (press F12 during playtest), then an additional message with the suggested value for the "Used sounds:" parameter will be shown there. However, this value is only reliable if there was no error up to that point.

Note that the check for unused "Used sounds:" entries is delayed for a few seconds to give the game time to load.

Event key:

By default the `se` in `<0:se:NameOfSound>`.

You can adjust this to distinguish between this and another Battler Flipbook Events add-in that also tries to use `se` as event key.

Auto-pan tag:

When this tag is present in an animation's note, then sound effects played by that animation are auto-panned by default with strength 100.

For example, if the sprite is at the left edge of the screen, and no `autoPan(…)` expression is used for that sound, it will be panned to the left 100%. A sprite at the right edge has its sounds panned right 100%, and anything in-between is interpolated.

If no sprite can be found for the battler that the animation is playing on, then no auto-pan is applied in general.

Plugin Commands

This plugin does not expose any plugin commands.

JavaScript API

This plugin unconditionally sets the global variable TS_Battler_Flipbook_Sound_Effect_Events 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.

`version` is independently also present in `TS_More_Shared_Sounds_for_Battler_Flipbook_Sound_Effect_Events` iff that plugin is used.

parameters

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

Note that the `sharedSounds` property is not hydrated in place (so that it's later still possible to figure out where and how they were defined). You can instead find the live shared sound collection at `SharedSound.sharedSounds` in this plugin's API.

`parameters` is independently also present in `TS_More_Shared_Sounds_for_Battler_Flipbook_Sound_Effect_Events` iff that plugin is used, though only the nested `sharedSounds` property is available there.

InstantiableAudioManager

Using the engine's `AudioManager` singleton as base prototype, this class is instantiated for each battler to manage audio resources.

Note that anything related to music is just forwarded to `AudioManager`.

Sound, NoSound, OneSound, RandomSound, RotateSound, ShuffleSound and SharedSound

Sound expression classes, with more specific implementations being derived from `Sound`. For example, `random(…)` creates a `RandomSound` and `rotate(…)` creates a `RotateSound`.

You can add your own sound expression type by creating a derived class and hooking `Sound.parse` or change their behaviour through method overrides.
If you do so, note that you likely will have to define shared sounds later on in the plugin load order, using the included More Shared Sounds for Battler Flipbook Sound Effect Events plugin.

getAudioManager(battler: Game_Battler): InstantiableAudioManager

Retrieves the audio manager used for a given battler, creating it if it doesn't already exist. These audio managers are discarded at the end of each battle.

oldTerminate, oldRender,
newTerminate, newRender

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.

Note that `render` is hooked on either `Graphics` (MV) or `PIXI.Application.prototyp` (MZ) depending whether `Graphics.render` exists.

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!

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.

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-flipbook-sound-effect-events .

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.