Sprite.lua

From PGE Wiki
Jump to: navigation, search

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 either your level's custom graphics folder for use in a level, along with a lunadll.lua file, or in the same directory as your .wld file along with a lunaworld.lua file for use throughout an entire episode.

How to use and Examples

To enable the sprite library for a specific level, add this line to lunadll.lua:

local SpriteAPI = API.load("sprite");

This will load the Sprite API.

Creating an animated sprite from multiple images

local myImages = {
    Graphics.loadImage(Misc.resolveFile("frame1.png")),
    Graphics.loadImage(Misc.resolveFile("frame2.png")),
    Graphics.loadImage(Misc.resolveFile("frame3.png"))
}

local myAnimationSet = SpriteAPI.animationFromImages(myImages)
local mySprite = SpriteAPI.sprite(myAnimationSet, SpriteAPI.COOR_CAMERA, 100, 100)
mySprite:show()

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:

mySprite:setFrameSpeed(8)

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:

local gifAnimationSet, gifFrameSpeed = SpriteAPI.animationFromGif(Misc.resolveFile("Rex.gif"))
local gifSprite = SpriteAPI.sprite(gifAnimationSet, SpriteAPI.COOR_CAMERA, 200, 200)
gifSprite:setFrameSpeed(gifFrameSpeed)
gifSprite:show()

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:
ExampleSpritesheet.png
Each frame in this file is 10x14 big in this 100x100 sprite sheet image. You can load this with the following code:

local exampleSpritesheetImage = Graphics.loadImage(Misc.resolveFile("ExampleSpritesheet.png"))
local allAnimationSets = SpriteAPI.animationFromSpritesheet(exampleSpritesheetImage, 10, 14)
local outerMovementAnimSet = allAnimationSets[1]
local toInnerMovementAnimSet = allAnimationSets[2]

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:

local exampleSpritesheetImage = Graphics.loadImage(Misc.resolveFile("ExampleSpritesheet.png"))
local allAnimationSets = SpriteAPI.animationFromSpritesheet(exampleSpritesheetImage, 10, 14)
local outerMovementAnimSet = allAnimationSets[1]
local toInnerMovementAnimSet = allAnimationSets[2]

local outerMovementSprite = SpriteAPI.sprite(outerMovementAnimSet, SpriteAPI.COOR_CAMERA, 100, 100)
local toInnerMovementSprite = SpriteAPI.sprite(toInnerMovementAnimSet, SpriteAPI.COOR_CAMERA, 100, 150)
outerMovementSprite:setFrameSpeed(8)
outerMovementSprite:show()
toInnerMovementSprite:setFrameSpeed(8)
toInnerMovementSprite:show()

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:

local outerAndToInnerMovementAnimSet = outerMovementAnimSet .. toInnerMovementAnimSet

You can then create a sprite out of outerAndToInnerMovementAnimSet.


Documentation

Coming soon!

Sprite API
Function Return values Description
SpriteAPI.animationFromSpritesheet(LuaResourceImg imgResource, number scanWidth, number scanHeight, table backgroundColorData) Animation set object Creates a new animation set from a spritesheet.

imgResource: The image resource to extract the animation frames.
scanWidth: The width of each frame of the animation.
scanHeight: The height of each frame of the animation.
backgroundColorData (Optional): A table which defines the background color data [{r, g, b, a}]. Use -1 to completely ignore a color value. Default is {-1, -1, -1, 255} (Every pixel which is full transparent is declared as background.)

SpriteAPI.animationFromImages(table of LuaResourceImg imgResource) Animation set object Creates a new animation set from an array of LuaResourceImg.
SpriteAPI.animationFromGif(string filename) Animation set object, number frameSpeed Creates a new animation set from an gif file. In addition the framespeed is returned.
SpriteAPI.sprite(sprite-mode mode, number x, number y, number speedX, number speedY ) Sprite object Creates a new empty sprite.

mode (Optional): either SpriteAPI.COOR_CAMERA or SpriteAPI.COOR_SCENE [Default is SpriteAPI.COOR_CAMERA]
x (Optional): the x coordinate of the sprite [Default is 0]
y (Optional): the y coordinate of the sprite [Default is 0]
speedX (Optional): the x speed of the sprite [Default is 0]
speedY (Optional): the y speed of the sprite [Default is 0]