Skip to content

Battle animations

Jump to bottom
jjppof edited this page Jan 6, 2026 · 86 revisions

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.

Check Creating Plasma battle animation tutorial for a step-by-step battle animation creation.

Files names pattern

Below is how you define your animation spritesheet and animation recipe.

Spritesheet

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

Recipe

This is an example of animation recipe for Whirlwind psynergy.

Recipe file name pattern:

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

In short: battle_animation_key could be whirlwind for Whirlwind psynergy, so whirlwind_db.json, whirlwind.png and whirlwind.json.

Battle animation tester

There's a small mode in GSHTML5 to test the battle animations easily. In order to start it, set start_battle_tester_on_init to true in init.json and then start the engine.
The engine will start in battle mode with an editor on the right side. Paste your JSON recipe there. You can modify this JSON on the fly and test while adding features in the recipe. In order to fire the animation to aim at one target, press O; multiple targets, press P.
Please notice that changes in this editor won't reflect the original JSON recipe, you need to copy the modified content and paste it into the original file to save it.

image

General properties

  • key_name [string]: battle animation unique key name. The same as the ability name. Required property.
  • cast_type [string]: when warriors are casting abilities, they generally play specific types of casting animation before it. Use this property to identify which casting animation this ability should use. List of cast types can be found at assets\dbs\common_abilities_animations\abilities_cast_db.json. Optional property.
  • wait_for_cast_animation [boolean]: will tell if we want to wait for the cast animation to finish before starting the main ability animation.

Sprites configuration properties

  • sprites [array|string]: specify the sprites that will be created for this battle animation. The indices 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". If this property is not set, total frames number of this sprite will be set.
    • 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".
      • frame_name [string]: the initial frame name to be set.
      • 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.

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.
  • 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.
  • 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 optionally be an array of values if you set an array for sprite_index, each item in sprite_index should have an equivalent item in start_delay in the same index, in other words, if using an array for start_delay, its length should match with sprite_index array. 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.

Sequences properties

  • 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.
    • 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.
    • tween [string]: the easing type of the animation. Available options:
      • "Linear.None"
      • "Quadratic.In"
      • "Quadratic.Out"
      • "Quadratic.InOut"
      • "Cubic.In"
      • "Cubic.Out"
      • "Cubic.InOut"
      • "Quartic.In"
      • "Quartic.Out"
      • "Quartic.InOut"
      • "Quintic.In"
      • "Quintic.Out"
      • "Quintic.InOut"
      • "Sinusoidal.In"
      • "Sinusoidal.Out"
      • "Sinusoidal.InOut"
      • "Exponential.In"
      • "Exponential.Out"
      • "Exponential.InOut"
      • "Circular.In"
      • "Circular.Out"
      • "Circular.InOut"
      • "Elastic.In"
      • "Elastic.Out"
      • "Elastic.InOut"
      • "Back.In"
      • "Back.Out"
      • "Back.InOut"
      • "Bounce.In"
      • "Bounce.Out"
      • "Bounce.InOut"
    • duration [number]: how long 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.
    • dont_affect_shadow [boolean]: if true, the property will affect only the sprite of allies and/or enemies.
    • 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 for 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. Please check x_sequence.tween section on this page.
    • duration [number]: how long this animation is going to last in ms.

  • set_frame_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. For full information about this property, check x_sequence.sprite_index on this page.
    • 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. For full information about this property, check x_sequence.sprite_index on this page.
    • 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 is 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|object]: the index of a sprite that you want this action to take place. For full information about this property, check x_sequence.sprite_index on this page.
    • 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 for 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.

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

    • sprite_index [string|number|array|object]: the index of a sprite that you want this action to take place. For full information about this property, check x_sequence.sprite_index on this page.
    • count [number]: the number of times this sprite will blink. Required property.
    • interval [number]: the blink interval in ms. Required property.
    • duration [number]: the duration in ms between blinks. Optional 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.

  • shake_sequence [array]: shakes a sprite for a given time and intensity. May interfere with x and y sequences.

    • sprite_index [string|number|array|object]: the index of a sprite that you want this action to take place. For full information about this property, check x_sequence.sprite_index on this page.
    • shake_count [number]: the number of times this sprite will shake. Required property.
    • interval [number]: one shake duration in ms.
    • direction [string]: the direction of the shake: set "x" or "y". Required property.
    • intensity [number]: the shake intensity in px. Required property.
    • random_delta [number]: a random delta value in px to be added to intensity. Optional property.

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

    • sprite_index [string|number|array|object]: the index of a sprite that you want this action to take place. For full information about this property, check x_sequence.sprite_index on this page.
    • duration [number]: the duration of the pixel displacement in ms.
    • tween [string]: the easing type of the animation. Please check x_sequence.tween section on this page.
    • 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. For full information about this property, check x_sequence.sprite_index on this page.
    • remove [boolean]: If true, will remove the filter instead of applying it. Optional property. Default is false.
image

  • tint_sequence [array]: tint a sprite with a given solid color. 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.

  • colorize_sequence [array]: colorize a sprite on a given color. All properties from flame_filter_sequence apply to this one. Properties specific to this sequence:

    • color [value]: Value ranging from 0 to 1. This range corresponds to the color spectrum starting with blue.
    • intensity [value]: Value ranging from 0 to 1. This is the intensity of the colorization.
    • tween [string]: you can ease the intensity property. Set easing type here. Please check x_sequence.tween section on this page.
    • duration [number]: you can ease the intensity property. Set the duration of it in ms.

Value range:
image

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

  • color_blend_filter_sequence [array]: blends a given color with the selected wprite. 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.
    • fake_blend [boolean]: if true, will also blend alpha channel. Default is false

  • particles_sequence [array]: configure the particles engine to emit particles. This property expects an array of objects that describe the behavior of the particles emission. Please check Particles engine article to configure a particle emission object.

Clone this wiki locally