Corona SDK Modules Demystified

Corona Level: Beginner

Building a Module

When you first start programming with Corona you’ll want to weave modules into your coding skill-set as early as possible. Though the idea of creating a module might seem like an advanced topic, I can assure you it’s quite the opposite.

As an example let’s create a player module where we can keep a score and other variables. Create a new file called “mod_player.lua” and let’s build out the module by entering the following:

-- mod_player.lua

-- Init table
local M = {}

-- Private items
local score = 0
local function addToScore( amount )
  score = score + amount

-- Public items
function M.setScore( points )
  addToScore( points )

function M.getScore()
  return score

-- Return Module
return M

That is pretty much the minimum you need for a module, which if you notice simply starts out as a lua table.

We then create a local method addToScore and a property score. If you create “local” methods and properties, then these items will only be accessible from within the module itself. Though the idea of “private” items is not very big in lua, this is how you would emulate privacy from other languages.

We then follow up with the public facing methods setScore and getScore. We don’t have any public properties in this example. Instead we are using the popular “getter” and “setter” methodology, which makes for better bookkeeping.

Let’s take a look at how to use our new module in our code. Open your main.lua file and enter the following:

-- main.lua
local player = require( 'mod_player' )

print( "score", player.getScore() )

player.setScore( 2000 )

print( "score", player.getScore() )


score  0
score   2000

Pretty simple stuff. We use the require function to pull in our module and assign it the player variable. We call the getScore and setScore and print out the results.

Now, if you were to add the following lines to the main.lua and run it:

print( player.score )


You will receive something like this in the output:


Runtime error
  main.lua:12: attempt to call field 'addToScore' (a nil value)

As you can see those items are private to the module itself. When addToScore is called from within the module, everything is fine. Again, there isn’t really any specific need to privatize items in your module. The general rule of thumb in lua is that if you don’t want to access items, then don’t.

The Module Lifecycle

An important thing to remember about modules is that once you require one — using require('mod_name') — it is essentially “global” to the project, unless you nil the reference. You have access to any of the modules public methods and properties anywhere in your project that the module is “required”. Once “required” it is your responsibility to rid the module from the memory pool if you no longer want its functionality.

Again, when you first access a module it will remain accessible and in memory until you specify otherwise.

I try to make sure my modules offer global functionality most of the time. If you’re using Storyboard then I find smaller functionality can most often live perfectly well inside of a scene. In other words, there is no need to over-complicate the code with modules unless its needed.

Modules With Storyboard

Using modules with Storyboard based projects is a very nice way to share functionality between scenes. To learn more about using modules with Storyboard take a look at the globals module, which I wrote about in this entry.

I hope this helps slightly demystify modules for use in your Corona SDK® based projects.

Happy coding.