Dynamic Pictures MV + MZ

📚 This plugin is $4.95 off for owners of Dynamic Characters, as they have some parts in common. Use Dynamic Actors (free) to control both at once.

📈 Please note that due to the increase in features in version 1.2.4, the price of this plugin will increase to $20 for new purchases on February 22. (In essence, this is a week-long sale on the new update, in case you decide to buy a license specifically due to the modifiers and/or increased JavaScript API surface.)

With this plugin, you can use rules to apply replacements and additional layers and eased modifiers (opacity, transforms, tint, blend mode) to Pictures. Shown Pictures continue to update live according to the defined rules, and this is guaranteed to not flicker even if the image isn't loaded yet.

You can also use the +ReplacePicture (MV/MZ) or Replace Picture (MZ) plugin command to change which (base) image is shown without affecting other aspects of the Picture, like ongoing movement or current modifier state.

Rules are applied in order, top to bottom, so that each rule can react to the tags added by previous rules. You can also use the AddPictureTags (MV), RemovePictureTags (MV) and Change Picture Tags (MZ) plugin commands to preset tags for a currently shown Picture. This preset disappears when the Picture is entirely overwritten or erased.

You can use the Z-Index parameter to change the order in which the layers appear, though the default of showing them front-to-back above the original base layer(s) should work unmodified in many cases.

Modifiers are usually controlled by rules, but you can temporarily override this using the FlashPictureModifiers (MV) / Flash Picture Modifiers (MZ) and LapsePictureModifiers (MV) / Lapse Picture Modifiers (MZ) plugin commands.

You can also wait for modifiers to stabilise using the plugin commands WaitForPictureModifiers (MV) or Wait for Picture Modifiers (MZ).

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

Ideas

• If you separate equipment into an image with the same dimensions as your character Pictures, you can use this plugin with character conditions to have your characters wear it in dialogue scenes.
• If you have a condition that becomes true irregularly, you can use this to have blinking characters in your dialogue scenes, by adding or hiding the difference as a layer.
  • Note that writing such a condition with a pattern that looks good can be tricky and depends on your game's individual style to some extent.
• You can use enemy and actor conditions with shorthands like isChanting or isActing to make parts of the scene respond to the flow of battle.
• Tint modifiers can be used to easily create consistent speaker highlights in dialogue scenes, for example according to a Variable being switched. These will always animate cleanly even when rapidly fast-forwarding.

Hints

• Space your z-indices a bit so that it's easier to insert something in-between layers later on.
  • In case you didn't, you can also use text mode to set a rule's z-index to a number with more decimal places.
• Layers are deduplicated automatically. The topmost copy of each remains.
• If layer dimensions differ, the resulting Picture is sized to fit the largest along each axis and layers are top-left aligned.
• You can use the target name placeholder %1 in added layers to show different images depending on the target.
  • This way, you can for example use just one rule for a piece of armour, even if different characters and/or poses are involved.
  • If multiple are present initially, the top-most target layer is used.
• You can apply many modifiers to the same Picture at once! They animate independently and their components are combined as needed.

Caution

• "Targets:" and "Hide Layers:" don't automatically require files for the purpose of "Exclude unused files". You can make a rule without targets to mark files as used.
• The "Preload?" flag is quite aggressive and loads/reserves layers along with any of the rule's targets, so it shouldn't be used if a target image is used with "Show Picture" or "Replace Picture" in unrelated situations or the precise timing isn't as important.
  • Layers do not desync just because some aren't loaded yet.
  • To preload (and in MV reserve) specific images, you can add unreachable "Show Picture" commands to the same Event script.
• A non-identity "Tint..." may cause performance issues in RPG Maker MV while it is being animated (due to "In-Duration" or "Out-Duration" greater than 1 or frequent change of whether the modifier applies to a Picture).

Notes

• RGB tint transitions are not linear in RPG Maker, but rather linear in sRGB space (gamma ~2.2). As this plugin does not use custom shaders, hues may shift slightly during transitions.
• RGB tint is additive as it uses the native sRGB tint feature.
  Greyscale however is inversely multiplied in (not necessarily linear) HSL.
• By default, the bottom-centre of the Picture is used as anchor point for transform modifiers, as convenience for dialogue portraits. You can quickly change this to the centre by copy-pasting the "50" from "Anchor X:" over to the "Anchor Y:" parameter (without navigating into either; it works in the list view too).

Load Order

Dynamic Pictures should be loaded relatively late, in order to have priority when splitting and merging Picture file names. It may have to be loaded before some other plugins that manage Pictures more coarsely.

Plugin Parameters

+ReplacePicture Command,
AddPictureTags Command,
RemovePictureTags Command,
FlashPictureModifiers Command,
LapsePictureModifiers Command,
WaitForPictureModifiers Command

You can use these parameters to rename the MV-style plugin commands in this plugin, in case there's a collision. MZ-style commands are unaffected.

Picture rules...

Rules to add and/or hide layers for certain targets (initial layers), based on conditions checked every frame.

Rules are indexed by target and conditions are precompiled when the game starts, so this should stay fast even with hundreds or thousands of rules overall.

See the parameter help and the JavaScript- and Shorthand Conditions sections below for more information.

- Layer Separator -

A character or sequence of characters used to separate layers in picture file names. This shouldn't appear in the names of picture image files you want to display.

You can erase this parameter, in which case the text TS_Dynamic_Pictures__Separator will be used.

Modifier definitions...

Named modifiers that can fade, transform and tint Pictures and override their blend mode. Please note that some operations are sensitive to the order in which they are applied, like skew, rotation and scale with distinct anchor points.

Each modifier has an associated "Easing" like "linear(0, .25 75%, 1)" or "ease-in-out", as well as an "In-Duration" and "Out-Duration" (in frames), which control the timing of the modifier's transitions.
All standard CSS easing functions available in Firefox 112 are supported.

Which modifiers are active for a given Picture is controlled declaratively by "Picture rules..." and (as temporary overrides) by the FlashPictureModifiers (MV) / Flash Picture Modifiers (MZ) and LapsePictureModifiers (MV) / Lapse Picture Modifiers (MZ) commands.

- Round offsets at rest? -

Advanced feature. Turn OFF to fully disable offset rounding. Defaults to ON.

Offset rounding is used to ensure transforms at rest (i.e. fully or not at all applied, without pending transition) are always aligned with the pixel grid as well as possible, to not unnecessarily blur Pictures. This could otherwise occur also due to for example scaling or skewing transforms and at certain rotation angles.

(In order to avoid jitter, transitioning transforms never round offsets.)

Compatibility tweaks?

Tweaks for compatibility with certain other plugins.

These are generally enabled by default, as they should have either no or unnoticeable impact when the other plugin isn't present, but are optional.

JavaScript Conditions

Rules and battler conditions can contain JavaScript conditions, which should be boolean expressions.

In these expressions, target refers to the file name (without extension) that the rule is being applied to, tags is an array of symbols and strings containing the currently applicable tags.

In actor and enemy conditions, battler refers to the Game_Actor or Game_Enemy that the condition is examining.

This means you can for example write (battler.hp / battler.mhp) <= 0.5 in a battler condition to only apply the picture rule while the selected battler is at or below 50% of their maximum HP. (See the next section for a shorter way to write this rule!)

End-of-line comments (with //) are allowed in JS and shorthand conditions.

Shorthand Conditions

Rules and battler conditions can contain "shorthand conditions", which are a convenient way to write JavaScript conditions more concisely. For example, here (in an actor or enemy condition) you can even write (hp / mhp) <= 0.5 for the same effect as above!

This is because, inside shorthand conditions, the following identifiers are available, in addition to the target, tags and, in battler conditions, battler also present in JavaScript conditions:

Sw… and Var…, not following ., where … is a series of digits

These identifiers are expanded into getting the state of the numbered Switch or value of a Variable.

battler state

Similarly to Sw… and Var… above, St… can be use to check whether the battler is affected by the specified state.

Additionally, the following boolean identifiers can be used directly (and are expanded into method calls):

isDeathStateAffected, isDualWield, isAutoBattle, isGuard, isSubstitute, isPreserveTp, isHidden, isAppeared, isDead, isAlive, isDying, isRestricted, isConfused, isActor, isEnemy

battler buffs & debuffs

The following evaluate to the respective buff level as number, where level 0 is neutral:

mhpBuff, mmpBuff, atkBuff, defBuff, matBuff, mdfBuff, agiBuff, lukBuff, anyBuff (= the sum of all other buff levels)

You can also get booleans according to the following pattern:

mhpIs…, mmpIs…, atkIs…, defIs…, matIs…, mdfIs…, agiIs…, lukIs…, anyIs…
…MaxBuffAffected, …BuffAffected, …DebuffAffected, …MaxDebuffAffected, …BuffOrDebuffAffected, …BuffExpired

battler options

Use these booleans to check a battler's options in combat:

canInput, canMove, canAttack, canGuard

battler properties

The following properties of battler can be used as if they were local variables:

• hp: Hit Points
• mp: Magic Points
• tp: Tactical Points
• mhp: Maximum Hit Points
• mmp: Maximum Magic Points
• atk: ATtacK power
• def: DEFense power
• mat: Magic ATack power
• mdf: Magic DeFense power
• agi: AGIlity
• luk: LUcK
• hit: HIT rate
• eva: EVAsion rate
• cri: CRItical rate
• cev: Critical EVasion rate
• mev: Magic EVasion rate
• mrf: Magic ReFlection rate
• cnt: CouNTer attack rate
• hrg: Hp ReGeneration rate
• mrg: Mp ReGeneration rate
• trg: Tp ReGeneration rate
• tgr: TarGet Rate
• grd: GuaRD effect rate
• rec: RECovery effect rate
• pha: PHArmacology
• mcr: Mp Cost Rate
• tcr: Tp Charge Rate
• pdr: Physical Damage Rate
• mdr: Magical Damage Rate
• fdr: Floor Damage Rate
• exr: EXperience Rate

battler phase

These change as phases of the battle progress or based on player input:

isSelected, isUndecided, isInputting, isWaiting, isActing, isChanting, isGuardWaiting

isChanting and isGuardWaiting are true while the battler isWaiting to perform a magic or guard skill, respectively.

Plugin Commands

+ReplacePicture

The next "Show Picture..." command *in the same event script* only replaces the image file shown for the given Picture, and does not modify any of its other properties.

This feature makes use of Picture buffering, so the Picture will not flicker while it loads. Replacing a picture this way also does not reset the tags applied to it by "AddPictureTags" or "Change Picture Tags".

Replace Picture (MZ)

Functions like "+ReplacePicture" followed by "Show Picture...".

This is just an easier way to write this combination that takes advantage of MZ's better plugin command UI.

AddPictureTags number ...tags (MV), RemovePictureTags number ...tags (MV) and Change Picture Tags (MZ)

The commands adds and/or remove preset tags on a visible Picture. These tags can be checked by rules, but are discarded when "Erase Picture..." or "Show Picture..."-without-"+ReplacePicture" are used on that slot.

(If no Picture is visible with the given number, these commands do nothing.)

FlashPictureModifiers …numbers …modifiers (MV), Flash Picture Modifiers (MZ),
LapsePictureModifiers …numbers …modifiers (MV) and Lapse Picture Modifiers (MZ)

Immediately forces the specified modifiers to fully transition in or out once on the specified Pictures. After the modifier has fully transitioned, it is released and will follow the state determined by "Picture rules...".

In the MV version, all fully decimal parameters are interpreted as Picture numbers, while all other parameters are interpreted as modifier names. These may appear in any order, and all specified modifiers are controlled on each specified Picture.

Pictures and modifiers that can't be resolved are ignored, but will generate a JavaScript console message at least in playtest mode.

WaitForPictureModifiers …numbers …modifiers Timeout=t (MV) and
Wait for Picture Modifiers (MZ)

Wait for all the given modifiers (or all) on the given Pictures (or all) to stabilise before continuing. (This is implemented by rewinding the interpreter and waiting once, on each interpreter step where this plugin command yields.)

The timeout parameter is optional and defaults to 10 seconds (600 frames).
In MV, in place of "t", enter a duration in frames as plain integer.

JavaScript API

This plugin unconditionally sets the global variable TS_Dynamic_Pictures when first loaded.

There, the following property and functions are available (See source code comments for more detailed information):

version

Semantic Version-compatible featureLevel, patchLevel and releaseCandidate 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.

Iff releaseCandidate is not undefined, it indicates the RC number of the current version (starting at 1). This value is reset for each version that has release candidates.

This property is frozen and the object is frozen.

parameters

Parsed plugin parameters, with trailing _ and _files stripped from property names. The shorthand and JS conditions are present as functions, here, and missing arrays and strings are added as empty. Boolean properties are normalised to true or false.

This property is frozen, but the object is mutable.

easings

A string-keyed record of easing constructors. This plugin performs CSS argument splitting before passing them to the easing constructor, so the argument is a string[][] | undefined where comma-separated arguments contain space-separated values.
(The splitting is parentheses-aware. undefined indicates no top-level parentheses were used.)

This property is frozen, but the object is mutable.

PictureRule, BattlerCondition, ActorCondition, EnemyCondition, ModifierDefinition and ColorTone

Classes that validate and evaluate rules and modifiers. It's possible for other plugins to extend these to create more advanced rules and modifiers programmatically.

These properties are frozen, but the classes are mutable.

getOrInitModifierStates(picture, modifiersToEnable): ModifierStates

Given a Game_Picture and a set of modifier names to initially enable, initialises and returns the Picture's modifier states Map according to parameters.modifierDefinitions.

getFreshModifierStates(picture): ModifierStates

Given a Game_Picture, returns its modifier states, applying Picture rules as necessary to refresh them for the current Graphics.frameCount.

If necessary, initialises the states using getOrInitModifierStates.

oldName, oldOpacity, oldBlendMode, oldTone, oldUpdate, oldInitialize, newName, newOpacity, newBlendMode, newTone, newUpdate, newInitialize, oldTerminate, oldCommand231, oldLoadImages (MZ-only), oldLoadPicture, newTerminate, newCommand231, newLoadImages (MZ-only), newLoadPicture, oldReservePicture (MV-only), oldPluginCommand, oldMakeSaveContents, newReservePicture (MV-only), newPluginCommand, newMakeSaveContents, oldExtractSaveContents newExtractSaveContents

Functions associated with engine hooks installed by this plugin, 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.

mvMzPlusReplacePicture, mzReplacePicture, mvAddPictureTags, mvRemovePictureTags, mzChangePictureTags, mvFlashPictureModifiers, mzFlashPictureModifiers, mvLapsePictureModifiers, mzLapsePictureModifiers, mvWaitForPictureModifiers, mzWaitForPictureModifiers

Plugin command handler functions, called with a Game_Interpreter instance as this-argument and arguments in their parameters. Please see the source code for specifics on their signatures.

changePictureTags(pictureId, addTags, removeTags)

Used by the "…PictureTags" command handlers above.

pictureId is a number and
addTags and removeTags are a (string | symbol)[] each.

flashPictureModifiers(pictures, modifiers), lapsePictureModifiers(pictures, modifiers), waitForPictureModifiers(interpreter, pictures?, modifiers?, timeout = 600)

Used by the "Lapse[ ]Picture[ ]Tags" command handlers above.

pictures is an Array of numbers and/or Game_Pictures,
modifiers is an Array of strings and/or ModifierDefinitions,
interpreter is a Game_Interpreter and
timeout is the maximum wait duration in frames, by default ten seconds.

anyTransitioning(pictures?, modifiers?): boolean

Returns whether any of the given modifiers are currently transitioning on the given Picture(s).

pictures is an Array of numbers and/or Game_Pictures and
modifiers is an Array of strings and/or ModifierDefinitions.

pictures defaults to $gameScreen.maxPictures() Pictures retrieved from $gameScreen.picture(n).
modifiers defaults to parameters.modifierDefinitions (i.e. all).

applyRules(indexedRules, index, name, tags, outModifiers?): string

The function that transforms Picture file names and collects enabled modifier names each frame.

indexedRules is a (frozen) readonly PictureRule[],
index is a Map<string, number[]> containing indices into indexedRules,
name is a string (returned by Game_Picture.prototype.name) and
tags is a (string | symbol)[], copied from the Picture's preset tags.

You may pass an empty string[] as outModifiers. When the function returns, this Array contains the set of enabled modifier names.

instantiateEasing(cssIshEasingFunction): (t: number) => number

Instantiates an easing function according to the cssIshEasingFunction string. It looks up the respective easing constructor in easings.

This is generally done up to once per Game_Picture per EasingDefinition.

splitCSSishValue(input): [topLevel: string, args: string[][] | undefined][]

Splits the given input string into a top-level identifier and comma separated arguments comprised of space-separated values. Parentheses-aware.

See the attached JSDoc comment in the plugin source for examples.

parseCSSNumber(string): number | undefined,
parseCSSPercentage(string): number | undefined

Strict CSS value parsers. parseCSSPercentage returns percentage points divided by 100.

advanceModifiers(modifierStates, modifiersToEnable)

Unconditionally advances the given modifierStates according to modifiersToEnable (a string[]).

References parameters.modifierDefinitions.

gatherSavedPictures(): Generator<Game_Picture|null|undefined, void, void>

A generator function that returns all Game_Picture instances for which preset tags should be saved at that time. For simplicity, this function is also allowed to yield null and undefined, which are ignored.

Save Contents

This plugin creates an additional top-level key TS_Dynamic_Pictures in each normal save file. There, the following properties are stored:

(Note: The values of these properties are an implementation detail, so please do not depend on them directly!)

pictureTags

Per Picture tag settings. Note that only string tags are preserved.

modifierStates

Per Picture modifier states, stored by name.

See also *gatherSavedPictures() in the API for how to save this information for custom uses of Game_Picture.

Class Extensions

This plugin adds prefixed properties to certain engine class instances.
These are implementation details, so please do not depend on them directly.

Game_Interpreter

• TS_Dynamic_Pictures__REPLACE_MODE
• TS_Dynamic_Pictures__ELAPSED

Compatibility Notes

This plugin was tested on RPG Maker MV 1.6.3 and RPG Maker MZ 1.8.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.

This plugin is compatible with YEP_ItemCore (independent items).

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/dynamic-pictures .

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.