Factory Manager - ssk.factoryMgr.*

The factory manager is a module designed to help you manage and access object builders: Factories

The manager uses a uniform interface and the expectation that every factory will return a single object reference.

Manager Functions

The manager has thes functions:

ssk.factoryMgr.register( name, path ) - Adds a new 'factory' definitition at path to the factory manager under name.
ssk.factoryMgr.init( [ name [, params ] ] ) - Initializes a named (name) factory or all not previously initialized factories if called with no name value. The optional params table can contain any values you want passed to the factor -y /-ies
ssk.factoryMgr.reset( name [, params ] ) - Resets a named (name) factory or all factories if called with no name value. The optional params table can contain any values you want passed to the factor -y /-ies
ssk.factoryMgr.new( [name [, group [, x [, y [, params ]]]]] ) - Calls the named (name) factory to build an object, passing it the optional parameters if you specify them.

Factory Instance Functions

All factories should support the new() function: + new( [ group [, x [, y [, params ]]]] )

Typical Factory Structure

The file containing a factory definition usually has the following structure:

Header - Copyright info and name of factory.
require() Statements - modules and libraries used by the factory are required here.
Localizations - In this section, I localize a number of commonly used ssk features.
- Tip: I may not end up using all of these features in the module, but the cost of localization is low and having a standard set of localized features makes for easier coding and duplication later.
Locals - Next I declare any file-level locals that may be used by the module.
- Ex: initialized - Most modules have a flag used to determine if the module has been initialized yet. This is a safety mechanism I use to avoid accidental double initializations.
Forward Declarations - This is where I declare any functions that may be used by the module, but which I don't expose as public members of the module. +Tip: I rarely use this, but keep a spot for it nonetheless. Again this is about keeping a known structure and enabling easy duplication.
Factory Module Begins - The module function definitions start here.
- factory.init( params ) - A method do one-time initialization of the factory needs it. Typical things that would be done here are, pre-loading images, defining sprite-sheets, etc.
  - params - Optional table of parameters.
- factory.reset( params ) - This function is typically called at the begining of a game (not between levels) to reset the factory module if it is needed.
  - params - Optional table of parameters.
- factory.new( group, x, y, params ) - This is function responsible for building this factories game object(s).
  - group - Display group to insert objects into.
  - x, y - x- and y- position to place 'object' at.
  - params - An optional table of parameters. This is where we pass special data and arguments a factory may need.
  - Tip: - You don't need to use the values of these arguments in every builder, but by having a minimialistic and yet common new() signature we make factories easy to use, easy to write, and easy to understand.
return factory - The last line of every factory module, where we return the factory module reference.

Factories Are Extensible

The above factory definition is pretty basic, but due to the fact that factories are modules, it is easy to extend this concept.

For example, if you include a built-in-editor in your game, it may be useful to add these functions to your factories:

editor_widget() - A function to create a drag-n-drop widget representing this object type for the ditor.
editor_new() - A function to create the editor instance of this object.
... - Whatever else you need.

Example Factory - `smiley.lua`


-- =============================================================
-- Copyright Roaming Gamer, LLC. 2008-2016 (All Rights Reserved)
-- =============================================================
-- Smiley Factory - Just a simple example...
-- =============================================================
local physics   = require "physics"

-- =============================================================
-- Localizations
-- =============================================================
-- Commonly used Lua Functions
local getTimer          = system.getTimer
local mRand                 = math.random
local mAbs                  = math.abs
--
-- Common SSK Display Object Builders
local newCircle = ssk.display.newCircle;local newRect = ssk.display.newRect
local newImageRect = ssk.display.newImageRect;local newSprite = ssk.display.newSprite
local quickLayers = ssk.display.quickLayers
--
-- Common SSK Helper Modules
local easyIFC = ssk.easyIFC;local persist = ssk.persist
--
-- Common SSK Helper Functions
local isValid = display.isValid;local isInBounds = ssk.easyIFC.isInBounds
local normRot = ssk.misc.normRot;local easyAlert = ssk.misc.easyAlert

-- =============================================================
-- Locals
-- =============================================================
local initialized = false

-- =============================================================
-- Forward Declarations
-- =============================================================

-- =============================================================
-- Factory Module Begins
-- =============================================================

local factory = {}

-- ==
--    init() - One-time initialization only.
-- ==
function factory.init( params )
    if(initialized) then return end
    initialized = true
end

-- ==
--    reset() - Reset any per-game logic/settings.
-- ==
function factory.reset( params )
end

-- ==
--    new() - Create new instance(s) of this factory's object(s).
-- ==
function factory.new( group, x, y, params )
    params = params or { size = 60 }

    local smiley = newImageRect( group, x, y, "images/smiley.png", 
                                {   size = params.size  } )

    return smiley
end

return factory

Learn By Example

The best way to learn how factories work is by example. Please look in the validation code that comes with SSK2 and pay particular attention to example Factory Manager found here:

~/validation/tests/factories/*.lua.

Validation Sample: 001_factoryTest.lua

-- =============================================================
-- Copyright Roaming Gamer, LLC. 2008-2016 (All Rights Reserved)
-- =============================================================

-- =============================================================
-- Localizations
-- =============================================================
-- Lua
local getTimer = system.getTimer; local mRand = math.random
local mAbs = math.abs
local strMatch = string.match; local strGSub = string.gsub; local strSub = string.sub
--
-- Common SSK Display Object Builders
local newCircle = ssk.display.newCircle;local newRect = ssk.display.newRect
local newImageRect = ssk.display.newImageRect;local newSprite = ssk.display.newSprite
local quickLayers = ssk.display.quickLayers
--
-- Common SSK Helper Modules
local easyIFC = ssk.easyIFC;local persist = ssk.persist
--
-- Common SSK Helper Functions
local isValid = display.isValid;local isInBounds = ssk.easyIFC.isInBounds
local normRot = math.normRot;local easyAlert = ssk.misc.easyAlert
--
-- SSK 2D Math Library
local addVec = ssk.math2d.add;local subVec = ssk.math2d.sub;local diffVec = ssk.math2d.diff
local lenVec = ssk.math2d.length;local len2Vec = ssk.math2d.length2;
local normVec = ssk.math2d.normalize;local vector2Angle = ssk.math2d.vector2Angle
local angle2Vector = ssk.math2d.angle2Vector;local scaleVec = ssk.math2d.scale
ssk.misc.countLocals(1)

-- =============================================================
-- =============================================================
local test = {}

local factoryMgr = ssk.factoryMgr

factoryMgr.register( "smiley", "tests.factories.example1" )
factoryMgr.register( "corona", "tests.factories.example2" )
factoryMgr.register( "rg", "tests.factories.example3" )

factoryMgr.init()

function test.run( group, params )
   group = group or display.currentStage
   params = params or {}

   local tmp = factoryMgr.new( "rg", group, centerX, centerY, { size = 80 } )

   local tmp = factoryMgr.new( "corona", group, centerX - 100, centerY, { size = 50 } )

   local tmp = factoryMgr.new( "smiley", group, centerX + 100, centerY )


end


return test