Battle animations - jjppof/goldensun_html5 GitHub Wiki

You can create a battle animation WITHOUT PROGRAMMING KNOWLEDGE, you just need to set up a JSON file (JSON is not a programming language, it's a data file just like CSV or XML are, check this tutorial to understand how JSON files work) with the animation recipe and a spritesheet for the graphics. Each animation has one json file and one spritesheet. The json file contains one object with the following properties.

[Particles information are still missing.]

Files names pattern

Spritesheet

assets/images/abilities_animations/[battle_animation_key].png
assets/images/abilities_animations/[battle_animation_key].json

Recipe

Example of animation recipe for Ice psynergy.

assets/dbs/abilities_animations/[battle_animation_key]_db.json

Example: battle_animation_key could be ice for Ice psynergy, so ice_db.json, ice.png and ice.json.

Battle animation tester

There's a small mode in GSHTML5 to test the battle animations easily. When in-game in the browser mode, press Y to enable the battle animation tester mode. This will enable the following fields below the canvas:

You can set an enemy party key name or leave it empty to go with Briggs' party. Then press "Start animation tester".
In the bottom text field, you type your battle animation key name to test it (you can check "Hit all enemies" to hit all enemies) or use a big JSON editor on the right side, any modifications in this editor will be applied on-the-fly (you need to make sure that you're using a valid JSON).

Common properties for all sequences

• ignore_if_dodge [boolean]: if true, this animation sequence will be ignored if the target dodged the attack. Optional property. Default is false.

Properties

• key_name [string]: battle animation unique key name. Ideally, the same as the ability name.

• sprites [array|string]: specify the sprites that will be created for this battle animation. The indexes of this array can be used on sprite_index property. If a string is passed to this property, it must be one of the following: "caster", "allies", "targets", or "background", by choosing one of these, you'll be able to access these sprites individually when defining animation sequences. But if it's defined as an array, it must be an array of objects that accept the following properties.

  • type [string]: The type of this sprite, it can be a regular sprite if you pass "sprite" (like the thunder sprite of Plasma, the stones of Spire, etc), it can be geometric forms if you pass "circle", "ring", or "rectangle". Or it can be a copy of a region of the background image if you pass "background_copy".
  • key_name [string]: sprite key_name. The animation for this sprite will also have this key_name, see animation_key property under play_sequence property below. It's only valid if type property is set to "sprite".
  • frames_number [number]: Your spritesheet for this ability animation will probably have more than one animation, for the one you specified in key_name, set the number of frames it has. It's only valid if type property is set to "sprite".
  • per_target [boolean]: if it's going to be one sprite per battle target, if set to true, per_target_key must also be set. Default is false.
  • per_target_key [string]: set a key name in this property to identify in the animation sequences the whole group of sprites that were created for each target. Only valid if per_target property is set to true.
  • position [string]: can be "behind" if the sprite is behind caster and target groups. "between" if the sprite is between the groups. or "over" if the sprite is over the two groups.
  • count [number]: set a specific number of copies for this sprite to be created. Each copy has a different index that will be incremented up to the count number.
  • trails [boolean]: set to true if you want this sprite to have trails.
  • trails_mode [string]: the blend mode for the trails. It can be "normal" or "screen".
  • trails_factor [number]: controls the number of trails that this sprite is going to have.
  • follow_sprite [number]: the index of a sprite that you want this one to follow the position. A sprite index is the position number of a sprite inside the above sprite property.
  • geometry_info [object]: object to describe geometric sprites. Only valid if type property is set to "circle", "ring", or "rectangle".
    • width [number]: Only valid for "rectangle" type. The width in px of the rectangle.
    • height [number]: Only valid for "rectangle" type. The height in px of the rectangle.
    • radius [number]: Only valid for "ring" and "circle" types. The radius of the form in px.
    • color [string]: The color of the geometric form in hexadecimal. It also accepts "element" as a value, if it's the case, the color of the geometric form will be the same as the color that represents the element of the ability.
    • thickness [number]: Only valid for "ring" type. The thickness of the ring.
    • keep_core_white [boolean]: if true, the core area of the geometric form will be tinted with white color. Default is false.
  • background_copy_info [object]: object to describe background copy region, which is a rectangle sprite. Only valid if type property is set to "background_copy". Check type property for details about background copies.
    • x [number|string]: the x position in px of the region. If a number is passed, then the absolute position in the canvas is set. If a string is passed, then it can be one of the following: "caster", "allies", or "targets".
    • y [number|string]: the y position in px of the region. If a number is passed, then the absolute position in the canvas is set. If a string is passed, then it can be one of the following: "caster", "allies", or "targets".
    • width [number]: the width in px of the region.
    • height [number]: the height in px of the region.
  • initial_config [object]: object to describe basic transforms and properties of the sprite when it's created like position, anchor point, scale, etc.
    • x [number|string]: the initial x position in px of the sprite. If a number is passed, then the absolute position in the canvas is set. If a string is passed, then it can be one of the following: "caster", "allies", or "targets".
    • y [number|string]: the initial y position in px of the sprite. If a number is passed, then the absolute position in the canvas is set. If a string is passed, then it can be one of the following: "caster", "allies", or "targets".
    • alpha [number]: the initial alpha channel value of the sprite, please values between 0 and 1.
    • blend_mode [string]: the blend mode. It can be "screen" or "normal".
    • scale [object]: the object containing values to define the sprite scale.
      • x [number]: the scale x value.
      • y [number]: the scale y value.
    • anchor [object]: the object containing values to define the sprite anchor point.
      • x [number]: the anchor point x value.
      • y [number]: the anchor point y value.

• x_sequence [array]: controlling the x property of a sprite in pixels.

  • sprite_index [string|number|array|object]: the index of a sprite that you want this action to take place. A sprite index is the position number of a sprite inside the above sprite property. This property can also be a string: "targets" if you're referring to targets, "allies" if you're referring to allies, "caster" if the caster, "background" if the background sprite. It can also be an array of any type before. If this property is of object type, you can use it to define a range of numbers:
    • starting_value [number]: the initial number of the range. Required property.
    • cumulator [number]: the step size that will be accumulated for each element. Required property.
    • reverse [boolean]: if true, it will reverse the resulting range elements order. Optional property. Default is false.
    • amount [number|string]: the number of elements that will be affected after this object gets expanded in the engine. You can also set string values as "allies" or "targets" to pass the number of these as the amount. Optional property. Default value is automatically inferred.
  • start_delay [number|array|object]: the initial delay in ms for this action to take place. The delay is always relative to the battle animation start. It can be an array of values if you set an array for sprite_index. The array length must match. If this property is of object type, you can use it to define a range of numbers:
    • starting_value [number]: the initial number of the range. Required property.
    • cumulator [number]: the step size that will be accumulated for each element. Required property.
    • reverse [boolean]: if true, it will reverse the resulting range elements order. Optional property. Default is false.
    • amount [number|string]: the number of elements that will be affected after this object gets expanded in the engine. You can also set string values as "allies" or "targets" to pass the number of these as the amount. Optional property. Default value is automatically inferred.
  • to [string|number|array|object]: the value you're targeting. The value can be "targets", "reset" or an actual value. In the case of "targets" is the corresponding property value of the central target. In the case of using "targets", a "shift" property is available to be added to the resulting value. In the case of "reset", it will return to x or y original value of a fighter, only works for x_sequence and y_sequence, shift and is_absolute don't apply for this value. It can be an array of values if you set an array for sprite_index. The array length must match. If this project is set as an object, the behavior will be just like start_delay property, please check it.
  • to_expression [string]: for whatever is the resulting value of to property, this property modifies its final value by a given math expression. Use v to reference the to value. Example: "v * 2 / (v ^ 3) + sqrt(v)". Optional property.
  • shift [number|array|object]: the value to be added to the resulting value from to property. It can be an array of values if you set an array for sprite_index. The array length must match. If this project is set as an object, the behavior will be just like start_delay property, please check it.
  • is_absolute [boolean]: whether the value given in to property is an absolute value.
  • per_target_key [string]: only valid if in the sprite definition section, a sprite with per_target true property was set. This implies that a per_target_key was also set. Set this property to the desired per_target_key key name in order to identify the correct group of sprites to manipulate. If this per_target_key is set, it's not necessary to set sprite_index.
  • tween [string]: the easing type of the animation. Types can be found here. Example: "Elastic.Out".
  • duration [number]: how low this animation is going to last in ms.
  • yoyo [boolean]: if true, the property will reach the to value, then return to its initial value.
  • affect_only_shadow [boolean]: if true, the property will affect only the shadow of allies and/or enemies.

• y_sequence [array]: controlling the y property of a sprite in pixels. Same properties as x_sequence.

• x_scale_sequence [array]: controlling the scale.x property of a sprite. 100% is 1. Same properties as x_sequence.

• y_scale_sequence [array]: controlling the scale.y property of a sprite. 100% is 1. Same properties as x_sequence.

• x_anchor_sequence [array]: controlling the anchor.x property of a sprite. 0 is the left, 1 is the right side of the sprite. Same properties as x_sequence.

• y_anchor_sequence [array]: controlling the anchor.y property of a sprite. 0 is the top, 1 is the bottom side of the sprite. Same properties as x_sequence.

• alpha_sequence [array]: controlling the alpha property of a sprite. Values between 0 and 1. Same properties as x_sequence.

• grayscale_sequence [array]: controlling the saturation of a sprite. Values between 0 and 1. Same properties as x_sequence.

• rotation_sequence [array]: controlling the rotation property of a sprite in rad. Same properties as x_sequence plus the one below.

  • direction [string]: it can be "clockwise", "counter_clockwise" or "closest".

• hue_angle_sequence [array]: controls the hue angle of a sprite in rad. Same properties as rotation_sequence.

• center_shift_sequence [array]: this property controls how far a fighter sprite will be from the center of the stage. Default value: 0. Same properties as x_sequence plus the one below.

  • force_stage_update [boolean]: if true, the stage will be updated while this property is changing.

• stage_angle_sequence [array]: controls the rotation of the stage in rad. Default position value is 0.7551327.

  • start_delay [number]: the initial delay in ms to this action takes place. The delay is always relative to the previous action.
  • to [number|string]: the value you're targeting. It can also be "default" to return to default position or "cast_position" to go to the cast position (allies or opponent, it depends on who is casting).
  • is_absolute [boolean]: whether the value given in to property is an absolute value.
  • direction [string]: it can be "clockwise", "counter_clockwise" or "closest".
  • tween [string]: the easing type of the animation. Types can be found here. Example: "Elastic.Out".
  • duration [number]: how low this animation is going to last in ms.

• set_frame_sequence [array]: plays a sprite animation.

  • sprite_index [string|number|array]: the index of a sprite that you want this action to take place. A sprite index is the position number of a sprite inside the above sprite property. This property can also be a string: "targets" if you're referring to targets, "caster" if the caster, "background" if the background sprite. It can also be an array of any type before.
  • start_delay [number|array]: the initial delay in ms to this action takes place. The delay is always relative to the battle animation start. It can be an array of values if you set an array for sprite_index. The array length must match.
  • frame_name [string]: the frame name to be set.

• play_sequence [array]: plays a sprite animation.

  • sprite_index [string|number|array|object]: the index of a sprite that you want this action to take place. A sprite index is the position number of a sprite inside the above sprite property. This property can also be a string: "targets" if you're referring to targets, "caster" if the caster, "background" if the background sprite. It can also be an array of any type before. For object type explanation, please check x_sequence.sprite_index section.
  • start_delay [number|array|object]: the initial delay in ms to this action takes place. The delay is always relative to the battle animation start. It can be an array of values if you set an array for sprite_index. The array length must match. For object type explanation, please check x_sequence.start_delay section.
  • reverse [boolean]: if true, reverses the animation direction.
  • frame_rate [number]: animation frame rate.
  • repeat [boolean]: if true, the animation will keep repeating.
  • hide_on_complete [boolean]: if true, the sprite will be hidden after animation end.
  • wait [boolean]: if true, waits for this animation end before unsetting the current battle animation.
  • animation_key [string]: the sprite key_name that wat set in the sprite property. In the case sprite_index is "caster" or "targets", you can use the following keys:
    • "attack"
    • "cast"
    • "cast_init"
    • "damage"
    • "downed"
    • "idle"

• blend_mode_sequence [array]: controls a sprite blend mode.

  • sprite_index [string|number|array]: the index of a sprite that you want this action to take place. A sprite index is the position number of a sprite inside the above sprite property. This property can also be a string: "targets" if you're referring to targets, "caster" if the caster, "background" if the background sprite. It can also be an array of any type before.
  • start_delay [number|array]: the initial delay in ms to this action takes place. The delay is always relative to the battle animation start. It can be an array of values if you set an array for sprite_index. The array length must match.
  • mode [string]: the blend mode. It can be "screen" or "normal".

• sfx_sequence [array]: plays an sfx during the battle animation.

  • sfx_key [string]: the sfx key to be played.
  • start_delay [number]: the initial delay in ms to this action takes place. The delay is always relative to the battle animation start.
  • position_shift [number]: the amount of time in seconds to initially cut this sfx. Optional property.
  • volume [number]: the volume of the sfx to be executed. Optional property. Default is 1.

• tint_sequence [array]: tint a sprite.

  • sprite_index [string|number|array]: the index of a sprite that you want this action to take place. A sprite index is the position number of a sprite inside the above sprite property. This property can also be a string: "targets" if you're referring to targets, "caster" if the caster, "background" if the background sprite. It can also be an array of any type before.
  • start_delay [number|array]: the initial delay in ms to this action takes place. The delay is always relative to the battle animation start. It can be an array of values if you set an array for sprite_index. The array length must match.
  • value [array]: array of 3 values for RGB. Each value ranging from 0 to 1. -1 values disable it.

• blink_sequence [array]: blink a sprite by tinting it multiple times given an interval.

  • sprite_index [string|number|array]: the index of a sprite that you want this action to take place. A sprite index is the position number of a sprite inside the above sprite property. This property can also be a string: "targets" if you're referring to targets, "caster" if the caster, "background" if the background sprite. It can also be an array of any type before.
  • start_delay [number|array]: the initial delay in ms to this action takes place. The delay is always relative to the battle animation start. It can be an array of values if you set an array for sprite_index. The array length must match.
  • count [number]: the number of times this sprite will blink. Required property.
  • interval [number]: the blink interval in ms. Required property.
  • color [object]: the RGB color of the blink. Default is white.
    • r [number]: the red component ranging from 0 to 1.
    • g [number]: the green component ranging from 0 to 1.
    • b [number]: the blue component ranging from 0 to 1.

• colorize_sequence [array]: colorize a sprite.

  • sprite_index [string|number|array]: the index of a sprite that you want this action to take place. A sprite index is the position number of a sprite inside the above sprite property. This property can also be a string: "targets" if you're referring to targets, "caster" if the caster, "background" if the background sprite. It can also be an array of any type before.
  • start_delay [number|array]: the initial delay in ms to this action takes place. The delay is always relative to the battle animation start. It can be an array of values if you set an array for sprite_index. The array length must match.
  • value [value]: Value ranging from 0 to 1. This range corresponds to the color spectrum starting with blue. -1 values disable it.
  • colorize_intensity [value]: Value ranging from 0 to 1. This is the intensity of the colorize.

• texture_displacement_sequence [array]: shifts texture pixels within its sprite boundaries.

  • sprite_index [string|number|array]: the index of a sprite that you want this action to take place. A sprite index is the position number of a sprite inside the above sprite property. This property can also be a string: "targets" if you're referring to targets, "caster" if the caster, "background" if the background sprite. It can also be an array of any type before.
  • start_delay [number|array]: the initial delay in ms to this action takes place. The delay is always relative to the battle animation start. It can be an array of values if you set an array for sprite_index. The array length must match.
  • duration [number]: the duration of the pixel displacement in ms.
  • tween [string]: the easing type of the animation. Types can be found here. Example: "Elastic.Out".
  • yoyo [boolean]: if true, the property will reach the shift value, then return to its initial value.
  • repeat_texture [boolean]: if false, it won't repeat the texture on displacement. Optional property. Default is true.
  • shift [object]: the x and/or y shift measured in px.
    • x [number]: the x-axis pixel shift to be applied in px.
    • y [number]: the y-axis pixel shift to be applied in px.

• flame_filter_sequence [array]: applies flame filter to sprites.

  • sprite_index [string|number|array|object]: the index of a sprite that you want this action to take place. A sprite index is the position number of a sprite inside the above sprite property. This property can also be a string: "targets" if you're referring to targets, "caster" if the caster, "background" if the background sprite. It can also be an array of any type before. For object type explanation, please check x_sequence.sprite_index section.
  • start_delay [number|array|object]: the initial delay in ms to this action takes place. The delay is always relative to the battle animation start. It can be an array of values if you set an array for sprite_index. The array length must match. For object type explanation, please check x_sequence.start_delay section.
  • remove [boolean]: If true, will remove the filter instead of applying it. Optional property. Default is false.
  • per_target_key [string]: only valid if in the sprite definition section, a sprite with per_target true property was set. This implies that a per_target_key was also set. Set this property to the desired per_target_key key name in order to identify the correct group of sprites to manipulate. If this per_target_key is set, it's not necessary to set sprite_index.

• levels_filter_sequence [array]: control the overall contrast, gamma, and dynamic range of sprites. About levels. All properties from flame_filter_sequence apply to this one. Properties specific to this sequence:

  • min_input [number]: the black input of the filter. Required property.
  • max_input [number]: the white input of the filter. Required property.
  • gamma [number]: the gamma input of the filter. Required property.

• glow_filter_sequence [array]: sets glow effect in the sprites. All properties from flame_filter_sequence apply to this one. Properties specific to this sequence:

  • r [number]: range 0 to 1. Sets the red component of the color. Required property.
  • g [number]: range 0 to 1. Sets the green component of the color. Required property.
  • b [number]: range 0 to 1. Sets the blue component of the color. Required property.
  • strength [number]: sets the strength of the glow. Required property.

• alpha_gray_filter_sequence [array]: this filter will apply transparency to the sprite based on its gray level. If pixel is black, then 100% transparent. If pixel is white, then 100% opaque. All properties from flame_filter_sequence apply to this one.