Tutorial: Basic Spawning

In game design, a common aspect is object spawning, whether it be spawning a variable number of items and placing them randomly about the screen, or spawning items repeatedly on a timer increment. In this tutorial, we’ll step through a basic spawning module which includes the following features:

Set rectangular bounds on the screen within which to spawn objects.

Spawning an initial number of objects immediately (optional).

Spawning a flexible amount of objects on a repeating timer.

Ability to pause, resume, and stop the spawning process.

Initial Setup

Let’s begin by setting up a couple variables…

1

2

local spawnTimer

local spawnedObjects={}

The first variable, spawnTimer, is simply a Lua forward reference to the timer object which we’ll use to control the spawning process. The second variable, spawnedObjects, is a basic table into which we’ll insert items as they are spawned, providing us with a basic method to track them, count them, loop over them, etc.

Spawn Parameters

Now, let’s set up a table of basic spawning parameters which we can adjust to control the spawning:

1

2

3

4

5

6

7

8

9

local spawnParams=

xMin=50,

xMax=750,

yMin=20,

yMax=1100,

spawnTime=200,

spawnOnTimer=12,

spawnInitial=4

All of these parameters are optional and will default to various values (details later) but they should usually be set to appropriate values. The first four parameters define the rectangular region on the screen in which items will spawn, as defined by a minimum and maximum for both x and y. The next parameter (spawnTime) defines the timed increment, in milliseconds, upon which new items will spawn, assuming an amount of items is defined by the spawnOnTimer parameter. Lastly, the spawnInitial parameter can be used to instantly spawn a certain number of items, if the game design calls for it.

Basic Spawning Function

Next, we’ll need a basic spawning function which creates the objects:

1

2

3

4

5

6

7

8

9

10

11

12

13

14

--Spawn an item

local functionspawnItem(bounds)

--create sample item

local item=display.newCircle(0,0,20)

item:setFillColor(1)

--position item randomly within set bounds

item.x=math.random(bounds.xMin,bounds.xMax)

item.y=math.random(bounds.yMin,bounds.yMax)

--add item tospawnedObjects table fortracking purposes

spawnedObjects[#spawnedObjects+1] = item

end

The first few lines create a sample item — in this case a basic white vector circle. Obviously these items could be images, animated sprites, physics-enabled objects, etc.

The next few lines position the item randomly within the declared bounds. Recall that we declared these as the first four parameters in the spawnParams table.

The final line simply adds the new item to the spawnedObjects table, providing a simple method to track and manage the spawned objects.

Spawn Controller

The next step is to create a simple but reasonably powerful “controller” function which allows us to start, stop, pause, and resume the spawning process. This function will accept two arguments: an action argument which represents the action to perform and a params argument (this represents the spawnParams table that we declared above).

1

2

--Spawn controller

local functionspawnController(action,params)

Next, we’ll include a few lines to cancel the timer on the start and stop actions:

1

2

3

4

--cancel timer on"start"or"stop",ifit exists

if(spawnTimer and(action=="start"oraction=="stop"))then

timer.cancel(spawnTimer)

end

Recall that we forward-referenced the timer object (spawnTimer) on Line 1, so we use that reference here.

It’s fairly obvious why we cancel the timer on the stop action, but why do we cancel it on the start action as well? Basically, it’s just a fail-safe, so if the function is called multiple times with the start action, the previous timer object is cancelled and it can begin in a clean state.

Now, we’ll handle the most important spawning action: the start action. In the initial lines of this conditional code block, we gather/set various parameters based on those defined in the spawnParams table that we declared above. As noted, all of those parameters are optional, so if any are undefined, we set some basic defaults in their place.

1

2

3

4

5

6

7

8

9

10

11

12

13

--Start spawning

if(action=="start")then

--gather/set spawning bounds

local spawnBounds={}

spawnBounds.xMin=params.xMin or0

spawnBounds.xMax=params.xMax ordisplay.contentWidth

spawnBounds.yMin=params.yMin or0

spawnBounds.yMax=params.yMax ordisplay.contentHeight

--gather/set other spawning params

local spawnTime=params.spawnTime or1000

local spawnOnTimer=params.spawnOnTimer or50

local spawnInitial=params.spawnInitial or0

Note that if the minimum or maximum x and y values are not defined, defaults for the overall display content area are substituted. If a spawn timer increment (spawnTime) isn’t defined, 1000 is substituted (1 second), and if a number of items to spawn (spawnOnTimer) isn’t defined, the function will spawn 50 items on the set increment. Finally, if an initial spawn value (spawnInitial) isn’t defined, the function assumes that we don’t want to instantly spawn anything, and the value is set to 0.

Next, we’ll check if the spawnInitial parameter is greater than 0 and, if so, we’ll instantly spawn that amount of items. Note that we pass the spawnBounds table to the spawnItem function, so it recognizes the limits in which to spawn the items.

1

2

3

4

5

6

--ifspawnInitial&gt;0,spawnnitem(s)instantly

if(spawnInitial&gt;0)then

forn=1,spawnInitial do

spawnItem(spawnBounds)

end

end

Following this, we check if the spawnOnTimer parameter is greater than 0 and, if so, we queue up a timer which spawns that amount of items on the set spawnTime increment. Note that we set this timer object to the spawnTimer reference so we can pause, resume, or stop it later if needed. As above, we pass the spawnBounds table to the anonymous function so that all items are spawned within the desired bounds.

1

2

3

4

5

6

--start repeating timer tospawn items

if(spawnOnTimer&gt;0)then

spawnTimer=timer.performWithDelay(spawnTime,

function()spawnItem(spawnBounds);end,

spawnOnTimer)

end

The final step is to account for the pause and resume actions. This is simply accomplished by adding two more conditional code blocks and calling the necessary timer API:

1

2

3

4

5

6

7

8

9

--Pause spawning

elseif(action=="pause")then

timer.pause(spawnTimer)

--Resume spawning

elseif(action=="resume")then

timer.resume(spawnTimer)

end

end

Calling the Spawn Controller

From this point, the spawn controller can be easily called with four possible actions. Note that calling the spawnController function with "start" as the action parameter is the sole use case which requires the spawnParams table — the other actions assume that the spawning process is already underway.

spawnController( "start", spawnParams )

spawnController( "pause" )

spawnController( "resume" )

spawnController( "stop" )

In Conclusion

Hopefully this tutorial gives you a simple base module atop which to build a more comprehensive spawning methodology involving animated sprites, physics objects, variable time increments, and much more. To get this entire project code base, please download it from DropBox and feel free to modify it toward your needs.

Disclaimer: SDKNews.com only syndicates the blog entries from various SDK blogs.
We are not the creator/author of these entries (posts). Product names, brand names
and company names mentioned on this site may be trademarks of their respective owners.