Sprite.lua

Download Latest Version

sprite.lua is a library for creating high-level animated custom sprites with movement abilities. It requires LunaLua v0.7.1.

Installation
Copy the sprite.lua file in the LuaScriptsLib folder.

How to use and Examples
To enable the sprite library for a specific level, add this line to lunadll.lua: This will load the Sprite API.

Creating an animated sprite from multiple images
In this example the three files "frame1.png", "frame2.png", "frame3.png" are bundled into an animation set. This animation set is passed to the sprite constructor. In addition we pass the type of coordiates and the coodinates itself to the constructor. This is necessary to see our custom sprite in the game. This is an easy way to create an animated sprite. But you will see that the animation goes insanely fast. To fix that you can add this line: With this line only every 8 frames a frameswitch is happening.

Creating an animated sprite from an animated gif
The sprite api can also load animated gifs: In this example we load the gif "Rex.gif" directly into an animation set. In addition we get the frame speed (written in the gif metadata) returned which we can use with the :setFrameSpeed-function. This is the simplest way to create an animated sprite, because you don't have to care about the frame speed. You can create animated sprites (with built-in frame delay) with gimp and its gif exporter.

Creating an animated sprite from a spritesheet
This way is the most efficient way to create an animated sprite. However it is a bit more complicated. The sprite api provides a function called SpriteAPI.animationFromSpritesheet. It will return an array/table of animation sets. This function takes the sprite width and the sprite height as a parameter and will try to extract the frames out of the spritesheet. Each row is one animation set in the array returend by the function.

Here is an example spritesheet: Each frame in this file is 10x14 big in this 100x100 sprite sheet image. You can load this with the following code: In this code the sprite api scans for each frame in the spritesheet if it is empty or not. If a frame on this spritesheet is fully transparent the extractor-function will ignore this frame. If a row is fully transparent then the whole row gets ignored and will not be added to the animation set array. In this case allAnimationSets is an array with 2 elements. The first element is the first row of our spritesheet. It displays 2 looping pixels. The second element is the second row of our spritesheet. It dispays 4 pixels getting together.

We now have our animation sets, but no sprites yet. Let's create them: Now we can see our two animations.

Sometimes you may also want to split up you animation sequence to two rows. The animation set class supports an operator to concat those two into one animation set: You can then create a sprite out of outerAndToInnerMovementAnimSet.

Documentation
Coming soon!