Defines the SpriteFactory and SpriteGroup creation module.
This module lets you create complex sprites in Corona from metadata exported from Spriteloq, a Flash SWF to Corona SDK Exporter.
To use create a SpriteFactory with newFactory() passing in the names of the SpriteLoq exported metadata.
local loqsprite = require(“loq_sprite”)
| loq_sprite | Defines the SpriteFactory and SpriteGroup creation module. |
| Functions | |
| newFactory | Creates a new factory for creating SpriteGroup instances. |
| SpriteFactory | A factory to create SpriteGroup instances. |
| shapeNames | The names of the sprite shapes available for the SpriteGroup instance for use with addPhysics. |
| spriteNames | The names of the sprite animations available for playback in a SpriteGroup instance. |
| addScale | Informs the SpriteFactory that the spritesheets have additional scales available for the loaded spritesheets. |
| setMinPrepare | If set to true then any new SpriteGroups created will use a minimal set of instructions to prepare the SpriteGroup. |
| addSpriteSetInfo | Manually add sprite set info to the SpriteFactory. |
| addSpriteSheetModule | Adds new spritesheet modules exported from Spriteloq to this SpriteFactory. |
| dispose | Removes the sprite sheets from texture memory. |
| newMultiSet | Used to stitch multiple sprite module’s sprite sheet’s into one set. |
| newSpriteGroup | Creates a SpriteGroup instance. |
| Shape Functions | |
| addPhysics | Adds physical properties to a display object instance with a specified shape name. |
| getRectShape | Returns a table of points that represents a rectangle shape for the sprite sequence for use as the shape property in the body data for physics.addBody. |
| getShape | Returns an array of polygon vertices that can be used as the shape data for physics bodies. |
| SpriteGroup | A group of sprites in a display group instance. |
| Properties | |
| curSprite | The current sprite instance of the SpriteGroup. |
| Events | |
| sprite | SpriteGroup instances will dispatch events propagated from curSprite. |
| Functions | |
| animating | The status of the current animation. |
| blendMode | Get or set the blendMode of the SpriteGroup instance. |
| currentFrame | Get or set the frame of the current animation sequence. |
| fillColor | gets or sets the fill color of the SpriteGroup instance. |
| frameRate | Gets the frameRate of the current sprite sequence in frames per second |
| getSpriteNames | A table of the names of the playable sprite animations. |
| numFrames | Gets the number of frames in the current sprite sequence |
| pause | Pauses the current sprite animation. |
| play | Plays prepares and plays a sprite animation. |
| prepare | Switches the sprite sequence, but does not play it. |
| sequence | The name of the current animation. |
| timeScale | Get or set the timeScale of the SpriteGroup instance. |
| propagateReference | Copies the reference point of the SpriteGroup to target display object and resets the reference point of the the internal sprites sprite to 0, 0 |
| Shape Functions | |
| addPhysics | Adds physical properties to the SpriteGroup instance. |
| getRectShape | Returns a table of points that represents a rectangle shape for the current sprite’s current frame for use as the shape property in the body data for physics.addBody. |
| getShape | Returns an array of polygon vertices that can be used as the shape data for physics bodies. |
| Examples | |
| Examples | |
| Creating a SpriteFactory and SpriteGroups | Creating a SpriteFactory and SpriteGroups |
| Using newMultiSet | Using newMultiSet |
| Adding physics properties with addPhysics | Adding physics properties with addPhysics |
| Using getRectShape with physics | Using getRectShape with physics |
| Adding an event listener and looping through animations | Adding an event listener and looping through animations |
| Triggering logic on a certain frame of an animation | From the ninja sample app we show a snippet of code from a SpriteGroup ‘sprite’ event listener. |
local function newFactory( ... )
Creates a new factory for creating SpriteGroup instances.
Call newFactory and pass in some initial sprite module names exported from Spriteloq.
If you don’t pass in some initial modules, then you can add them later with SpriteFactory:addSpriteSheetModule. You can manually add in individual sprite set infomation with SpriteFactory:addSpriteSetInfo which can be used in conjunction with SpriteFactory:newMultiSet.
A SpriteFactory instance.
A factory to create SpriteGroup instances.
| shapeNames | The names of the sprite shapes available for the SpriteGroup instance for use with addPhysics. |
| spriteNames | The names of the sprite animations available for playback in a SpriteGroup instance. |
| addScale | Informs the SpriteFactory that the spritesheets have additional scales available for the loaded spritesheets. |
| setMinPrepare | If set to true then any new SpriteGroups created will use a minimal set of instructions to prepare the SpriteGroup. |
| addSpriteSetInfo | Manually add sprite set info to the SpriteFactory. |
| addSpriteSheetModule | Adds new spritesheet modules exported from Spriteloq to this SpriteFactory. |
| dispose | Removes the sprite sheets from texture memory. |
| newMultiSet | Used to stitch multiple sprite module’s sprite sheet’s into one set. |
| newSpriteGroup | Creates a SpriteGroup instance. |
| Shape Functions | |
| addPhysics | Adds physical properties to a display object instance with a specified shape name. |
| getRectShape | Returns a table of points that represents a rectangle shape for the sprite sequence for use as the shape property in the body data for physics.addBody. |
| getShape | Returns an array of polygon vertices that can be used as the shape data for physics bodies. |
local function addScale( ... )
Informs the SpriteFactory that the spritesheets have additional scales available for the loaded spritesheets. If additional scales are not available, the SpriteGroups created will use the native scale of 1 of spritesheet and scale down the sprite.
local function setMinPrepare( _state )
If set to true then any new SpriteGroups created will use a minimal set of instructions to prepare the SpriteGroup. Does not set timeScale, setFillColor, nor does the SpriteGroup dispatch a ‘sprite’ event with a ‘prepare’ phase.
If set to false, any new SpriteGroups will default to the normal prepare method.
function SpriteFactory:dispose()
Removes the sprite sheets from texture memory.
Note: Because of a bug in Corona, dispose uses a timer to dispose of the spritesheet and sheet module. You can attach an event listener and listen for the “spriteFactory” event with phase == “dispose” to know when this spriteFactory is disposed of. The spriteFactory:dispose event properties include the disposed setNames, spriteNames, and shapeNames.
function SpriteFactory:newMultiSet( _modules, _spriteInfo )
Used to stitch multiple sprite module’s sprite sheet’s into one set.
| name | The name of the sprite as defined in the sprite sheet. |
| frameCount | How many frames in the sprite’s animation. |
| frameRate | The frameRate of the animation. |
| loopParam | The loop option as specified in the Corona docs for sprites. 0 for loop, 1 for play once, -1 for bounce, -2 for bounce loop |
function SpriteFactory:newSpriteGroup( _spriteName )
Creates a SpriteGroup instance.
A SpriteGroup instance.
Dispatches a sprite event with phase set to ‘prepare’ if a spriteName is passed in.
function SpriteFactory:addPhysics( _displayObj, _physics, _bodyType, _properties, _shapeName, _xOffset, _yOffset, _scale )
Adds physical properties to a display object instance with a specified shape name.
A table of points for the rectangle containing the current sprite’s current frame for use with physics.
function SpriteFactory:getRectShape( _sequence, _frame, _xOffset, _yOffset, _scale )
Returns a table of points that represents a rectangle shape for the sprite sequence for use as the shape property in the body data for physics.addBody.
_sequence The sprite name used to retrieve the rectangle shape.
A table of points for the rectangle containing the sprite frame for use with physics.
function SpriteFactory:getShapes( _shapeName, _xOffset, _yOffset, _scale )
Returns an array of polygon vertices that can be used as the shape data for physics bodies. The method addPhysics calls this function.
Returns an array of polygon vertices that can be used as the shape data for physics bodies. If the sprite does not have shape data its rectangular frame shape is returned.
A group of sprites in a display group instance.
| Properties | |
| curSprite | The current sprite instance of the SpriteGroup. |
| Events | |
| sprite | SpriteGroup instances will dispatch events propagated from curSprite. |
| Functions | |
| animating | The status of the current animation. |
| blendMode | Get or set the blendMode of the SpriteGroup instance. |
| currentFrame | Get or set the frame of the current animation sequence. |
| fillColor | gets or sets the fill color of the SpriteGroup instance. |
| frameRate | Gets the frameRate of the current sprite sequence in frames per second |
| getSpriteNames | A table of the names of the playable sprite animations. |
| numFrames | Gets the number of frames in the current sprite sequence |
| pause | Pauses the current sprite animation. |
| play | Plays prepares and plays a sprite animation. |
| prepare | Switches the sprite sequence, but does not play it. |
| sequence | The name of the current animation. |
| timeScale | Get or set the timeScale of the SpriteGroup instance. |
| propagateReference | Copies the reference point of the SpriteGroup to target display object and resets the reference point of the the internal sprites sprite to 0, 0 |
| Shape Functions | |
| addPhysics | Adds physical properties to the SpriteGroup instance. |
| getRectShape | Returns a table of points that represents a rectangle shape for the current sprite’s current frame for use as the shape property in the body data for physics.addBody. |
| getShape | Returns an array of polygon vertices that can be used as the shape data for physics bodies. |
SpriteGroup instances will dispatch events propagated from curSprite.
| end | The sprite stops playing. |
| loop | The sprite loops (from last to first, or reverses direction) |
| next | The sprite’s next frame is played |
| prepare | The spriteGroup prepares a new animation. This is dispatched if the spriteGroup plays a new animation. |
function SpriteGroup:fillColor( ... )
gets or sets the fill color of the SpriteGroup instance. Note: Setting the alpha property of SpriteGroup display object it will not affect the fillColor.
The current fillColor of the SpriteGroup instance.
NOTE: fillColor is only supported in build 614 and higher. Running on lower versions causes Corona to crash. If you’re using a build lower than 614 then please download the API build for version 591 from the Spriteloq downloads page.
function SpriteGroup:play( _spriteName, _keep )
Plays prepares and plays a sprite animation.
A sprite event with phase equal to “prepare” is dispatched when if a new sprite animation is prepared.
function SpriteGroup:addPhysics( _physics, _bodyType, _properties, _shapeName, _scale )
Adds physical properties to the SpriteGroup instance.
A table of points for the rectangle containing the current sprite’s current frame for use with physics.
function SpriteGroup:getRectShape( _scale )
Returns a table of points that represents a rectangle shape for the current sprite’s current frame for use as the shape property in the body data for physics.addBody.
A table of points for the rectangle containing the current sprite’s current frame for use with physics.
function SpriteGroup:getShapes( _shapeName, _scale )
Returns an array of polygon vertices that can be used as the shape data for physics bodies. The method addPhysics calls this function.
Returns an array of polygon vertices that can be used as the shape data for physics bodies. If the sprite does not have shape data its rectangular frame shape is returned.
| Examples | |
| Creating a SpriteFactory and SpriteGroups | Creating a SpriteFactory and SpriteGroups |
| Using newMultiSet | Using newMultiSet |
| Adding physics properties with addPhysics | Adding physics properties with addPhysics |
| Using getRectShape with physics | Using getRectShape with physics |
| Adding an event listener and looping through animations | Adding an event listener and looping through animations |
| Triggering logic on a certain frame of an animation | From the ninja sample app we show a snippet of code from a SpriteGroup ‘sprite’ event listener. |
Creating a SpriteFactory and SpriteGroups
-- Require the module
local loqsprite = require('loq_sprite')
-- Create a SpriteFactory and include some spritesheet modules
local spriteFactory = loqsprite.newFactory('standing_sheet', 'running_sheet', 'jumping_sheet')
-- Create a SpriteGroup instance and pass in an initial animation
local si = spriteFactory:newSpriteGroup('standing')
-- Position the spriteGroup instance
si.x = 100
si.y = 200
-- Play one of the animations
si:play('running')
-- For atrace and xinspect
require('loq_util')
-- Prints out the table of animations: standing, running, jumping
atrace(xinspect(spriteFactory.spriteNames))
-- Adds a new animation for all SpriteGroup instances of factory
spriteFactory:addSpriteSheetModule('flying_sheet')
-- Prints out: standing, running, jumping, flying
atrace(xinspect(spriteFactory.spriteNames))
-- New sprite uses the first animation by default.
local si2 = spriteFactory:newSpriteGroup()
si2:play()
si:prepare('flying') -- Switches to flying without playing it.Using newMultiSet
If you have a sprite with too many frames to pack into a sprite sheet, you can manually create a sprite from multiple sheets using newMultiSet. Spriteloq doesn’t support the creation of multiple spritesheets for one sprite directly, but newMultiSet gives you a way around this.
local loqsprite = require('loq_sprite')
local spriteFactory = loqsprite.newFactory()
-- Here we call newMultiSet passing in an array of 3 spritesheets we created from Spriteloq.
-- We also need to pass in a table to specify the parameters of this sprite.
spriteFactory:newMultiSet(
{'sprite_1_sheet', 'sprite_14_sheet', 'sprite_27_sheet'},
{name='character', frameCount=28, frameRate=20, loopParam=0})
local sg = spriteFactory:newSpriteGroup()
sg:play()Adding physics properties with addPhysics
If the spritesheet metadata for the sprite includes shape data, you can add physics behavior to a SpriteGroup by calling addPhysics and passing the physics module and properties for the object.
local physics = require('physics')
physics.start();
physics.setGravity(0, 10)
physics.setScale(60)
physics.setDrawMode('hybrid')
local loqsprite = require('loq_sprite')
local spriteFactory = loqsprite.newFactory()
local tri = spriteFactory:newSpriteGroup('triangle')
tri:addPhysics(physics, 'dynamic', {density = 1.0, friction = 0.2, bounce = 0.2})
local box = spriteFactory:newSpriteGroup('box')
box.y = 200
box.rotation = 5
box:addPhysics(physics, 'static', {density = 1.0, friction = 0.3, bounce = 0.3})Using getRectShape with physics
If you want to quickly prototype physics using the rectangular shapes of your sprites, you can call getRectShape which will return a table of points to use as the shape property in body table for a physics.addBody call.
local loqsprite = require('loq_sprite')
local spriteFactory = loqsprite.newFactory()
local hero = spriteFactory:newSpriteGroup('hero idle')
local heroRectShape = hero:getRectShape()
heroBody = { friction=0.9, bounce=0.1, density=2, shape = heroRectShape }
physics.addBody(hero, "dynamic", heroBody)Adding an event listener and looping through animations
If you need to trigger events based on the play back of SpriteGroup instance, add an event listener. The example shows how you can trigger some logic to occur depending on the the SpriteGroup’s properties.
local loqsprite = require('loq_sprite')
local spriteFactory = loqsprite.newFactory()
local sg = spriteFactory:newSpriteGroup()
local animIndex = 1
local function playNext(self, _e) -- self is the SpriteGroup instance and _e is the event
-- when the animation of the current sprite ends switch to the next one
if _e.phase == 'end' then
animIndex = (animIndex % #spriteFactory.spriteNames) + 1
local spriteName = spriteFactory.spriteNames[animIndex]
sg:play(spriteName)
end
end
sg.sprite = playNext
sg:addEventListener('sprite', sg)
sg:play()From the ninja sample app we show a snippet of code from a SpriteGroup ‘sprite’ event listener. When the ninja jumps we want to create a new bolt ball on frame 17 of the jump animation.
-- 'ninja' is a SpriteGroup instance
-- 'bolts' is a table of SpriteGroup instances for our bolt animations
-- 'nfactory' is a SpriteFactory instance
-- '_e' is the sprite event
-- on frame 17 of the 'next' phase of the sprite event
if _e.phase == 'next' and ninja:currentFrame() == 17 then
-- create a new bolt and display it at the ninja position
local bolt = nfactory:newSpriteGroup('bolt ball')
bolt.x = ninja.x
bolt.y = ninja.y
bolt:play()
table.insert(bolts, bolt)
endCreates a new factory for creating SpriteGroup instances.
local function newFactory( ... )
Informs the SpriteFactory that the spritesheets have additional scales available for the loaded spritesheets.
local function addScale( ... )
If set to true then any new SpriteGroups created will use a minimal set of instructions to prepare the SpriteGroup.
local function setMinPrepare( _state )
Manually add sprite set info to the SpriteFactory.
function SpriteFactory:addSpriteSetInfo( _setInfos )
Adds new spritesheet modules exported from Spriteloq to this SpriteFactory.
function SpriteFactory:addSpriteSheetModule( ... )
Removes the sprite sheets from texture memory.
function SpriteFactory:dispose()
Used to stitch multiple sprite module’s sprite sheet’s into one set.
function SpriteFactory:newMultiSet( _modules, _spriteInfo )
Creates a SpriteGroup instance.
function SpriteFactory:newSpriteGroup( _spriteName )
Adds physical properties to a display object instance with a specified shape name.
function SpriteFactory:addPhysics( _displayObj, _physics, _bodyType, _properties, _shapeName, _xOffset, _yOffset, _scale )
Returns a table of points that represents a rectangle shape for the sprite sequence for use as the shape property in the body data for physics.addBody.
function SpriteFactory:getRectShape( _sequence, _frame, _xOffset, _yOffset, _scale )
Returns an array of polygon vertices that can be used as the shape data for physics bodies.
function SpriteFactory:getShapes( _shapeName, _xOffset, _yOffset, _scale )
The status of the current animation.
function SpriteGroup:animating()
Get or set the blendMode of the SpriteGroup instance.
function SpriteGroup:blendMode( _blendMode )
Get or set the frame of the current animation sequence.
function SpriteGroup:currentFrame( _frame )
gets or sets the fill color of the SpriteGroup instance.
function SpriteGroup:fillColor( ... )
Gets the frameRate of the current sprite sequence in frames per second
function SpriteGroup:frameRate()
A table of the names of the playable sprite animations.
function SpriteGroup:getSpriteNames()
Gets the number of frames in the current sprite sequence
function SpriteGroup:numFrames()
Pauses the current sprite animation.
function SpriteGroup:pause()
Plays prepares and plays a sprite animation.
function SpriteGroup:play( _spriteName, _keep )
Switches the sprite sequence, but does not play it.
function SpriteGroup:prepare( _spriteName )
The name of the current animation.
function SpriteGroup:sequence()
Get or set the timeScale of the SpriteGroup instance.
function SpriteGroup:timeScale( _timeScale )
Copies the reference point of the SpriteGroup to target display object and resets the reference point of the the internal sprites sprite to 0, 0
function SpriteGroup:propagateReference( _target )
Adds physical properties to the SpriteGroup instance.
function SpriteGroup:addPhysics( _physics, _bodyType, _properties, _shapeName, _scale )
Returns a table of points that represents a rectangle shape for the current sprite’s current frame for use as the shape property in the body data for physics.addBody.
function SpriteGroup:getRectShape( _scale )
Returns an array of polygon vertices that can be used as the shape data for physics bodies.
function SpriteGroup:getShapes( _shapeName, _scale )