Altimit Character Animations

[Xilef]

Altimit Character Animations

This is an open-source project, feel free to clone the repository and make pull requests.

About

This Plugin adds the ability to greatly extend the animation system for character sprites.

Altimit Character Animations offers flexibility that no-other character animation Plugin can through the use of Javascript as a scripting method for selecting your animation states.

This allows custom states to be created and custom conditions to be written to massively expand how character animations can be done.

The goal is for Altimit Character Animations to be the ultimate extra-frames Plugin.

Download Latest Version

• Download Plugin (Right-click, save-as)
• View on GitHub

Features

• 8 direction support
• Unlimited animation frames
• Any sized, any layout sprite-sheets
• Compatibility with Altimit Movement, including XML defined colliders
• Javascript scripting interface

Alpha Release

The alpha release is the early days of the Plugin whilst the API is assessed and features added.

The goal is to bring it up to par with other existing extra-frames Plugins and provide everything needed for developers to create a game using all the features available with the Plugin.

Known Issues

The latest issues are listed on the project page at the following URL: github.com/AltimitSystems/mv-plugins/issues

Feel free to report issues in this thread or create a new issue on the project tracker (label as Altimit Character Animations).

API

$params includes the following properties:

• direction - character facing direction
• direction4 - direction limited to up, down, left, right
• direction8 - for use with 8 direction movement, some Plugins will let you use normal "direction"
• travelled - How many pixels has the character moved since the last frame

• state - contains character's current state and how many frames they've been in the state
• lastState - contains character's previous state (if there is one)
• override - Boolean set to true if the state has been overridden with a custom state

• tilesetId - sprite tileset ID
• tileId - sprite tile ID
• characterName - This should be the same as the XML file name
• characterIndex - Sprite index on multi-sprite character sheets
• character - Game_Character, comes with all properties that Game_Character has. Very powerful!

• isDebugThrough - Boolean set to true when debug walk-through-walls is active
• isDashButtonPressed - Different to $params.state.dashing
• isOnDamageFloor - Character on floor damage tile (applies only to Player by default)

The in-built states are:

• state.bush - Character is in a bush
• state.dashing - Character is dashing (running)
• state.jumping - Character is jumping
• state.ladder - Character is on ladder
• state.moving - Character is moving
• state.idle - Character is doing nothing

Custom states should not use these names. So if you want a state for when your character is handsome, don't call it "dashing", call it "handsome" and then you can reference it with $params.state.handsome

The animation return structure has the following options:

• animation - ID of the XML animation to play-back
• oneShot - Boolean, if set to true then the animation will play once and stop on the last frame (default false)
• scaleX - Scales sprite in X axis (default 1)
• scaleY - Scales sprite in Y axis(default 1)
• speed - Play-back speed multiplier (default 1)

Both the XML animation-list and animation tags support scaling properties "sx" and "sy":

<div class="xml" id="{CB}" style="font-family: monospace;"><ol><span style="color: #009900;"><!-- All sprite frames will be 2x bigger -->

<span style="color: #009900;"><span style="font-weight: bold; color: black;"><animation-list sheet="my_sheet" sx="2" sy="2"<span style="font-weight: bold; color: black;">>

 

    <span style="color: #009900;"><!-- When this animation is playing, sprite will be 50% sized -->

    <span style="color: #009900;"><!-- Combined with the animation-list scale, this results in a 1x (normal!) sized sprite -->

    <span style="color: #009900;"><span style="font-weight: bold; color: black;"><animation id="my_animation" sx="0.5" sy="0.5"<span style="font-weight: bold; color: black;">>

 

        <span style="color: #009900;"><!-- Frames go here -->

 

    <span style="color: #009900;"><span style="font-weight: bold; color: black;"></animation<span style="font-weight: bold; color: black;">>

 

<span style="color: #009900;"><span style="font-weight: bold; color: black;"></animation-list<span style="font-weight: bold; color: black;">>

These scaling properties can be used to mirror sprites; simply scale with a negative value. This is useful if you want to re-use sprite frames for both the left and right directions.

Usage

To add a character animation extension to a sprite sheet simply create an XML file in the img/characters folder with the same file name as the character sheet you wish to extend.

For example, to extend Actor1.png we'd create Actor1.xml next to it.

There are two required structures in the XML file:

• animation-list
• script

The animation list must contain a property defining which image to use as a source of the extra frames.

So to extend Actor1.png with Actor1_extra.png our XML file should look similar to this:

<div class="xml" id="{CB}" style="font-family: monospace;"><ol><span style="color: #009900;"><!-- Notice Actor1_extra, this says "Use Actor1_extra.png for these frames" -->

<span style="color: #009900;"><span style="font-weight: bold; color: black;"><animation-list sheet="Actor1_extra"<span style="font-weight: bold; color: black;">>

<span style="color: #009900;"><span style="font-weight: bold; color: black;"></animation-list<span style="font-weight: bold; color: black;">>

 

<span style="color: #009900;"><!-- The script is where we write our animation state logic -->

<span style="color: #009900;"><span style="font-weight: bold; color: black;"><script<span style="font-weight: bold; color: black;">>

<span style="color: #009900;"><span style="font-weight: bold; color: black;"></script<span style="font-weight: bold; color: black;">>

Let's say we want to add an "idle" animation for when the first Actor1 character is waiting around for more than 10 seconds (600 frames).

We first need to write out where in the Actor1_extra these "idle" animation frames are.

<div class="xml" id="{CB}" style="font-family: monospace;"><ol><span style="color: #009900;"><span style="font-weight: bold; color: black;"><animation-list sheet="Actor1_extra"<span style="font-weight: bold; color: black;">>

 

    <span style="color: #009900;"><!-- Our idle animation for when the character is facing "down" -->

    <span style="color: #009900;"><!-- The "rate" is the frames-per-second of the animation -->

    <span style="color: #009900;"><span style="font-weight: bold; color: black;"><animation id="idle_south" rate="10"<span style="font-weight: bold; color: black;">>

 

        <span style="color: #009900;"><!-- The animation frames -->

        <span style="color: #009900;"><!-- These are texture co-ordinates on the sprite sheet -->

        <span style="color: #009900;"><!-- In this example, one frame is 64x64 pixels and there are 5 frames, left-to-right -->

        <span style="color: #009900;"><span style="font-weight: bold; color: black;"><frame x="0" y="0" width="64" height="64" <span style="font-weight: bold; color: black;">/>

        <span style="color: #009900;"><span style="font-weight: bold; color: black;"><frame x="64" y="0" width="64" height="64" <span style="font-weight: bold; color: black;">/>

        <span style="color: #009900;"><span style="font-weight: bold; color: black;"><frame x="128" y="0" width="64" height="64" <span style="font-weight: bold; color: black;">/>

        <span style="color: #009900;"><span style="font-weight: bold; color: black;"><frame x="196" y="0" width="64" height="64" <span style="font-weight: bold; color: black;">/>

        <span style="color: #009900;"><span style="font-weight: bold; color: black;"><frame x="256" y="0" width="64" height="64" <span style="font-weight: bold; color: black;">/>

 

    <span style="color: #009900;"><span style="font-weight: bold; color: black;"></animation<span style="font-weight: bold; color: black;">>

 

<span style="color: #009900;"><span style="font-weight: bold; color: black;"></animation-list<span style="font-weight: bold; color: black;">>

 

<span style="color: #009900;"><span style="font-weight: bold; color: black;"><script<span style="font-weight: bold; color: black;">>

<span style="color: #009900;"><span style="font-weight: bold; color: black;"></script<span style="font-weight: bold; color: black;">>

Now that we've written out where the animation frames for our down-facing idle animation is we need to write script logic for selecting the frames.

<div class="xml" id="{CB}" style="font-family: monospace;"><ol><span style="color: #009900;"><span style="font-weight: bold; color: black;"><animation-list sheet="Actor1_extra"<span style="font-weight: bold; color: black;">>

 

    <span style="color: #009900;"><span style="font-weight: bold; color: black;"><animation id="idle_south" rate="10"<span style="font-weight: bold; color: black;">>

 

        <span style="color: #009900;"><span style="font-weight: bold; color: black;"><frame x="0" y="0" width="64" height="64" <span style="font-weight: bold; color: black;">/>

        <span style="color: #009900;"><span style="font-weight: bold; color: black;"><frame x="64" y="0" width="64" height="64" <span style="font-weight: bold; color: black;">/>

        <span style="color: #009900;"><span style="font-weight: bold; color: black;"><frame x="128" y="0" width="64" height="64" <span style="font-weight: bold; color: black;">/>

        <span style="color: #009900;"><span style="font-weight: bold; color: black;"><frame x="196" y="0" width="64" height="64" <span style="font-weight: bold; color: black;">/>

        <span style="color: #009900;"><span style="font-weight: bold; color: black;"><frame x="256" y="0" width="64" height="64" <span style="font-weight: bold; color: black;">/>

 

    <span style="color: #009900;"><span style="font-weight: bold; color: black;"></animation<span style="font-weight: bold; color: black;">>

 

<span style="color: #009900;"><span style="font-weight: bold; color: black;"></animation-list<span style="font-weight: bold; color: black;">>

 

<span style="color: #009900;"><!-- Scripting is in Javascript -->

<span style="color: #009900;"><span style="font-weight: bold; color: black;"><script<span style="font-weight: bold; color: black;">>

    // The $params variable holds information about the current state

    // The script must return a structure defining the animation

 

    // If we are facing south and have been idle for over 10 seconds (600 frames)

    if ( $params.direction == 2 <span style="color: #ddbb00;">&& $params.state.idle > 600 ) {

<span style="color: #ddbb00;">        // Play the idle_south animation, defined in XML

<span style="color: #ddbb00;">        // oneShot will play the animation once and stay on the final frame

<span style="color: #ddbb00;">        return { animation: "idle_south", oneShot: true };

    }

<span style="color: #009900;"><span style="font-weight: bold; color: black;"></script<span style="font-weight: bold; color: black;">>

For an idea of how advanced this can be, animations for "enter idle" can be defined and the $params.state.idle frames can be used to detect the start of idling, then after N frames it can play an "idle loop" animation.

Character states can be override with custom states also. If I wanted to set a "fishing" state to $gamePlayer I can call $gamePlayer.extraStateSet( ["fishing"] ). If I want to stop overriding states (such as fishing has been completed) I can use $gamePlayer.extraStateReset().

 

[LittleGameDev]

This plugin is very interesting and I would love to beta test it out for you. I downloaded the plugins file, there is not much in the help section so I am at a bit of a loss on how to set it up, I hope you will be providing a demo file for this plugin. It would make setting it up and testing out its features a lot easier. :thumb: