GBC Object Pool – Pooling Complex Physics Objects

GBC Object Pool is a CoronaSDK plugin that simplifies the management of Object Pooling. In this article, I describe the method to pool complex physics objects.

A complex physics object consists of several display objects connected together by a physics joint. I recently added another example to the GBC Object Pool sample app that demonstrates how to pool complex physics objects. This article will go through some of the code in that example.

Using the traditional way of object creation, you would need to create multiple objects and joints in order to display a complex physics object. Depending on the complexity of this object, there may be visible performance issues (screen stutter or delay) when creating these types of objects. Utilizing object pooling will reduce or eliminate this delay.

The general solution is to create as many pools that are needed in order to create the object, and then join them via joints after you extract them from the pool. For example, connecting similar items may only require one pool. In the example, though, we connect three circles to a square, so I created two pools… every time we wish to display this type of complex object (when we tap on the screen), we grab one square from the square pool and three circles from the circle pool, and join them together.

squarePool = GBCObjectPool.init(createMainObject, returnMainObject)
GBCObjectPool.create(squarePool, 10, 0, true) 
        
circlePool = GBCObjectPool.init(createSatellite, returnSatellite)
GBCObjectPool.create(circlePool, 100, 0, true)

-- This creates a complex object using multiple pools when the screen is touched.
-- We grab 1 object from the square pool, and 3 objects from the 
-- circle pool.
-- Notice, we then create the proper joints, and event listeners.
-- We also have to save a reference to the joints and the circles so that
-- they can be returned to the pool later.
function onScreenTap(event)
    local Circles = {}
    local Joints = {}
    
    local square = GBCObjectPool.get(squarePool)
    
    for i = 1, 3 do
        Circles[i] = GBCObjectPool.get(circlePool)
    end
    
    square.x = event.x
    square.y = event.y
    Circles[1].x = square.x - 70
    Circles[1].y = square.y
    Circles[2].x = square.x + 70
    Circles[2].y = square.y
    Circles[3].x = square.x + 5
    Circles[3].y = square.y + 70
    
    Joints[1] = physics.newJoint("rope", square, Circles[1], 0, 0, 0, 0)
    Joints[2] = physics.newJoint("rope", square, Circles[2], 0, 0, 0, 0)
    Joints[3] = physics.newJoint("rope", square, Circles[3], 0, 0, 0, 0)
    
    -- Save a reference to all the joints and circles in the square object
    -- We will need this later when placeing back into the pool
    square.satellites = Circles
    square.joints = Joints    
    
    square:addEventListener("tap", onSquareTap)
    
    return true
end

We need a way to track all the objects used, so we can return them to the pool later. Notice above, we save a reference to the joints and circles in the square object itself. Since the square object will contain a listener that will start removing everything when tapped, it’s a great place to store it.

The code below is the listener that is called when you tap the square. This function will dismantle the complex object and return the parts to their appropriate pool.

-- When you tap on the square object, the entire complex object
-- is returned to the proper pools.
-- Note that since we are not destroying objects (we are pooling them)
-- we have to manually remove and nil all physics joints, since we created them
-- when we created this complex object.
function onSquareTap(event)
    local object = event.target
    
    -- remove the physics joints
    for i = #object.joints, 1, -1 do
        display.remove(object.joints[i])
        object.joints[i] = nil
    end
    
    -- put the circles back into the pool
    for i = #object.satellites, 1, -1 do
        GBCObjectPool.put(circlePool, object.satellites[i])
    end
    
    -- nil out the joint and circle variables
    object.satellites = nil
    object.joints = nil
    
    -- remove listener from square
    object:removeEventListener("tap", onSquareTap)
    
    -- place square into pool
    GBCObjectPool.put(squarePool, object) 
    
    return true
end

That’s really all there is to it. In summary, just remember:

  • When creating a complex object
    • Grab the objects from the pools
    • Create your physics joints
    • Store a reference to all the objects and joints used
  • To remove a complex object
    • Remove the joints using display:remove(joint) or joint:removeSelf()
    • Return all items to the appropriate pools

[divider]

GBC Object Pool Performance

The sample app included in my GBC Object Pool plugin has a performance scene that compares object pooling to traditional object creation. I took that scene, and modified it to execute 100 times automatically. After each run, it dumped the amount of time it took to execute.

Here are the results I experienced using the following settings in the app:

  • Display 100 images, 200 times
  • Use colors, physics, and scaling
  • Display the images using traditional methods, then pooling. Record both times
  • Repeat 100 times

Note that while the app is running, I did not attempt to access the devices, and no other apps were running in the background. Basically, I ran the app, clicked Start, and walked away.

Windows Desktop Performance

For this test, I used my development machine… a 2 year old Dell XPS 8700 with 16GB RAM.

Notice the tightness of the pooling times? GBC Object Pool (and object pooling in general) is pretty consistent, operating on average around 6700 milliseconds to perform the task.

The blue dots represents the traditional method of creating 200 images via display.newImageRect() 100 times, and then removing them. Notice the sporadic times and wide distribution. The dotted line represents a linear average where 50% percent of the dots are above the line and 50% are below the line. Notice that all of the object pooling tests are mapped below this line.

Android Performance

Moving on to smart devices, I used my Android phone… a 2+ year old mid-range Samsung.

Again, notice how pooling provides a more consistent result and maps faster than traditional average times?

What is interesting is the first few items between run 1 and run 10 (and again between run 61 and 75). Check out the data listed here:

Run
Traditional
Pooling
Difference
1 7706 6678 -13.34%
2 7962 6722 -15.57%
3 8844 6671 -24.57%
4 7787 6680 -14.22%
5 8030 6651 -17.17%
6 8243 6739 -18.25%
7 7679 6928 -9.78%
8 7221 6846 -5.19%
9 7278 6988 -3.98%
10 7318 6886 -5.90%

Something definitely was happening on the phone (memory allocation? background OS task?), but you will notice that it wasn’t a noticeable factor when using pooling. Since it is not possible to know when or if a background task will start executing while a user is playing your game, I would expect the game to stutter if you were creating a lot of objects during this time via the traditional method.

Announcing: GBC Object Pool

My latest plugin, GBC Object Pool, is now in the marketplace.

The GBC Object Pool plugin allows the CoronaSDK developer to easily and quickly implement object pooling within your application. Using two lines of code, you can create an object pool. GBC Object Pool optimizes the management of pooling, allowing for object reuse and eliminates garbage collection inherently found with traditional create/destroy functions.

The plugin provides several examples of pooling.  If there are any questions or requests, please let me know. I plan on writing more examples, blogs, and perhaps some videos on the  use of this plugin.

Some links:

GBC Object Pool in the Corona Marketplace

Link to documentation

Link to example code

[divider]