How We Used Object Oriented Programming

[carsakiller]

Introduction

Hi there!

In this post, I want to talk about how we used Object Oriented Programming (OOP) patterns to make our lives much easier. While it may seem complex if you are unfamiliar, it definitely helped us a lot with code readability and speeding up feature implementation.

Planning

Originally, we were planning on taking a more functional approach to Carsa's Commands v2, as was done in v1. However, it can become quite messy when there are functions everywhere and things are not organized. Since we are dealing with data like players, vehicles, and roles, I figured it would be a good idea to try and turn them into objects so that we could have a Player object that can then contain methods like Player.equip(). This should help with organizing and keeping all of the functions I need for players within the Player object scope.

In order to properly implement OOP with classes in Lua, you can use metatables, unfortunately, we cannot access metatables in the Stormworks implementation of Lua. Luckily, tables are themselves objects in Lua and allow for us to implement a sort of OOP in Lua.

Our Implementation

Now, let's take a look at how we implemented OOP using tables and started our second rewrite for Carsa's Commands v2.

The Role "Class"

First, lets look at our Role "class"

---Class that defines each role
---@class Role
local Role = {}
--#region

---Creates a role object
---@param self Role This role object's instance
---@param name string The name of the new role
---@param active? boolean If this role should be active by default
---@param admin? boolean If this role should give it's members admin privileges
---@param auth? boolean If this role should give it's members auth privileges
---@param commands? table A table indexed by command names with a value of true for each command this role should give access to
---@param members table? A table indexed by the `steamIDs` of the players that have this role
---@param no_delete boolean? If the role cannot be deleted
function Role.constructor(self, name, active, admin, auth, commands, members, no_delete)
    self.name = name
    self.active = active or true
    self.admin = admin or false
    self.auth = auth or false
    self.commands = commands or {}
    self.members = members or {}
    self.no_delete = no_delete or false

    self.save()
end

The first thing to note is the line

local Role = {}

This is creating a table for us that will contain all of the values and methods of our role objects. All objects we create later will contain everything that this Role table contains.

Next, we have a constructor function that is inside the Role table. This should look similar to how a constructor looks in other languages such as JavaScript. We are going to call this function when we want to create a new role. This constructor uses the self keyword to assign some values to this role such as name and active, which are passed in to the function as arguments or have default values.

Finally, the constructor calls a save() method on self which is used for saving the object into g_savedata.roles so the data can persist.

---Save this role to g_savedata
---@param self Role This role object's instance
function Role.save(self)
    g_savedata.roles[self.name] = serialize(self)
end

We will get to what the serialize() function later.

Creating a Role Object

Now that we have the blueprint for a role, we need to actually create a role object. For this, we created a new() function, heavily inspired by JavaScript's new operator.

---Creates a new object from a class
---@param class table A class like `Players` or `Role`
---@return table object A new object created using a class
function new(class, ...)
    local obj = {}

    for k, v in pairs(class) do
        if type(v) == "function" then
            -- replace every function with a middleware function that sets the "self" argument
            obj[k] = function(...)
                return v(obj, ...)
            end
        end
    end

    obj.constructor(...)
    return obj
end

This function allows us to create a new object from a class like Role. All it really does is copy all functions from the class and set the self argument as a new empty table. It then calls the constructor function on the new object, passing the additional arguments and returns the new, now initialized, object.

It can be used like this:

local adminRole = new(Role, 'Admin', false, true, true)

This creates a new role called Admin that is inactive but has admin and auth permissions.

Saving An Object to g_savedata

When saving our object to g_savedata, we will want to remove the functions from the object as there is no need to include them. We just need to save the number, string, etc. values.

---serializes an object for storing to g_savedata
---@param object table The object to serialize
---@return table data The serialized object data to save
function serialize(object)
    local data = {}
    for k, v in pairs(object) do
        if type(v) ~= "function" then
            data[k] = v
        end
    end
    return data
end

serialize() does this by creating a new table that only contains non-function values from the passed object and then returning it.

Reading An Object From g_savedata

Now there is the problem that when we go to read our role from g_savedata, all of it's methods are missing. Now we have to deserialize our data and re-initialize our objects. We do this in onCreate(), where we get all of our data from g_savedata.

for role_name, data in pairs(g_savedata.roles) do
    G_roles.create(role_name, data.active, data.admin, data.auth, data.commands, data.members, data.no_delete)
end

G_roles.create() is a function in a Roles object that contains a list of all of the roles. All G_roles.create() really does is call new() with the data it is passed (like we did above) and then adds it to it's roles table.

---Creates a role and adds it to this roles container
---@param self RoleContainer This role container object's instance
---@param role string The name of the role
---@param active boolean? If the role is active or not
---@param admin boolean? If the role grants admin permissions
---@param auth boolean? If the role grants auth permissions
---@param commands table? A table indexed by the names of the commands this role should have access to
---@param members table? A table indexed by the `steamIDs` of the players that have this role
---@return boolean success If the role was created successfully
---@return string err Why the role was/wasn't created
---@return string errText Text explaining why the role was/wasn't created
function RoleContainer.create(self, role, active, admin, auth, commands, members)
	if self.roles[role] then
		return false, "ROLE ALREADY EXISTS", "The role " .. quote(role) .. " already exists"
	end
	self.roles[role] = new(Role, role, active, admin, auth, commands, members)
	return true, "ROLE CREATED", quote(role) .. " has been created"
end

Conclusion

While using OOP for Carsa's Commands may have taken up more characters, and took a long time to rewrite everything, it was definitely worth it. It allowed us to keep everything much more organized and allowed us to implement new features quickly. I definitely recommend you give it a try.