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.

With this plugin, you can use rules to apply replacements and additional layers 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.

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.

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.

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

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.

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

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

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

This property is frozen and the object is frozen.

parameters

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

This property is frozen as parameters is directly captured.

PictureRule, BattlerCondition, ActorCondition and EnemyCondition

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

These properties are frozen, but the classes are mutable.

mvMzPlusReplacePicture, mzReplacePicture, mvAddPictureTags, mvRemovePictureTags and mzChangePictureTags

Plugin command handler functions, called with a Game_Interpreter instance as this-argument and arguments in their parameters.

changePictureTags(pictureId, addTags, removeTags)

Used by the "…PictureTags" command handlers above.

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

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

The function that transforms Picture file 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.

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:

pictureTags: [Game_Picture, string[]][]

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

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

Compatibility Notes

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