Lua addons

For an example of a Lua integration done pretty well, I'd point you toward Urho3D. The way Urho3D works is that scene nodes comprise a set of 3D transformations (position, rotation, scale) and a list of Components, where the Components are things like models, animations, lights, etc... Components can also be an instance of a ScriptObject, which encapsulates a scriptable component. The framework provides certain "hooks" that the scripter can implement. For example, the scripter can provide a Start() function in the script object code, which will be called when the component is created and initialized, a Stop() function to be called when the component is removed, a TransformChanged() function which will be called whenever the scene node's transformation is changed, and so forth. Script object's can also be subscribed to listen for and respond to certain events.

As an example, in my game I have certain objects such as trees, mushrooms, etc... which are lootable. The player can loot them to obtain resources to use for other things. In order to implement the lootable behavior, I implemented a Lootable component as a script object. The object encapsulates a table of data detailing which resources it holds, and subscribes in Start() to listen for a particular user event, OnLoot, to know when to do its thing. In the event handler for OnLoot, the object packages up the resources it holds and sends them off to the sender of the OnLoot event, then passes off a PrepareToDie event to the lootable object itself, to alert the object that it has been looted and should die now.

All of that behavior is encapsulated in a Lua object, an instance of a meta-object called ScriptObject. This ScriptObject functionality is provided by the framework.

Lootable=ScriptObject()

function Lootable:Start()
	self:SubscribeToEvent(self.node, "Loot", "Lootable:HandleLoot")
	self:SubscribeToEvent(self.node, "IsLootable", "Lootable:HandleIsLootable")
	self.resources={}
	self.vm=VariantMap()
	
	self.node:GetVars():SetBool("lootable", true)
end

function Lootable:SetResources(resources)
        self.resources=resources
end

function Lootable:HandleIsLootable(eventType, eventData)
	eventData:SetBool("lootable", true)
	
	local r=""
	local n,v
	for n,v in pairs(self.resources) do
		r=r..n..";"
	end
	eventData:SetString("resources", r)
end

function Lootable:HandleLoot(eventType, eventData)
	local looter=eventData:GetPtr("Node", "looter")
	if not looter then return end
	local r=""
	--local vm=VariantMap()
	local n,v
	for n,v in pairs(self.resources) do
		self.vm:SetInt(n,v)
		r=r..n..";"
	end
	
	self.vm:SetString("resources", r)
	looter:SendEvent("AddResources", self.vm)
	
	self.node:SendEvent("PrepareToDie", self.vm)
end

Above is the whole of the lootable component as it now stands. In Lua, I would add an instance of Lootable to a node with the call lootablecomponent=node:CreateScriptObject("Lootable") and populate it with lootablecomponent:SetResources({wood=3,leaves=5}). In the C++ framework, when the creation call is made, a Component of type LuaScriptInstance is created and added to the node. The LuaScriptInstance is associated with the named ScriptObject class instance, then the Start() method is called on the object to let it do its own setup.

In my opinion, this is an instance of Lua script integration done well. The scripters can simply instance ScriptObject objects, and write the custom function hooks and event handlers. Unfortunately, writing the boilerplate code to get to that level of functionality really isn't all that easy. You might take a look at the LuaScript branch of the Urho3D engine source code to see how they set it up. In particular, look at the LuaScript, LuaFunction, LuaFile and LuaScriptInstance classes.