# Use of classes for lua extensions

I'm asking about a very small domain. One-off extension scripts. IE, defining a new weapon for scorched earth.

When providing and API for small extension I've seen two approaches.

The API exposes classes that the extender then subclasses, overriding the needed methods.

--# weapons/flame_missile.lua

--#extender pulls in a predefined weapon base class
require "weapon.missile"

--# luabind syntax for classes
class "flame_missile" (missile)

function flame_missile:__init()
self.hotness = 10
self:set_cost(42)
end

function flame_missile:on_hit( who )
who:take_damage(self.hotness)
who:ignite()
end


In the other approach the api just exposes accessors and sandboxes the script, re-executing the file with each new missile and using the globals as the instance's state.

--# weapons/flame_missile.lua
hotness = 10
cost = 42

--# extender just knows that an on_hit function will be called
--# when the missile hits something.
function on_hit( who )
who:take_damage(hotness)
who:ignite()
end


NOTE: in my example who's api is OO. I'm not interested in whether OO should be used in the extension API. I'm more interested if OO should be used to incorporate user extensions into the game.

The first one feels more C++-y. So I'm a little more comfortable with from a software engineering standpoint. However, one-off scripts don't need to fit together into a larger architecture. Further, they could be written by less proficient coders, so all the fancy OO might be lost on them.

I really like how concise the sandbox approach is. But it's a little limiting (only one missile per file, inheriting behavior from another weapon is no longer possible. I'd really like to define my extension api like this but I'm a little wary as it's a radical departure from classic C++ programming style.

Which method do you prefer?
Is there an even better way to elegantly incorporate extensions into the game?

I would base that decision solely on the proficiency of the user base with programming languages, code structure and code constructs.

From a programmer's perspective, I prefer your first approach.

If I had to write the system for less proficient users, I'd take the second approach. I may even hide the function call in something more human-readable:

--# weapons/flame_missile.lua
Parameters
{
hotness = 10,
cost = 42,
}

--# extender just knows that an on_hit function will be called
--# when the missile hits something.
OnHitEvent
{
damage_taken = Parameters.hotness,
should_ignite = true,
}


OnHitEvent is simply a Lua function taking a table as parameter, which wraps the function call. The parameters are named, well defined and documented and will be checked for any typos. It's a bit more effort behind the scenes but significantly boosts understanding of the code to any non-programmer.

The system that Supreme Commander uses is that you can subclass classes, then you define the class-specific functions and data like so:

MyUnit = Class(MyUnitBase) {
Create = function(self, blah)
MyUnitBase.Create(self, blah)
--do other junk
end,
}


The way the code is set up, is all of the classes that have to be in C code are exposed to the lua environment for subclassing. The above method is much like your first, and i would recommend that you take it. It makes it quite usable for both programmers and modders (of which i'm both). I started out programming to this model, and while i didn't completely understand things, it worked perfectly well and made sense to me.

I honestly feel that either one would be perfectly fine (I personally would go with the first) - provided that you comment it thoroughly and have a wiki explaining what everything does. People can pick up on pretty much any file format, how long it takes directly correlates to how much documentation you have.