Class Mechanism

Poly uses Lua metatables to simulate a class mechanism. The following example class illustrates Poly’s Class API:

-- require Poly's Class API
local Class = require('__poly__.Class')

-- == Define a new class called ExampleClass ======================================
local ExampleClass = Class:new('examples.ExampleClass')

-- define ExampleClass's "new" function (a.k.a. its constructor)
function ExampleClass:new(param1, param2)
    -- return a new object of this class (metatable is automatically set by Poly)
    return {
        attr1 = param1,
        attr2 = param2
    }
end

-- define a class method, e.g., a setter for attr1
function ExampleClass:set_attr1(attr1)
    self.attr1 = attr1
end

-- create a new object of ExampleClass
local my_example_object = ExampleClass:new(1, 'foo')
-- call class method 'set_attr1' with argument 5 on my_example_object
my_example_object:set_attr1(5)


-- == Define a new class that is derived from ExampleClass ========================
local DerivedClass = Class:new('examples.DerivedClass', ExampleClass)

-- override "new" of ExampleClass
function DerivedClass:new()
    -- call super class constructor
    return ExampleClass:new(2, 'bar')
end

-- create a new object of DerivedClass
local my_derived_object = DerivedClass:new()
-- call inherited class method 'set_attr1' with argument 10 on my_derived_object
my_derived_object:set_attr1(10)

Some additional notes on the Class API:

• The class method new is a special member function. It is the class’ constructor and, if defined, has to return a new instance of the class. It can optionally take arguments. You do not have to set instance’s metatable yourself, Poly takes care of that for you.

• To make the class mechanism work, all calls to member and static member functions of a class have to use the colon notation, e.g., ExampleClass:new(1, 'foo') and my_example_object:set_attr1(5). Definitions of class methods have to use the colon notation as well, e.g., function ExampleClass:set_attr1(attr1) ....

• The first parameter to Class:new is the class’ identifier. It can be any unique string, but usually should be the class’ name prefixed with the class’ path, e.g., examples.ExampleClass in this example, because example class is defined in a file in the examples folder. Adding the class’ path as prefix allows to have multiple classes with the same name.

• The Class:new function takes an optional second argument base_class. This allows for class inheritance, when passing another previously defined class. The derived class provides all functions of the base class. Defining functions in the derived class overrides the corresponding function in the base class. Note that when overriding the new function, you are responsible for correctly initializing the base class object, e.g., by calling the base class constructor.

• Poly may persist class instances in Factorio’s global table, e.g. for event handling, so it is generally a good idea to only store compatible types in class instances, e.g. numbers, strings, LuaGuiElements, and not functions, for example.