Introduction to beebegames.newObject()

Yesterday, I released the BeebeGames Class, so today I’m going to describe how to use one of the main features, and that’s the newObject() function. In a nutshell, here’s what it does:

the newObject() function replaces display.newImage, display.newImageRect, AND movieclip.newAnim for those who want to get an image object on the screen, positioned, and into a group with just one line of code.

It does more than that, but that’s the basics of it. Before we do anything though, we need to import the beebegames.lua module into our project. If you have more than one module in your app, then I would NOT make it local so other modules can access it:

game = require( "beebegames" )

And that’s it. To speed things up, you should store some of the functions you’ll be using as local calls like so:

local newObject = game.newObject

And that covers the preliminary work that needs to be done to start using the newObject() function.

To better demonstrate the effectiveness of this new function, I’ll go over the old way of doing things, and then I’ll show you the BeebeGames Class alternative. First, we’ll cover static images, and then go on to cover animated objects.

Let’s say we want to place a new display object on the screen, at the coordinates 150, 150, and we want that image to be compatible with content scaling. We also want it’s opacity (alpha) to be set to 0.5 (50% opacity). Lastly, we need that object to be placed in a group called imagesGroup.

Here’s how you would normally do it:

local myObject = display.newImageRect( "myImage.png", 48, 64 )
myObject.x = 150; myObject.y = 150
myObject.alpha = 0.5
imagesGroup:insert( myObject )

Okay, so that’s not that bad. But let’s use newObject() to condense all that into one line of code. First, here’s what the newObject() function with its arguments looks like:

newObject( { imageTable }, width, height [, x, y, secondsBetweenFrames, fps60, alpha, parentGroup ] )

And here’s how we use that to create our object:

local myObject = newObject( { "myImage.png" }, 48, 64, 150, 150, nil, nil, 0.5, imagesGroup )

The two nil values have to do with animations, and since this object isn’t animated, we simply set those arguments to nil.

Now going from 4 short lines to one long one might not be enough of a payoff to you, but now that you’ve created the object using newObject(), you now have access to these useful methods:

  • doTransition( )

  • move( )

  • moveTowards( )

  • getAngleTo( )

  • getDistanceTo( )

  • destroy( )

Plus a few animation-related functions. Speaking of animations, let’s go over the old movieclip method of creating an animated object. There’s also spritesheets, but that’s even more complex.

Let’s create an animation that consists of two images (a character walking, for instance), looping indefinitely with 200 milliseconds between the frames, with all the same properties as the last object we created.

Remember, this is the old movieclip method:

local movieclip = require( "movieclip" )

local myObject = movieclip.newAnim{ "myImage1.png", "myImage2.png" }
myObject.x = 150; myObject.y = 150
myObject.alpha = 0.5
myObject.frameNumber = 1
imagesGroup:insert( myObject )

local objectAnimation = function()
    if myObject.frameNumber == 1 then
        myObject:stopAtFrame( 2 )
        myObject.frameNumber = 2
    else
        myObject:stopAtFrame( 1 )
        myObject.frameNumber = 1
    end
end

local myObject.animTimer = timer.performWithDelay( 200, objectAnimation, 0 )

This is where you’ll see the BeebeGames Class really shine. Here’s how to do that same thing using beebegames.newObject():

local myObject = newObject( { "myImage1.png", "myImage2.png" }, 48, 64, 150, 150, 0.2, true, 0.5, imagesGroup )
myObject:startAnimation()

If you set your app to 60 FPS in your config.lua, then you should set the fps60 argument to true, otherwise, set it to false (or nil). This is because the BeebeGames Class uses frame-based animations, rather than time-based. That way, animations are able to be paused/resumed very easily.

Everything starts paused automatically, so make sure your the game.isActive variable is set to true if your animations aren’t playing.

Also, notice that the secondsBetweenFrames is set to 0.2. In movieclip, you use milliseconds, with newObject, you use actual seconds.

Some animation-related methods you now have access to using newObject() include:

  • startAnimation( )

  • stopAnimation( )

  • nextFrame( )

  • showFrame( )

One last thing, if you want your animation to be paused, simply set game.isActive to false, and then back to true when you’re ready to resume. The same goes for the new doTransition() function, but that goes beyond the scope of this article.

And that’s it as far as the newObject() function goes! There’s a lot more to the BeebeGames Class than just that, but I wanted to go over the newObject function because it is one of the main benefits to using the module.

Remember, you can get the BeebeGames Class at the Corona Code Exchange when you’re ready to get started.

To read more entries, visit the archives or subscribe to the RSS feed.