Actions Library (ssk.actions.*) (Part2)

The actions library is a collection of helper modules and functions to do the heavy lifting associated with smooth facing, movement, screen-wrapping, and target acquisition.

GIF

This library is especially suited to action and arcade style game mechanics.

Facing
face
Non-Physics Movement
move.at move.forward
Physics Movement
movep.dampDown movep.dampHoriz movep.dampNormal
movep.dampVert movep.forward movep.impulseForward
movep.limitV movep.limitAV movep.thrustForward
Scene
scene.circWrap scene.rectWrap target.acquireRandom
Target Acquisition
target.drawDebugAngleDistanceLabel target.drawDebugDistanceLabel target.drawDebugLine
target.get target.loseAtMaxDistance target.loseAtMinAlpha
target.loseNotVisible target.loseOnDestroyed target.set

Scene Wrapping (scene.*)

Some action games use a single-screen world that wraps. That is, if a player or enemy leaves one side of the screen, they re-enter from the other side.

The helper functions in this action module help you achieve this.

scene.rectWrap

This helper will wrap one object about the bounds of a rectangle (any display object).

This seem strange at first, but by using a display object as the proxy for wrapping calculations, we have an easy way to define the wrapping space and well as an easy way to debug this.

ssk.actions.scene.rectWrap( objectToWrap, wrapRectangle )

Example:

-- Create a rectangle to act as our 'wrapping bounds'
local wrapProxy = display.newRect( display.contentCenterX, display.contentCenterY, 300, 300 )

-- Show it a little so we can see where the wrap should happen
wrapProxy.alpha = 0.1 

-- Place a player in the center of the wrapProxy and give it a random velocity
local player = display.newCirle( wrapProxy.x, wrapProxy.y, 20 )

physics:addBody( player )

player:setLinearVelocity( math.random( -100, 100), math.random( -100, 100) )

-- Start an enter frame listener and test for wrapping each frame
function player.enterFrame( self )
    ssk.actions.scene.rectWrap( self, wrapProxy )
end

Runtime:addEventListener( "enterFrame", player )

scene.circWrap

This helper is similar to rectWrap, but the wrapping is about a circular space and no proxy is required.

ssk.actions.scene.circWrap( objectToWrap, point, radius )

Example:


local cx = display.contentCenterX
local cy = display.contentCenterY

-- Place a player in the center of the screen and give it a random velocity
local player = display.newCirle( cx, cy, 20 )

physics:addBody( player )

player:setLinearVelocity( math.random( -100, 100), math.random( -100, 100) )

-- Start an enter frame listener and test for wrapping each frame
function player.enterFrame( self )
    ssk.actions.scene.circWrap( self, { x = cx, y = cy }, 100 )
end

Runtime:addEventListener( "enterFrame", player )

Target Acquisition (target.*)

In action and arcade games, there is often the need for missiles, gun turrets, enemies, etc. to acquire a target and then chase it down.

The functions in this actions module handle the first half of that work (target acquisition), and you can code up the second half using the face function in combination with move or movep functions.

target.set

This function allows you to manually assign a target to an object.

ssk.actions.target.set( obj, newTarget )

Example:

-- Have the player start targeting enemy
ssk.actions.target.set( player, enemy )

target.get

This function allows you to manually get an object's current target.

Returns nil if the object has no current target.

ssk.actions.target.get( obj )

Example:

-- Get the player's current target
local curTarget = ssk.actions.target.get( player )

target.acquireRandom

This chooses a random target from a target pool and assigns it to obj.

Returns true if a target was assigned, false otherwise.

ssk.actions.target.acquireRandom( obj, params )

Example:

ssk.actions.target.acquireRandom( self, { targets = targets } )

target.acquireNearest

This chooses the nearest target from a target pool and assigns it to obj.

Returns true if a target was assigned, false otherwise.

ssk.actions.target.acquireRandom( obj, params )

Example:

ssk.actions.target.acquireRandom( self, { targets = targets } )

target.loseOnDestroyed

Tell obj to wipe its current target if that target has been destroyed and is no longer a valid display object.

Returns true if obj no longer has a valid target.

ssk.actions.target.loseOnDestroyed( obj )

Example:

function player.enterFrame( self )

    -- Acquire a new random target if our last one was destroyed, or
    -- if we don't have one yet.
    if( ssk.actions.target.loseOnDestroyed( self ) ) then
        ssk.actions.target.acquireRandom( self, { targets = targets } )
    end
end

target.loseAtMaxDistance

Tell obj to wipe its current target if that target has moved beyond maxDist.

Returns true if obj no longer has a valid target.

ssk.actions.target.loseAtMaxDistance( obj )

Example:

function player.enterFrame( self )

    -- Acquire a new random target if our last one was destroyed, or
    -- if we don't have one yet.
    if( ssk.actions.target.loseAtMaxDistance( self, { maxDist = 200 } ) ) then
        ssk.actions.target.acquireRandom( self, { targets = targets } )
    end
end

target.loseAtMinAlpha

Tell obj to wipe its current target if that target's alpha is below alpha.

Returns true if obj no longer has a valid target.

ssk.actions.target.loseAtMinAlpha( obj )

Example:

function player.enterFrame( self )

    -- Acquire a new random target if our last one was destroyed, or
    -- if we don't have one yet.
    if( ssk.actions.target.loseAtMinAlpha( self, { alpha = 0.1 } ) ) then
        ssk.actions.target.acquireRandom( self, { targets = targets } )
    end
end

target.loseNotVisible

Tell obj to wipe its current target if that target is not visible.

Returns true if obj no longer has a valid target.

ssk.actions.target.loseNotVisible( obj )

Example:

function player.enterFrame( self )

    -- Acquire a new random target if our last one was destroyed, or
    -- if we don't have one yet.
    if( ssk.actions.target.loseNotVisible( self ) ) then
        ssk.actions.target.acquireRandom( self, { targets = targets } )
    end
end

target.drawDebugLine

This is a debug feature that draws a line between obj and its target.

ssk.actions.target.drawDebugLine( obj, params )

Example:

ssk.actions.target.drawDebugLine( self )

target.drawDebugDistanceLabel

This is a debug feature that draws a label showing the distance from obj to its target in pixels.

ssk.actions.target.drawDebugDistanceLabel( obj, params )

Example:

ssk.actions.target.drawDebugDistanceLabel( self, { yOffset = 40 } )

target.drawDebugAngleDistanceLabel

This is a debug feature that draws a label showing the distance from obj to its target in pixels, as well as the angle between obj forward and the target.

ssk.actions.target.drawDebugAngleDistanceLabel( obj, params )

Example:

ssk.actions.target.drawDebugAngleDistanceLabel( self, { yOffset = 40 } )

RoamingGamer Copyright © Roaming Gamer, LLC. 2008-2016; All Rights Reserved