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

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 Non-Physics Movement
face 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

Facing (face)

face

Causes obj to rotate towards a specific angle or target. The rate of rotation can be immediate or at a specified number of degrees-per-second (dps).

This function is typically called in an enterFrame listener and once used must be called every frame. 

ssk.actions.face( obj, params )

Example:

function player.enterFrame( self )

    -- Rotate to face the object `enemy` at a rate of 180 degrees-per-second
    ssk.actions.face( self, { target = enemy, rate = 180 } )

end

Tip #1: While you must continue to call this function every frame after you first call it, you can pause the facing to temorarily suspend calculations. This is useful if you want obj to stop turning, of if you no longer have an angle/target to face.

Tip #2: If used in Combination with Target Acquisition functions, you don't need to provide a target. This will be handled for you.

Non-Physics Movement (move.*)

The actions move module provides functions to move object using 'calculated' movement in pixels-per-second.

move.forward

Move at a fixed rate, measured in pixels-per-second (pps), in the direction the object is facing.

ssk.actions.move.forward( obj, params )

Example:

function player.enterFrame( self )

    -- Move forward at 300 pixels-per-second
    ssk.actions.move.forward( self, { rate = 300 } )

end

move.at

Move at a fixed rate, measured in pps, in an arbitrary < x, y > direction.

ssk.actions.move.at( obj, params )

Example:

function player.enterFrame( self )

    -- Move 'right' at 300 pixels-per-second
    ssk.actions.move.at( self, { x = 300 } )

end

Physics Movement (movep.*)

The actions movep module provides functions to move, limit, and dampen movement using 'calculatoins' and physics methods.

All objects moved with the movep module must have physics bodies.

movep.forward

Move obj foward at a fixed rate, measured in pixels-per-second, using frame-by-frame calculations and obj:setLinearVelocity().

ssk.actions.movep.forward( obj, params )

Example:

function player.enterFrame( self )

    -- Move forward using physics at a rate of 300 pixels-per-second
    ssk.actions.movep.forward( self, { rate = 300 } )

end

movep.thrustForward

Move obj forward by applying a force using calculations and obj:applyForce().

ssk.actions.movep.thrustForward( obj, params )

Example:

function player.enterFrame( self )

    -- Move this object forward by applying a 100 units of force.
    ssk.actions.movep.thrustForward( self, { rate = 100 } )

end

movep.impulseForward

Move obj forward by applying a impulses (kicks) using calculations and obj:applyLinearImpulse().

This is suitable for use in timed or intermittent movements and can produce some very intersting responses.

ssk.actions.movep.impulseForward( obj, params )

Example:

-- Apply 15 impulses (kicks) to player, one every 250 milliseconds
function player.timer( self )
    ssk.actions.movep.impulseForward( self, { rate = 25 } )
end

timer.performWithDelay( 250, player, 15 )

movep.limitV

Limits an object's linear velocity to a maximum rate in pixels-per-second.

This is often used to place a cap on the maximum rate that can be produced using movep.thrustForward.

ssk.actions.movep.limitV( obj, params )

Example:

function player.enterFrame( self )

    -- Accelerate this quickly using 500 units of force, but
    -- limit the maximum velocity to 750 pixels-per-second
    ssk.actions.movep.thrustForward( self, { rate = 500 } ) 
    ssk.actions.movep.limitV( self, { rate = 750 } )

end

movep.limitAV

Limits an object's angular velocity to a maximum rate in degrees-per-second.

This is great for things like wheels and circles that turn due to frictional contact with other objects.

ssk.actions.movep.limitAV( obj, params )

Example:

function player.enterFrame( self )

    ssk.actions.face( self, { target = target, rate = 180 } )

end

movep.dampVert

This allows you to dampen linear velocity for just the vertical component of an object's movement.

ssk.actions.movep.dampVert( obj, params )

Example:

function player.enterFrame( self )

    ssk.actions.movep.dampVert( self, { damping = 1.5 } )

end

movep.dampHoriz

This allows you to dampen linear velocity for just the horizontal component of an object's movement.

ssk.actions.movep.dampHoriz( obj, params )

Example:

function player.enterFrame( self )

    ssk.actions.movep.dampHoriz( self, { damping = 1.5 } )

end

movep.dampDown

This allows you to dampen linear velocity for just the downward (+y) component of an object's movement.

ssk.actions.movep.dampDown( obj, params )

Example:

function player.enterFrame( self )

    ssk.actions.movep.dampDown( self, { damping = 1.5 } )

end

movep.dampNormal

This is a very specialized kind of damping that dampens motion that is 90-degrees away from forward motion.

The easiest way to think of this is damping like a tire. Tires slow movement that is at cross angles to the tire's forward vector.

Note: Not available yet.

ssk.actions.movep.dampNormal( obj, params )

Example:

function player.enterFrame( self )

    ssk.actions.movep.dampNormal( self, { damping = 1.5 } )

end

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