loq_sprite

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.

Usage

local loqsprite = require(“loq_sprite”)

Summary
loq_spriteDefines the SpriteFactory and SpriteGroup creation module.
Functions
newFactoryCreates a new factory for creating SpriteGroup instances.
SpriteFactoryA factory to create SpriteGroup instances.
shapeNamesThe names of the sprite shapes available for the SpriteGroup instance for use with addPhysics.
spriteNamesThe names of the sprite animations available for playback in a SpriteGroup instance.
addScaleInforms the SpriteFactory that the spritesheets have additional scales available for the loaded spritesheets.
setMinPrepareIf set to true then any new SpriteGroups created will use a minimal set of instructions to prepare the SpriteGroup.
addSpriteSetInfoManually add sprite set info to the SpriteFactory.
addSpriteSheetModuleAdds new spritesheet modules exported from Spriteloq to this SpriteFactory.
disposeRemoves the sprite sheets from texture memory.
newMultiSetUsed to stitch multiple sprite module’s sprite sheet’s into one set.
newSpriteGroupCreates a SpriteGroup instance.
Shape Functions
addPhysicsAdds physical properties to a display object instance with a specified shape name.
getRectShapeReturns 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.
getShapeReturns an array of polygon vertices that can be used as the shape data for physics bodies.
SpriteGroupA group of sprites in a display group instance.
Properties
curSpriteThe current sprite instance of the SpriteGroup.
Events
spriteSpriteGroup instances will dispatch events propagated from curSprite.
Functions
animatingThe status of the current animation.
blendModeGet or set the blendMode of the SpriteGroup instance.
currentFrameGet or set the frame of the current animation sequence.
fillColorgets or sets the fill color of the SpriteGroup instance.
frameRateGets the frameRate of the current sprite sequence in frames per second
getSpriteNamesA table of the names of the playable sprite animations.
numFramesGets the number of frames in the current sprite sequence
pausePauses the current sprite animation.
playPlays prepares and plays a sprite animation.
prepareSwitches the sprite sequence, but does not play it.
sequenceThe name of the current animation.
timeScaleGet or set the timeScale of the SpriteGroup instance.
propagateReferenceCopies 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
addPhysicsAdds physical properties to the SpriteGroup instance.
getRectShapeReturns 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.
getShapeReturns an array of polygon vertices that can be used as the shape data for physics bodies.
Examples
Examples
Creating a SpriteFactory and SpriteGroupsCreating a SpriteFactory and SpriteGroups
Using newMultiSetUsing newMultiSet
Adding physics properties with addPhysicsAdding physics properties with addPhysics
Using getRectShape with physicsUsing getRectShape with physics
Adding an event listener and looping through animationsAdding an event listener and looping through animations
Triggering logic on a certain frame of an animationFrom the ninja sample app we show a snippet of code from a SpriteGroup ‘sprite’ event listener.

Functions

newFactory

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.

Parameters

  • ...  Optional module names of sprite metadata generated by Spriteloq

Returns

A SpriteFactory instance.

SpriteFactory

A factory to create SpriteGroup instances.

Summary
shapeNamesThe names of the sprite shapes available for the SpriteGroup instance for use with addPhysics.
spriteNamesThe names of the sprite animations available for playback in a SpriteGroup instance.
addScaleInforms the SpriteFactory that the spritesheets have additional scales available for the loaded spritesheets.
setMinPrepareIf set to true then any new SpriteGroups created will use a minimal set of instructions to prepare the SpriteGroup.
addSpriteSetInfoManually add sprite set info to the SpriteFactory.
addSpriteSheetModuleAdds new spritesheet modules exported from Spriteloq to this SpriteFactory.
disposeRemoves the sprite sheets from texture memory.
newMultiSetUsed to stitch multiple sprite module’s sprite sheet’s into one set.
newSpriteGroupCreates a SpriteGroup instance.
Shape Functions
addPhysicsAdds physical properties to a display object instance with a specified shape name.
getRectShapeReturns 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.
getShapeReturns an array of polygon vertices that can be used as the shape data for physics bodies.

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

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.

Parameters

  • ...  One or more numbers e.g (0.5, 2, 0.75).  The value 1 is always assumed to exist and does not need to be passed in.

setMinPrepare

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.

addSpriteSetInfo

function SpriteFactory:addSpriteSetInfo(_setInfos)

Manually add sprite set info to the SpriteFactory.

Parameters

  • _setInfos An array of sprites and references: { (spriteName = {set, xReference, yReference})+ }

addSpriteSheetModule

function SpriteFactory:addSpriteSheetModule(...)

Adds new spritesheet modules exported from Spriteloq to this SpriteFactory.

Parameters

  • ...  Optional module names of sprite metadata exported from Spriteloq

dispose

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.

newMultiSet

function SpriteFactory:newMultiSet(_modules,
_spriteInfo)

Used to stitch multiple sprite module’s sprite sheet’s into one set.

Parameters

  • _modules An array of module names of sprite metadata generated by Spriteloq
  • _spriteInfo A table specifying the animation info of the sprite

SpriteInfo Properties

nameThe name of the sprite as defined in the sprite sheet.
frameCountHow many frames in the sprite’s animation.
frameRateThe frameRate of the animation.
loopParamThe loop option as specified in the Corona docs for sprites.  0 for loop, 1 for play once, -1 for bounce, -2 for bounce loop

newSpriteGroup

function SpriteFactory:newSpriteGroup(_spriteName)

Creates a SpriteGroup instance.

Parameters

  • _spriteName Optional name of the initial animation.  Otherwise defaults to the first sprite animation.

Returns

A SpriteGroup instance.

Event

Dispatches a sprite event with phase set to ‘prepare’ if a spriteName is passed in.

Shape Functions

addPhysics

function SpriteFactory:addPhysics(_displayObj,
_physics,
_bodyType,
_properties,
_shapeName,
_xOffset,
_yOffset,
_scale)

Adds physical properties to a display object instance with a specified shape name.

Parameters

  • _displayObj A display object that usually is not a SpriteGroup.
  • _physics The Corona physics module.
  • _bodyType A string representing the physics body type: ‘dynamic’, ‘kinematic’, ‘static’.
  • _properties A table with properties that contains the physics body: density, friction, bounce
  • _shapeName shapeName for the physics body specified a sprite.
  • _xOffset Optional x offset for the physics body.
  • _yOffset Optional y offset for the physics body.
  • _scale Optional scale for the physics body.

Returns

A table of points for the rectangle containing the current sprite’s current frame for use with physics.

getRectShape

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.

Parameters

_sequence The sprite name used to retrieve the rectangle shape.

Returns

A table of points for the rectangle containing the sprite frame for use with physics.

getShape

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.

Parameters

  • _shapeName Optional name of a sprite with a shape.  Default uses the current sprite sequence name for the shape name.

Returns

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.

SpriteGroup

A group of sprites in a display group instance.

Summary
Properties
curSpriteThe current sprite instance of the SpriteGroup.
Events
spriteSpriteGroup instances will dispatch events propagated from curSprite.
Functions
animatingThe status of the current animation.
blendModeGet or set the blendMode of the SpriteGroup instance.
currentFrameGet or set the frame of the current animation sequence.
fillColorgets or sets the fill color of the SpriteGroup instance.
frameRateGets the frameRate of the current sprite sequence in frames per second
getSpriteNamesA table of the names of the playable sprite animations.
numFramesGets the number of frames in the current sprite sequence
pausePauses the current sprite animation.
playPlays prepares and plays a sprite animation.
prepareSwitches the sprite sequence, but does not play it.
sequenceThe name of the current animation.
timeScaleGet or set the timeScale of the SpriteGroup instance.
propagateReferenceCopies 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
addPhysicsAdds physical properties to the SpriteGroup instance.
getRectShapeReturns 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.
getShapeReturns an array of polygon vertices that can be used as the shape data for physics bodies.

Properties

curSprite

The current sprite instance of the SpriteGroup.  This sprite is changed when a new sprite animation sequence is prepared.

Events

sprite

SpriteGroup instances will dispatch events propagated from curSprite.

Phases

endThe sprite stops playing.
loopThe sprite loops (from last to first, or reverses direction)
nextThe sprite’s next frame is played
prepareThe spriteGroup prepares a new animation.  This is dispatched if the spriteGroup plays a new animation.

Functions

animating

function SpriteGroup:animating()

The status of the current animation.

Returns

true if animating, false otherwise

blendMode

function SpriteGroup:blendMode(_blendMode)

Get or set the blendMode of the SpriteGroup instance.

Parameters

  • _blendMode Optional, to set the blendMode of the animations.

Returns

The current blendMode of the SpriteGroup instance.

currentFrame

function SpriteGroup:currentFrame(_frame)

Get or set the frame of the current animation sequence.

Parameters

  • _frame Optional, to set the current frame of the animation.

Returns

The current frame of the animation.

fillColor

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.

Parameters

  • _arg1 If parameter count is 1 or 2 then arg1 is Gray.  If parameter count is 3 or 4 then arg1 is Red.
  • _arg2 Optional.  If parameter count is 2 then arg2 is Alpha.  If parameter count is 3 or 4 then arg2 is Green.
  • _arg3 Optional.  Blue component.
  • _arg4 Optional.  Alpha component.

Returns

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.

frameRate

function SpriteGroup:frameRate()

Gets the frameRate of the current sprite sequence in frames per second

Returns

The frameRate of the current sprite sequence in frames per second

getSpriteNames

function SpriteGroup:getSpriteNames()

A table of the names of the playable sprite animations.

numFrames

function SpriteGroup:numFrames()

Gets the number of frames in the current sprite sequence

Returns

The number of frames in the current sprite sequence

pause

function SpriteGroup:pause()

Pauses the current sprite animation.

play

function SpriteGroup:play(_spriteName,
_keep)

Plays prepares and plays a sprite animation.

Parameters

  • _spriteName Optional - The name of the sprite animation, or plays the current animation sequence.
  • _keep If the current animation is the same as the new sprite animation, do not reset it.

Event

A sprite event with phase equal to “prepare” is dispatched when if a new sprite animation is prepared.

prepare

function SpriteGroup:prepare(_spriteName)

Switches the sprite sequence, but does not play it.

Parameters

  • _spriteName The sprite to display.

Event

A sprite event with phase equal to “prepare” is dispatched when the new sprite animation is prepared.

sequence

function SpriteGroup:sequence()

The name of the current animation.

timeScale

function SpriteGroup:timeScale(_timeScale)

Get or set the timeScale of the SpriteGroup instance.

Parameters

  • _timeScale Optional, to set the timeScale of the animations.

Returns

The current timeScale of the SpriteGroup instance.

propagateReference

function SpriteGroup:propagateReference(_target)

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

Parameters

  • _target The target display object to have its reference point updated.

Shape Functions

addPhysics

function SpriteGroup:addPhysics(_physics,
_bodyType,
_properties,
_shapeName,
_scale)

Adds physical properties to the SpriteGroup instance.

Parameters

  • _physics The Corona physics module.
  • _bodyType A string representing the physics body type: ‘dynamic’, ‘kinematic’, ‘static’.
  • _properties A table with properties that contains the physics body: density, friction, bounce
  • _shapeName Optional shapeName for the physics body.  Otherwise uses the current sprite sequence to determine the shape.
  • _scale Optional scale for the physics body

Returns

A table of points for the rectangle containing the current sprite’s current frame for use with physics.

getRectShape

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.

Parameters

  • _scale Optional scale for the rectangle

Returns

A table of points for the rectangle containing the current sprite’s current frame for use with physics.

getShape

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.

Parameters

  • _shapeName Optional name of a sprite with a shape.  Default uses the current sprite sequence name for the shape name.
  • _scale Optional scale for the physics body

Returns

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

Summary
Examples
Creating a SpriteFactory and SpriteGroupsCreating a SpriteFactory and SpriteGroups
Using newMultiSetUsing newMultiSet
Adding physics properties with addPhysicsAdding physics properties with addPhysics
Using getRectShape with physicsUsing getRectShape with physics
Adding an event listener and looping through animationsAdding an event listener and looping through animations
Triggering logic on a certain frame of an animationFrom the ninja sample app we show a snippet of code from a SpriteGroup ‘sprite’ event listener.

Examples

Creating a SpriteFactory and SpriteGroups

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

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

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

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

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()

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.  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)
end
local function newFactory(...)
Creates a new factory for creating SpriteGroup instances.
local function addScale(...)
Informs the SpriteFactory that the spritesheets have additional scales available for the loaded spritesheets.
local function setMinPrepare(_state)
If set to true then any new SpriteGroups created will use a minimal set of instructions to prepare the SpriteGroup.
function SpriteFactory:addSpriteSetInfo(_setInfos)
Manually add sprite set info to the SpriteFactory.
function SpriteFactory:addSpriteSheetModule(...)
Adds new spritesheet modules exported from Spriteloq to this SpriteFactory.
function SpriteFactory:dispose()
Removes the sprite sheets from texture memory.
function SpriteFactory:newMultiSet(_modules,
_spriteInfo)
Used to stitch multiple sprite module’s sprite sheet’s into one set.
function SpriteFactory:newSpriteGroup(_spriteName)
Creates a SpriteGroup instance.
function SpriteFactory:addPhysics(_displayObj,
_physics,
_bodyType,
_properties,
_shapeName,
_xOffset,
_yOffset,
_scale)
Adds physical properties to a display object instance with a specified shape name.
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.
function SpriteFactory:getShapes(_shapeName,
_xOffset,
_yOffset,
_scale)
Returns an array of polygon vertices that can be used as the shape data for physics bodies.
function SpriteGroup:animating()
The status of the current animation.
function SpriteGroup:blendMode(_blendMode)
Get or set the blendMode of the SpriteGroup instance.
function SpriteGroup:currentFrame(_frame)
Get or set the frame of the current animation sequence.
function SpriteGroup:fillColor(...)
gets or sets the fill color of the SpriteGroup instance.
function SpriteGroup:frameRate()
Gets the frameRate of the current sprite sequence in frames per second
function SpriteGroup:getSpriteNames()
A table of the names of the playable sprite animations.
function SpriteGroup:numFrames()
Gets the number of frames in the current sprite sequence
function SpriteGroup:pause()
Pauses the current sprite animation.
function SpriteGroup:play(_spriteName,
_keep)
Plays prepares and plays a sprite animation.
function SpriteGroup:prepare(_spriteName)
Switches the sprite sequence, but does not play it.
function SpriteGroup:sequence()
The name of the current animation.
function SpriteGroup:timeScale(_timeScale)
Get or set the timeScale of the SpriteGroup instance.
function SpriteGroup:propagateReference(_target)
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:addPhysics(_physics,
_bodyType,
_properties,
_shapeName,
_scale)
Adds physical properties to the SpriteGroup instance.
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.
function SpriteGroup:getShapes(_shapeName,
_scale)
Returns an array of polygon vertices that can be used as the shape data for physics bodies.
Close