Learning Lua Step-By-Step (Part 18)

This entry is part 17 of 25 in the series Learning Lua Step-By-Step

Post Stastics

  • This post has 1032 words.
  • Estimated read time is 4.91 minute(s).

Metatables in Lua

Unleashing the Power of Customized Behaviors

Lua, offers a feature known as metatables that allows developers to create customized behaviors for tables. We’ve already seen metatables in the section on OOP but they are so important that I wish to revisit them again. Metatables are essentially tables themselves, but they define the behavior of other tables when certain operations are performed on them. In this comprehensive guide, we will delve deeper into the world of metatables in Lua, exploring their syntax, functionality, and practical applications.

Understanding Metatables

At its core, a metatable is a regular Lua table that defines the behavior of another table. When Lua encounters an operation on a table that is not directly supported (such as addition, subtraction, or accessing a non-existent key), it checks the metatable of that table to determine how to handle the operation. This mechanism enables developers to implement operator overloading, custom indexing, inheritance-like structures, and more.

Creating Metatables

Let’s start by creating a simple metatable and attaching it to a table:

-- Define a metatablelocal mt = {}

-- Define a metatable method
mt.__add = function(table1, table2)local result = {}

    for k, v inpairs(table1) do
        result[k] = v
    endfor k, v inpairs(table2) do
        result[k] = v
    endreturn result
end-- Create a table and set its metatablelocal table1 = { 1, 2, 3 }
setmetatable(table1, mt)

-- Create another tablelocal table2 = { 4, 5, 6 }

-- Perform addition using the metatablelocal result = table1 + table2

-- Print the resultfor k, v inipairs(result) doprint(k, v)

In this example, we define a metatable mt with a custom __add method that performs element-wise addition of two tables. We then attach this metatable to table1 using setmetatable. When we perform the addition operation (table1 + table2), Lua uses the __add method from the metatable to handle the operation.

Metamethods and Their Usage

Metatables use metamethods, which are predefined keys in the metatable that Lua recognizes and uses for specific operations. Here are some commonly used metamethods and their purposes:

  • __add: Defines behavior for the addition operator +.
  • __sub: Defines behavior for the subtraction operator -.
  • __mul: Defines behavior for the multiplication operator *.
  • __div: Defines behavior for the division operator /.
  • __mod: Defines behavior for the modulus operator %.
  • __pow: Defines behavior for exponentiation ^.
  • __unm: Defines behavior for unary minus -.
  • __concat: Defines behavior for string concatenation ...
  • __len: Defines behavior for the length operator #.
  • __eq: Defines behavior for equality ==.
  • __lt: Defines behavior for less than <.
  • __le: Defines behavior for less than or equal to <=.
  • __index: Defines behavior for table indexing.
  • __newindex: Defines behavior for setting values in a table.
  • __call: Defines behavior for calling a table as a function.

Let’s explore some of these metamethods in action:

Custom Indexing and New Indexing

local mt = {}

mt.__index = function(table, key)if key == "default"thenreturn"This is the default value."elsereturnrawget(table, key)

mt.__newindex = function(table, key, value)iftype(value) == "number"thenrawset(table, key, value * 2) -- Double the value when settingelserawset(table, key, value)
    endendlocal myTable = {}
setmetatable(myTable, mt)

print(myTable.default) -- Output: This is the default value.

myTable.customKey = 10print(myTable.customKey) -- Output: 20 (doubled due to metatable behavior)

In this example, we define __index and __newindex metamethods to customize table indexing and setting values, respectively. The __index method returns a default value for a specific key (default in this case), while the __newindex method doubles numeric values when setting them in the table.

Operator Overloading

local Vector = {}
Vector.__index = Vector

function Vector.new(x, y)localself = setmetatable({}, Vector)
    self.x = x
    self.y = y
    returnselfendfunction Vector.__add(v1, v2)return Vector.new(v1.x + v2.x, v1.y + v2.y)
endlocal v1 = Vector.new(1, 2)
local v2 = Vector.new(3, 4)
local v3 = v1 + v2

print(v3.x, v3.y) -- Output: 4 6

In this example, we define a Vector class with a metatable that includes an __add metamethod for vector addition. This allows us to use the + operator directly on Vector instances, providing a clean and intuitive syntax for vector arithmetic.

Practical Applications of Metatables

Metatables open up a wide range of possibilities for customizing Lua’s behavior. Here are some practical applications where metatables shine:

  1. Object-Oriented Programming (OOP): Metatables can be used to implement OOP concepts such as classes, inheritance, and method overriding in Lua, making code organization and reuse more structured.
  2. Data Structures: Metatables can be leveraged to create specialized data structures like queues, stacks, trees, and graphs with custom behaviors and operations.
  3. Domain-Specific Languages (DSLs): Metatables enable the creation of DSLs within Lua by defining custom syntax and semantics for specific problem domains.
  4. Game Development: Metatables are extensively used in game development for implementing game entities, behaviors, physics, and AI systems with flexible and efficient code.
  5. Scripting Interfaces: Metatables can provide scripting interfaces for applications, allowing users to extend and customize the functionality of the software through Lua scripts.


  1. Operator Overloading: Create a metatable for complex numbers that supports addition, subtraction, and multiplication operations. Test your implementation with different complex numbers.
  2. Custom Indexing: Implement a metatable for a dictionary-like table that provides default values for missing keys. Also, ensure that numeric values are automatically doubled when set in the table.
  3. OOP in Lua: Design a simple class hierarchy using metatables to represent shapes (e.g., Circle, Rectangle) with methods for calculating area and perimeter. Demonstrate inheritance and method overriding.
  4. Data Structure: Use metatables to implement a stack data structure with push and pop operations. Ensure that the stack behaves correctly with multiple elements and edge cases.


Metatables are a powerful feature in Lua that empowers developers to create flexible and expressive code by customizing the behavior of tables. By understanding metamethods and their usage, developers can leverage metatables to implement advanced functionality, data structures, object-oriented patterns, and more. With metatables, Lua becomes not just a scripting language but a versatile tool for building complex systems and applications.


  1. Lua Reference Manual
  2. Programming in Lua
  3. Lua Users Wiki
  4. Lua Patterns
  5. Lua Programming Gems

These resources provide comprehensive documentation, tutorials, and community insights for mastering Lua programming and utilizing metatables effectively in your projects.

Series Navigation<< Learning Lua Step-By-Step (Part 17)Learning Lua Step-By-Step (Part 19) >>

Leave a Reply

Your email address will not be published. Required fields are marked *