Lua Locals and Globals

While responding in Discord, I realised my write-up was really a bit big for Discord, and might well be lost over time (as it disappears from current commentary). To help people with understanding locals and globals in Lua I thought I would replicate it here, and if people have questions, additions or suggestions they can be collated here.


If you declare any variable local (in a Lua or script file), that variable is made local to the scope it has been declared in.
For example a local variable declared in a file scope will only be accessible within the file (not outside). A local variable declared within a for loop is only accessible within the for loop and so on.


Global variables are variables not declared with local - which means this is Lua’s default declaration method. For example if you declare this variable in your .script or .lua file:
my_var = 1
Then my_var is now a globally declared variable and will have global access for all scripts within the same Lua environment.

Global variables are truly global to any lua environment. Which means they are stored in the top level _G table that lua uses for the environment. It is important to note, that there can potentially be multiple lua environments running at once, and thus multiple Lua global tables, one within each environment.

You can interrogate globals anytime you want by printing them
If there are alot of globals this will be a big output and will likely be truncated.
If you want the top level of globals you can use something like:
for k,v in pairs(_G) do print(tostring(k), tostring(v)) end.
For example: To check variable X is in the global table, a very simple and quick check is
if _G.X == nil then ...

If you have assigned a global variable and it isnt visible in another file check that the project settings have Script → Shared State checked on. Additionally, some systems run their own scripts within their own Lua environment so this will limit what globals will be accessible. The best way around this if you need a shared data set, is to make one.

Sometimes you might need to get data from one lua environment to another. There are mechanisms for Defold and Lua that can help you do this.

Globals are bad?

This is a bit of a misnomer in Lua. To understand globals, you need to understand tables. All variables are stored within the _G table within the Lua env. Including locals. Thus, a global and a local is accessed in identically the same way. All data in lua is stored in hash tables (this is not entirely the case, but generally true) and thus whether you are looking up a global or local, there will be little or no performance difference. What can happen though, is the global namespace _G can get large, and your hash lookups may take longer, however for this to occur you need to be having hundreds of thousands of individual global variables to start to really see any degradation. This is true for local tables too though.

The other aspect of globals is because they are stored in _G then all scripts in the environment can easily access them. Local variables “lifetime” can be short (ie scope of a loop for instance) and this means external scripts will not easily be able to get access to them - but it does not mean they are not accessible - they are, but its complicated :slight_smile: So there is a benefit in general script protection.

Sharing Data

To solve shared data you can utilize features like messaging, modules (with state saving) and similar, or you could have a little database (like a sqlite table) or you can define your own event system or data exchange system in lua (there are many libs on github that do this). Generally, I would recommend Defolds messaging system - it is the simplest and best way to manage most data exchanges.

For more details on lua modules and how to use them have a look at the excellent documentation here:

For details on the Defold GUI system which is an example of scripts that do not share env state with the go system, have a read of these documents:

If you are running into trouble understanding some of the nuances of Defold or Lua, there is a great community on Discord that should be able to help. Additionally, dig through the tutorials, manuals, and sample code that can be found on the Defold website, and sample projects on Github that use Defold. The Lua-users group is also an amazing source of great information on how to best utilize Lua.

I hope this helps people if you are struggling a little with the Lua side of Defold’s scripting. And please hassle me if you want/need to have a chat about Lua and Luajit. Im happy to help people get a good understanding of Lua - it is a very powerful scripting system and when used well, it can bring many times production and development improvements.