Dynamic Actors MV + MZ

This plugin submits combined rule definitions to both Dynamic Characters and Dynamic Pictures, to make it more convenient to set up graphics for Actors that also appear as Pictures (for example in dialogue scenes).

It also makes it easier to apply Actor conditions to Events and Vehicles, by optionally not limiting them to the given party character sprite. Additionally, Actor conditions defined in this plugin may optionally be fulfilled by Actors currently outside the party, to more easily implement dynamic NPCs.

For more information, please see the respective plugin's documentation.

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

This plugin requires at least one of the following plugins:

Added Features and Limitations

• To avoid confusion, the "only on Maps:" and its nested "with note tag:" parameters available in this plugin also apply to Pictures, even though this Dynamic Characters feature isn't part of Dynamic Pictures.
  • Some tweaks are in place to make sure there won't be any errors from such rules where the map or its data aren't available. (e.g. Battle Test)
• Similarly, the terrain tag check from Dynamic Characters isn't available here because it requires input that only exists when checking characters, and as such can't very intuitively be applied to Pictures.
  • This also applies to Event-, Vehicle- and Enemy-conditions, which are features not shared between Dynamic Characters and Dynamic Pictures.
• To make it easier to work with Actors who appear as Events sometimes, there is an option to use the Actor condition logic from Dynamic Pictures for all character sprites for rules defined by this plugin.
  • See the plugin parameter "Strict Character check?" below for more information.
• To make it easier to work with Actors who appear as NPCs outside the party, there is an option to also consider initialised Actors outside the party for conditions defined in this plugin (where applicable). You can allow this by turning OFF the "Only in party?" toggle for the Actor condition.
  • Doing so will may reduce performance depending on the total amount of Actors.
    
  • Actors become initialised when first used by the game.

Hints

• For simplicity, it's not possible to specify distinct layers for each target (base layer) in one rule.
  • However, you can still easily set up variations for different Actors using the %1 target name placeholder in a layer name.
    • If you do this, please ensure that the variation actually exists for each target to avoid any potential runtime errors, and please add any variations as added layers to a rule with no targets so that they won't be excluded when deploying your game.
      • You can use transparent 1x1-pixel PNGs as placeholder for unused variations.
• Conditions in this plugin are slightly more limited than in the original separate plugins. You can still apply such conditions by setting tags there, which will be visible to the "Actor rules" defined here.

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 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" or (in MV) "Change Actor Images" commands to the same Event script.

Load Order

Dynamic Actors must be loaded AFTER (below) the following plugins:

• Dynamic Characters
• Dynamic Pictures

At least one of these plugins is required for this one to function, and for full functionality both of them must be loaded first.

Plugin Parameters

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

Strict Character check?

Controls whether to apply the rules this plugin adds to Dynamic Characters only to Actor characters respectively matching Actor conditions, or else to use Dynamic Pictures's behaviour where a match is only required iff Actor conditions exist and may be fulfilled by any Actor.

This is useful when Actors are represented by Map Events sometimes, but may force you to separate sprite sheets in img/characters/ by Actor.

Instead of setting up separate rules for each actor, you can e.g. check whether the Actor's database name appears in the current target/base-layer file name by writing target.includes(battler.actor().name) in the shorthand- or JS-condition in the Actor condition, as this is compatible with both Dynamic Characters and Dynamic Pictures.

Turning this OFF may reduce performance in some cases.
ON by default.

JavaScript Conditions

Rules and Actor 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 conditions, battler refers to the Game_Actor that the condition is examining.

This means you can for example write (battler.hp / battler.mhp) <= 0.5 in an Actor condition to only apply the rule while the selected Actor 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 Actor conditions can contain "shorthand conditions", which are a convenient way to write JavaScript conditions more concisely. For example, here (in an Actor 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 Actor 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 Actor 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 an Actor'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 Actor isWaiting to perform a magic or guard skill, respectively.

Plugin Commands

This plugin provides no additional plugin commands.

Please see the Dynamic Characters and Dynamic Pictures pages for relevant commands added by those two plugins.

JavaScript API

This plugin unconditionally sets the global variable TS_Dynamic_Actors 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. 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 and the parameter object, as well as actorRules are frozen. Note that changing ActorRules objects won't affect the game as the nested CharacterRules and PictureRules are submitted only once as this plugin is initialised. They are retained mainly for reference.

ActorRule, ActorCharacterRule, ActorPictureRule, StrictActorConditionForCharacters, LooseActorConditionForCharacters, AlwaysPassActorConditionForCharacters and ActorConditionForPictures

Classes that validate and evaluate rules. It's possible for other plugins to extend these to create more advanced rules programmatically. Not all classes are used, depending on this plugin's configuration. Please refer to the source code for more information.

These properties are frozen, but the classes are mutable.

Iff TS_Dynamic_Characters or TS_Dynamic_Pictures weren't available when this plugin was loaded, some of these classes are missing their base class and as such will unconditionally throw errors when instantiated by another plugin.

Save Contents

This plugin stores no additional save data.

However, both Dynamic Characters and Dynamic Pictures do! Please see their respective documentation.

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 acquired at https://tamschi.itch.io/dynamic-actors .

Once you have acquired 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.