Battle Symphony Manual

The original manual for Battle Symphony is hard to follow, so I'm rewriting it here. This post only covers the default Symphony Engine and does not include any of the add ons.

Yami's Battle Symphony scripts v1.16 plus all add ons can be downloaded from https://github.com/suppayami/rmvxa-collection/tree/master/battle-symphony.

Installation

In RPG Maker, open the Script Editor (F11). Right click under the section titled Materials, but above Main, and choose Insert. Type "Battle Symphony" in the Name box. Copy all the text from the Battle Symphony script and paste it here in RPG Maker.

If using Yanfly's Battle Engine, put Battle Symphony below all Yanfly scripts.

Configuration

Find the section in the script titled: Section I. Basic Settings (S-01)

EMPTY_VIEW
Whether to show party battlers or not. Set to true or false.
Default: False

PARTY_DIRECTION
The direction the party will be facing. (down = 2, left = 4, right = 6, up = 8)
Default: 4

ACTORS_POSITION
An array of x, y coordinates of each battler

WEAPON_ICON_NON_CHARSET
?

DISABLE_AUTO_MOVE_POSE
?

BATTLER_SHADOW
Whether to draw shadows beneath each battler. Set to true or false.
Default: True

ENEMY_ATTACK_ANIMATION
Animation ID to use as the default enemy attack animation.
Default: 1
Can be changed for each individual enemy by adding the tag <atk ani 1: id> in the enemy's notebox, where id is the Animation ID in the database.

AUTO_IMMORTAL_OFF
Whether to automatically turn off the Immortal status after actions are finished. Set to true or false.
Default: True

ALWAYS_COUNTER
Whether battlers can always counter or reflect, even when stunned or paralysed. Set to true or false.
Default: True

SYMPHONY TAGS

Each command entered during battle (e.g. an attack, using a skill, or using an item) is made up of a multitude of simpler actions that are grouped together as follows:

Setup actions: Actions prior to making the attack/using the skill, e.g. moving forward, drawing a weapon, or pulling out an item.

Target actions: Actions that affect individual targets, e.g. attacking a single enemy, healing an ally, etc.

Whole actions: Actions that affect all targets simultaneously, e.g. casting fire on all enemies will display animations on all enemies. (These actions occur after skill and item costs are calculated.)

Follow actions: Follow up actions to clean up any Target Actions.

Finish actions: Actions that finalise the use of the skill, e.g. putting away the weapon or item, and returning to battler's original position.

The Battle Symphony Engine already has defaults for all of these in place. Setup actions, Follow actions, and Finish actions are generally always going to be the same for every attack/skill/item, so most of the time only the Target actions will need to be modified. 

This is done by adding the target action group tag in the note box of whichever Skill, Item, or Weapon you want to customise. 

The tags for each group are as follows:

<setup action> </setup action>

<target action> </target action>

<whole action> </whole action>

<follow action> </follow action>

<finish action> </finish action>

Note: You only need to add the group tag for the group you wish to modify. Most of the time, this will only be Target Actions.

Then, between those tags are placed any sequence of any number of Symphony Commands as specified in the Commands section below.

COMMANDS

These commands are the heart of the Battle Symphony Engine, and are what makes the magic happen. 

These commands can be done in any order, any number of times. Any subject or target tag should be one of the options in the TARGET / SUBJECT section at the end of this section.

MOVEMENT

move subject: movement, frames, wait
This will move the target to a specific location.
subject: The subject to move (see the TARGET / SUBJECT section for details)
movement: Direction or location to move to
- forward, x: Move forward by x pixels.
- backward, x: Move backward by x pixels.
- origin: Move back to subject's original location.
- target, position: Move to target’s location. position is position on target’s body: foot, body, center, head, back
frames (optional): Total Frames. Use to define moving speed.
wait (optional): Type wait here to wait until effect’s done before going on.


teleport subject: movement, frames, wait
This will teleport the subject to a specific location. Usage is the same as move subject.


jump arc X subject: movement, frames, wait
This will make the subject jump to a specific location.
X: Jump Arc. Integer.
subject: Jumping Subject (see the TARGET / SUBJECT section for details)
movement: Specific Location
- forward, x: Jump forward for x pixel.
- backward, x: Jump backward for x pixel.
- origin: Jump back to subject's original location.
- target, position: Jump to target’s location. position is position on target’s body: foot, body, center, head, back
frames (optional): Total Frames. Use to define jumping speed.
wait (optional): Type wait here to wait until effect’s done before going on.

ICONS

icon create: target, name, position, id
This will create an icon object from IconSet, often used for weapons and items.
target: The target (see the TARGET / SUBJECT section for details)
name: Icon name for reference with other tags e.g. icon delete. Can be:
- weapon, weapon1: Icon for equipped Weapon 1.
- weapon2: Icon for equipped Weapon 2.
- shield: Icon for equipped Shield.
- item: Icon for the Item being used.
- any custom name
position (optional): Where the icon should be displayed. Can be:
- hand: Create Icon on Character’s Hand.
- shield: Create Icon on Character’s Other Hand.
- item: Create Icon on item position.
- middle: Create Icon on middle body.
- top: Create Icon on top body.
- bottom: Create Icon on bottom body.
id (optional): Icon ID when using a custom name.


icon delete: target, name
This will delete an icon object created by tag icon create.
target: The target.
name: Icon name for reference


icon effect: target, name, effect, frames, wait
This will make an effect for an icon object created by tag icon create.
target: The target.
name: Icon name reference.
effect: Icon Effect. Can be:
- angle, x: Set Icon angle to x.
- rotate, x: Make Icon rotate to angle x.
- animation x: Start Animation ID x on Icon.
- move_x x: Make Icon move to X-coordinate x.
- move_y y: Make Icon move to Y-coordinate y.
- cur_x x: Make Icon move to X-coordinate: Current X + x.
- cur_y y: Make Icon move to Y-coordinate: Current Y + y.
- fade in: Make Icon fade in.
- fade out: Make Icon fade out.
- float: Make Icon float (Use for Item Using).
- swing: Swing Icon down (Use for Swing Attack).
- upswing: Swing Icon up (Use for Swing Attack).
- stab: Special Move for Spear Attack.
- claw: Special Move for Claw Attack.
frames (optional): Total Frames. Use to define effect speed.
wait (optional): Type wait here to wait until effect is done before going on.


icon throw owner: target, name, arc, frames, wait
This will throw an object created by tag icon create to target.
owner: Object Owner, or where the icon should be thrown from
target: The target, or where the icon should be thrown to.
name: Icon name reference.
arc: Throwing Arc. Negative Integer will make object be thrown downward.
frames (optional): Total Frames. Use to define throwing speed.
wait (optional): Type wait here to wait until effect is done before going on.

ANIMATIONS

animation id: target, option
This will play animation on the targets. By default, this animation will be played with non-mirror and no waiting.
id: Animation ID in Database.
target: The target to play the animation on.
option (optional):
- wait: Causes the animation to wait until it’s done before going on.
- mirror: Causes the animation to mirror itself.

attack animation: target, option
skill animation: target, option
last animation: target, option
This will play the normal attack animation, or the skill's animation, or the last used animation, respectively, on the targets. By default, this animation will be played with non-mirror and no waiting.
target: The target.
option (optional):
- wait: Causes the animation to wait until it’s done before going on.
- mirror: Causes the animation to mirror itself.

BATTLE DAMAGE

attack effect: option1, option2
skill effect: option1, option2
This will calculate all attack or skill effects, from damage to status effects. You will have to use this tag to make the skill do damage and cause status effects on targets.
option1 (optional):
- clear: This will clear any miss, or evade flags.
- counter check: This will check and calculate counter flags.
- reflect check: This will check and calculate reflect flags.
- dmg: This will calculate the damage for targets.
- effect: This will cause status effects, includes Gain TP.
- whole: This will include all three tunes: calc, dmg, effect.
option2 (optional):
- calc: This will recalculate miss and evade flags for current step.
- perfect: This will prevent missing or evading.


immortal: target, flag
This will change the immortal flag for targets, which is useful when making a multi-hit skill. Setting the flag to false will make targets collapse if they fulfill the death condition.
target: The target to make immortal.
flag: Immortal Flag, set to true or false.

WAIT

wait for animation
This will wait until all animations have done before going on. Often used last in an Action Sequence

wait for move
This will wait until all movement has finished before going on. Often used last in an Action Sequence

wait: x
This will wait for x frames before going on

MISC

message
This will display using skill/item on Battle Log

auto symphony: key
This will play the Action Set defined by Auto Symphony (Section III) in the script.
key: Refer to Auto Symphony key (Section III) in the script.

TARGET / SUBJECT

Any target or subject tag in the list of Symphony Commands above this section can be one of the following:

user	The active battler.
target, or targets	The active targets in question.
actors, party, or actors living	All living actors.
all actors	All actors including dead ones.
actors not user	All living actors except for the user.
enemies, troop, or enemies living	All living enemies.
all enemies	All enemies, even dead.
enemies not user	All enemies except for the user
actor x	The actor in slot x
enemy x	The enemy in slot x.
everything	All living actors and enemies.
everything not user	All living battlers except the user
allies, or friends	The battler’s allies
friends not user	The battler’s allies except himself
opponents, or rivals	The battler’s opponents.
focus	The active battler and his targets
not focus	Everything but the active battler and his targets
counter subject	The countering battler
reflect subject	The reflecting battler
substitute subject	The substituting battler (for Cover skill)

BUGS

Battle Symphony 1.16 has the following bugs:

• Substitute actions (for the Cover skill) are not implemented
• The substitute subject is only set when item/skill effects are carried out, meaning any actions on the substitute subject prior to those effects will not happen

NOTES

• Shield icons are placed on the hand position, rather than in a shield position in front of the battler.
• All icons, battler positions, etc are reset at the end of every action, therefore it is not possible to hold an icon or position until the next turn, e.g. if guarding, and you want a shield icon in front of the player

Autonomous Movement

Just a reminder:

Events with Autonomous Movements will stop moving when the Player directly interacts with them, and will move again from where they left off afterwards (if bug fix in previous post is implemented).

Events with Autonomous Movements will keep moving during Autorun or Parallel Process events, and if you change their movement via a Set Move Route call, they will go back to their Autonomous route immediately after Set Move Route is over.

To prevent this, leave Autonomous Movement on Fixed. Or if you require them to move autonomously outside the Autorun event, have two event pages - one with the custom Autonomous route, and one with the Fixed route - and ensure the page with the Fixed route is active during Autorun.

Restore Move Route Bug Fix

I found a bug in RPG Maker VX Ace that I am really surprised I haven't come across a fix for already on the internet.

It's something I noticed before, but didn't really look into until now.

If you have an event with a repeating Custom Autonomous Movement, and some logic when you interact with them that makes a Set Move Route call, once the interaction is over one of two things may happen:

1. they return to their autonomous movement, but not where they left off when they were interrupted (meaning their original route gets totally screwed up), or
2. they stop moving completely.

It turns out, which one happens depends on where they were in their move route when you interacted with them. If you interact with them at the end of their Custom Autonomous Move Route cycle, the second one happens. Any other time, the first one happens.

The Way Movement Works

Events move around via an update_routine_move method that is called continuously (until you interact with them). The move route is the list of move commands, and it keeps track of the current movement via an index that is manually incremented. 

In other words, the code retrieves the current move command from the route via the index, processes the command, then advances the index. Pretty standard stuff. This method is also called for Set Move Route commands within the event logic, which actually overwrites the original move route.

But once Player interaction ends, the event is supposed to go back to its original move route. So the code stores (or "memorises") the Custom Autonomous Move Route prior to any Set Move Route call. It also stores the index so it can "remember" where it was up to when interrupted.

Then, when Set Move Route is done, it simply restores the original move route and the original index from memory. 

The bug is: it doesn't restore this index correctly.

The problem code is in one of two places, depending how you look at it.

Either:

class Game_Character

  #--------------------------------------------------------------

  # * Restore Move Route

  #--------------------------------------------------------------

  def restore_move_route

    @move_route           = @original_move_route

    @move_route_index     = @original_move_route_index

    @original_move_route  = nil

  end

end

OR

class Game_Character

  #--------------------------------------------------------------

  # * Process Move Route End

  #--------------------------------------------------------------

  def process_route_end

    if @move_route.repeat

      @move_route_index = -1

    elsif @move_route_forcing

      @move_route_forcing = false

      restore_move_route

    end

  end

end

It all looks correct and innocent enough, but the giveaway is that the index is set back to -1 and not 0 if the move route is set to repeat.

The reason for this is, the code processes the end of the move route as another command in the list. And as we discovered earlier, after a command is processed, it then advances the index. So when it goes back to the start, the index has been advanced back to 0 and we're good to go.

When it restores the move route, however, it doesn't take this into account. Therefore, the index is out by 1 when the original route is restored. 

What this means is if the event was in the middle of the move route when interrupted, it skips the command it was up to and goes to the next one, which is why the original route gets messed up. If the event was at the end of its route when interrupted, the index is then increased to be greater than the number of commands in the list, so when the code goes to process the next command, it simply doesn't find one and the event stops moving.

The Fix

For all that, the fix is very simple. The move route index simply needs to be decreased by 1 when restoring it back to the original route. This can be done in either of the two methods above. It makes more sense to me to do it in process_route_end but it's easier with aliasing to do it in restore_move_route. 

IMPORTANT: Choose one or the other, not both.

Either:

class Game_Character

  #--------------------------------------------------------------

  # * Alias method - Restore Move Route

  #   Only needed if the overwritten method below isn't used

  #--------------------------------------------------------------

  alias rtp_bug_fix_restore_move_route restore_move_route

  def restore_move_route

    rtp_bug_fix_restore_move_route

    @move_route_index -= 1

  end

end

OR

class Game_Character

  #----------------------------------------------------------------

  # * Overwrite Method - Process Move Route End

  #   Only needed if the alias method above isn't used

  #--------------------------------------------------------------

  def process_route_end

    if @move_route.repeat

      @move_route_index = -1

    elsif @move_route_forcing

      @move_route_forcing = false

      restore_move_route

      @move_route_index -= 1

    end

  end

end

Viewports

As explained by Shaz at:
https://forums.rpgmakerweb.com/index.php?threads/viewport-for-dummies.32585/

In the RTP, all the menus have only a single viewport, though you can still put things in front of or behind other things by changing the individual sprites' z-values.

On the map and in battles, there are three viewports. Viewports also have z-values.

Viewport 1 has a z-value of 0, Viewport 2 has a z-value of 50 and Viewport 3 a z-value of 100. Then things are layered inside these viewports by the sprites' z-values, just as they are in the menus.

If you have something in viewport 1 with a z-value of 500, anything in viewport 3 will still appear in front, even if those sprites have lower z-values.

Viewport 1 on the map contains the map itself, the background parallax, the character/event/vehicle sprites. When you set the screen tone or make the screen shake, only things on this viewport are affected.

Viewport 2 holds the weather and timer sprites and pictures. When you make the screen flash, this viewport is affected (which also has the appearance of affecting Viewport 1 as well, as this one is in front).

Viewport 3 takes care of the screen brightness, when you do a fade in or fade out or transfer.