How to Use the New Time Functions

Combined, the BeebeGames Class version 1.2 and 1.3 features 6 new time-related functions, one of which being a complete replacement for the built-in timer.performWithDelay() as well as a—much requested—table that holds all active timers.

Before we get started on anything, you’ll want to import the beebegames.lua module into your project and localize the functions you’ll be using:

game = require( "beebegames" )

local resetTimeCounter = game.resetTimeCounter
local getCountedTime = game.getCountedTime
local performAfterDelay = game.performAfterDelay

local pauseAllTimers = game.pauseAllTimers()
local resumeAllTimers = game.resumeAllTimers()
local cancelAllTimers = game.cancelAllTimers()

resetTimeCounter() and getCountedTime()

These two functions go hand-in-hand and have to do with counting time as it passes. This can be useful for many different scenarios, for example, checking to see how long it took a player to complete a round… but I’ll leave the “when” up to you.

Here’s how to use it:

-- create a new counter variable
local timeCounter = resetTimeCounter()

The above code will start/restart the time counter. Then, when you want to find out how much time has passed (in milliseconds), use the next function:

local timePassed = getCountedTime( timeCounter )

You must pass your counter variable as an argument to getCountedTime() in order for things to work properly.

Now for the really good stuff…

performAfterDelay

You’re probably already familiar with Corona’s built-in timer.performWithDelay() function, because performing a specific action after a set delay in time is a task that is common to many games and apps.

However, there is one limitation to the built-in function that could cause a lot of unnecessary headache: the inability to pause and resume active timers! Thankfully, the BeebeGames Class has you covered with performAfterDelay() :-)

As a quick note, you’ll still be responsible for keeping track of and removing active timers during screen transitions, etc. In fact, everything is still the same as the old timer.performWithDelay() function, only with some minor changes and additions.

The most notable change is the fact that you specify your delay in seconds instead of milliseconds. So if you need to get between seconds, you simply pass decimals. So for a 350 millisecond delay, you’d pass 0.35 instead. Here’s what the whole function looks like:

performAfterDelay( secondsToWait, functionToCall, howManyTimes, isFps60 )

The last argument is also new. If you modified your config.lua and have your app set to 60 FPS, you’ll pass true to this argument. Otherwise, you can set it to false or leave it out (it defaults to 30 FPS). This is so timing stays on track (and is responsible for allowing you to pause/resume each timer).

As with the old function, passing 0 to the howManyTimes argument will result in an infinitely-looping timer (will continue to go until it is paused or canceled).

In the example below, we’ll call a function to print the words “Hello World” to the console after 10 seconds:

local printMessage = function()
    print( "Hello World" )
end

local newTimer = performAfterDelay( 10, printMessage, 1, true )

And if you want to pause the timer mid-way through:

newTimer:pause()

And to resume:

newTimer:resume()

When you’re finished with the timer, you can destroy it by calling:

newTimer:cancel()
newTimer = nil

You cannot resume a canceled timer. It is also best practice to always assign these timers to a variable (or you won’t be able to pause/resume), and to make all timer variables local. You’ll also need to nil-out the variable you used to hold the timer manually.

One Table to Rule Them All

Beginning in version 1.3, the BeebeGames Class includes a—much requested—table to hold all active timers (timers that haven’t been canceled), as well as functions that will allow you to pause, resume, or cancel all of these timers with just one line of code respectively.

All timers are held in a table called beebegames.activeTimers, and below is how you can perform bulk actions on all of your timers:

  • pauseAllTimers() –> pauses all timers

  • resumeAllTimers() –> resumes all timers

  • cancelAllTimers() –> cancels all timers

All of the functions above put every single timer on the same level, so if you have some paused and some active, all will still be paused and resumed upon calling the above functions.

I hope you find all of the new additions in version 1.2 and 1.3 useful—I know my own projects will. Once again, you can get the module from the Corona Code Exchange.

HostGator $3.96

$3.96 for web hosting – used by jonbeebe.net. Get started today.