Lua Metatable Tutorial – Complete Guide

Welcome to this comprehensive tutorial on Lua metatables, one of the most fascinating and complex aspects of the Lua programming language. Metatables are powerful tools in Lua, opening up vast possibilities for effective and efficient coding. As we delve into the library’s depths, you’ll learn how to utilize them to create unique prototypes, streamline operations, and utilize metatables’ versatility to simplify complex coding tasks.

What are Lua Metatables?

Metatables in Lua are tables that can redefine how other tables function by changing the default behavior of Lua operations. Acting as ‘hidden tables’, metatables allow us to customize how the Lua interpreter handles tables. This opens up endless possibilities in terms of programming constructs and serves as a striking example of how flexible Lua can be.

Why Should You Learn About Lua Metatables?

Learning about Lua metatables is like discovering a secret chamber full of untapped potential. By learning how to harness the power of metatables, you can make your code more concise, reusable, and efficient. Here’s why:

  • Elegance: Metatables can make your code cleaner and more readable by allowing you to customize table behavior.
  • Efficiency: You can avoid having to repeat similar pieces of code by using metatables, improving code efficiency.
  • Flexibility: With metatables, you can create objects, attributes, and methods. This is a noteworthy advantage in game development, where clean and flexible code is crucial.

In a nutshell, knowing about Lua metatables can give you an edge as a developer, especially in game development. If you’re interested in being part of that world, keep reading!

CTA Small Image




Creating Lua Metatables

Creating a metatable is as straightforward as creating an ordinary Lua table. Here’s how we can create a metatable and associate it with a table:

    -- Creating a regular table
    regularTable = {key1 = "val1", key2 = "val2"}

    -- Creating a metatable
    metaTable = {}

    -- Setting the metatable for regularTable
    setmetatable(regularTable, metaTable)

Index Metamethod

The `__index` metamethod is used when Lua attempts to read from a table entry that doesn’t exist. By defining the `__index` metamethod, you can redirect the lookup to another table or function. Let’s look at an example where the `__index` metamethod redirects Lua to another table:

    -- Creating tables
    regularTable = {key1 = "val1"}
    secondTable = {key2 = "val2"}

    -- Setting the metatable for regularTable
    setmetatable(regularTable, {__index = secondTable})

    print(regularTable.key1)  -- Prints "val1"
    print(regularTable.key2)  -- Prints "val2"

In the example above, when Lua failed to find ‘key2’ in ‘regularTable’, it used the `__index` metamethod to look for ‘key2’ in ‘secondTable’.

Newindex Metamethod

The `__newindex` metamethod is called when Lua attempts to write to a table entry that doesn’t exist. Here’s an example:

    -- Creating a table
    regularTable = {key1 = "val1"}
    -- Creating metatable with __newindex metamethod
    metaTable = { __newindex = function (table, key, value)
                    print("Attempt to write " .. tostring(key) .. " = " .. tostring(value) .. " in readonly table.")
                 end }

    -- Setting the metatable for regularTable
    setmetatable(regularTable, metaTable)
    regularTable.key2 = "val2" -- Attempt to write key2 = val2 in readonly table.

In this example, Lua calls the `__newindex` metamethod instead of adding ‘key2’ to ‘regularTable’, printing the message and preventing the write operation.

Arithmetic Metamethods

Arithmetic metamethods redefine the behavior of arithmetic operations in Lua tables. For example, we can define the `__add` metamethod to add the corresponding elements of two tables.

    -- Creating tables
    table1 = {1, 2, 3}
    table2 = {4, 5, 6}

    -- Metatable with __add metamethod
    metaTable = { __add = function(t1, t2)
                   local result = {}
                   for i = 1, #t1 do
                      result[i] = t1[i] + t2[i]
                   return result

    -- Setting the metatable
    setmetatable(table1, metaTable)

    -- Adding tables
    table3 = table1 + table2   

    for i, v in ipairs(table3) do
       print(v)  -- Prints 5, 7, 9

In this case, adding `table1` and `table2` actually adds the corresponding elements of the tables, thanks to the `__add` metamethod. Without the metamethod, Lua would throw an error, as by default, the ‘+’ operation is not valid for tables.

Equality and Comparison Metamethods

The `__eq` (equals), `__lt` (less than), and `__le` (less than or equal to) are comparison metamethods. We can redefine them to customize comparisons between table objects in Lua.

Here, we’ll illustrate an example with the `__eq` metamethod:

    -- Creating tables
    table1 = {1, 2, 3}
    table2 = {1, 2, 3}
    -- Creating metatable with __eq metamethod
    metaTable = { __eq = function (t1, t2)
                   for k, v in pairs(t1) do
                      if t2[k] ~= v then
                         return false
                   return true

    -- Setting metatables
    setmetatable(table1, metaTable)
    setmetatable(table2, metaTable)

    -- Comparing tables
    print(table1 == table2)  -- Prints true

In this example, we replaced Lua’s default table comparison (which only returns true if both operands are the same object) with our own function that compares the contents of the tables.

Call Metamethod

If Lua tries to call a table like a function and that table has a `__call` metamethod, Lua calls the metamethod instead. Here’s an example:

    -- Creating table
    t = {1, 2, 3}
    -- Creating metatable with __call metamethod
    metaTable = { __call = function(t, ...)
                      local sum = 0
                      for i, v in ipairs(t) do
                         sum = sum + v
                      return sum

    -- Setting the metatable
    setmetatable(t, metaTable)
    -- Calling the table
    print(t())  -- Prints 6

In this example, `t()` calls the `__call` metamethod, which sums up the values in the table `t`.

Tostring Metamethod

We can define how a table is converted to a string with the `__tostring` metamethod. Here’s an example:

    -- Creating table
    t = {1, 2, 3}
    -- Creating metatable with __tostring metamethod
    metaTable = { __tostring = function(t)
                      local str = "{"
                      for i, v in ipairs(t) do
                         str = str .. v .. (i ~= #t and ", " or "")
                      return str .. "}"

    -- Setting the metatable
    setmetatable(t, metaTable)
    -- Printing the table
    print(t)  -- Prints {1, 2, 3}

In this case, when `print` tries to convert `t` to a string, it calls the `__tostring` metamethod, which returns a string representation of the table.

Len Metamethod

The `__len` metamethod allows us to define the behaviour of the ‘length’ operation (`#`). Here’s an example:

    -- Creating table
    t = {1, 2, 3, nil, 5}
    -- Creating metatable with __len metamethod
    metaTable = { __len = function(t)
                      local count = 0
                      for _ in pairs(t) do
                         count = count + 1
                      return count

    -- Setting the metatable
    setmetatable(t, metaTable)
    -- Printing the table length
    print(#t)  -- Prints 5

Without the `__len` metamethod, Lua would consider the length of `t` to be 3, as it stops counting at the first `nil` in the sequence. But by defining the `__len` metamethod, we can count every entry in the table, including those after `nil` values.

These are just a few examples of the potential metatables hold. Mastering them opens ways to bend Lua to your needs and lets you build cleaner, more efficient code. We hope you have found this introduction to Lua metatables informative and helpful in your journey to mastering Lua!

More Metamethod Applications

Now that we’ve mastered the basics of Lua metatables and metamethods, let’s continue exploring their depths with additional examples.

Multiple Metamethods in One Metatable

A single metatable can contain multiple metamethods. Consider the following code that showcases using both the `__index` and `__newindex` metamethods:

    -- Creating tables
    baseTable = {base = "base"}
    derivedTable = {}
    -- Creating metatable
    metaTable = {
        __index = baseTable,

        __newindex = function(table, key, value)
          rawset(table, key, value)
          print('Added key "' .. key .. '" with value "' .. value .. '" to the table.')

    -- Setting the metatable
    setmetatable(derivedTable, metaTable)

    -- Testing
    print(derivedTable.base)  -- Prints "base" = "bar"   -- Prints 'Added key "foo" with value "bar" to the table.'

Here, the `__index` metamethod provides default values from `baseTable` to `derivedTable`, and the `__newindex` metamethod intercepts new entries and customizes their addition to `derivedTable`.

Metatable Inheritance

In Lua, we can mimic inheritance using metatables. When a table lacks a key-value pair, we can define the `__index` metamethod to look for it in another table. Here’s an example:

    -- Parent table
    parentTable = {parentKey = "parentValue"}

    -- Child table
    childTable = {}

    -- Metatable for childTable to inherit from parentTable
    setmetatable(childTable, { __index = parentTable })

    -- When childTable does not have 'parentKey', it looks for it in parentTable
    print(childTable.parentKey)  -- Prints "parentValue"

In this code, `childTable` doesn’t have the ‘parentKey’, but it still outputs ‘parentValue’ because it finds it in the `parentTable`.

Protecting Tables with Metatables

We can use metatables to protect tables, restricting changes to them. Let’s look at a read-only table that throws an error when someone attempts to change it:

    -- The original table
    myTable = {property = "Value"}

    -- Metatable that makes the table read-only
    metaTable = {
        __index = myTable,
        __newindex = function (table, key, value)
            error("ERROR: Attempt to modify read-only table.")

    -- New table assigned the metatable
    readOnlyTable = setmetatable({}, metaTable)

    -- Attempt to change a property's value = "New value"  -- Causes the error

Here, an attempt to change a property’s value in `readOnlyTable` triggers the `__newindex` metamethod, which throws an error.

Metatables and Type Checking

Metatables can also help us create custom types in Lua and allow us to check these types:

    -- Defining custom type
    myType = {}
    myType.__index = myType

    -- Defining method
        return setmetatable({value = x}, myType)

    function myType:getValue()
        return self.value

    -- Creating an instance
    instance =
    print(instance:getValue())  -- Prints "5"

    -- Type checking
    if getmetatable(instance) == myType then
        print('instance is of myType.')

In this piece of code, we first define a new type `myType` and add a method to it. When we create an instance of `myType` and assign it a metatable of `myType`, we can then check whether the metatable of `instance` equals `myType` to see whether it is of the custom type.

Mastering Lua metatables provides powerful tools for managing tables and customizing behaviors in Lua scripts. As we have shown, metatables are versatile and flexible tools in the Lua programming language. Dive in, explore further, and harness the potential of these great features. Happy coding!

Where To Go Next?

Your journey into the world of Lua programming and game development shouldn’t stop here. The power of metatables is just one aspect of Lua – a flexible language with a host of features to learn and master. Whether you’re excited about further exploring Lua’s potential, or you’re ready to take on a new challenge, we’ve got the right path for you.

We encourage you to check out our Roblox Game Development Mini-Degree. This comprehensive collection of courses are ideal for anyone interested in game creation with Roblox Studio and Lua. Covering everything from the basics of Roblox and scripting, to crafting melee battle games and exciting first-person shooter games, this program suits beginners and those who’ve already mastered the basics. As you complete the courses, you’ll develop key skills for the game development industry and build an impressive portfolio.

We also invite you to explore our broader collection of Roblox courses. On these training journeys, you’ll learn how to create games on this exciting platform while discovering more of Lua’s vast capabilities.

So, why wait? With Zenva, you can go from beginner to professional at your own pace, earning valuable certificates along the way. Happy learning and coding!


As we’ve explored in this tutorial, Lua metatables are a potent tool at your disposal as a programmer. They allow you to customize operations and behaviors, creating dynamic, efficient and elegant code. Understanding and mastering them can open doors to sophisticated program designs and an enhanced development experience.

Through Zenva, we’re proud to offer a wide range of opportunities to further enhance your coding skills. From our Roblox Game Development Mini-Degree to a variety of programming and game development courses, we’re here to empower your journey into the realm of coding. Now it’s your turn to write the next chapter of your coding journey. Let’s get coding!


Python Blog Image

FINAL DAYS: Unlock coding courses in Unity, Unreal, Python, Godot and more.