Superloading:
Superloading allows you to replace or add code to the beginning or end of an arbitrary class function. Superloading is the preferable way for add-ons to modify ToME code.
When ToME is running a module or add-on and needs to load a file, it first checks the superload folder of any loaded mods or add-ons; if the file it is looking for is located in these directories, it loads that. So far-- just like overloading. The difference is that there is a function that is accessible from superloaded files that is named "loadPrevious" which loads the default version of the file in question. For instance, your superload might read:
local _M = loadPrevious(...)
--load the default file; keep track of the module in question with our _M variable
local base = _M.levelup (or whatever function you are superloading)
--create a back up of the function we plan to modify
function _M:levelup()
--replace the function
-- Do stuff "before" loading the original file
local base_return = base(self, 2)
-- we're now calling our backup function, and assigning it's return value to a value we'll return at function end
-- since we're calling without colon operator, we need to send explicit self
-- Do stuff "after" loading the original file
return base_return
-- our return; our own procedures could modify this return if its important
end
return _M
--return the module in question for any files that require our module
Note that superloads can stack. If we have two add-ons loaded, both of which modify _M:levelup, the base of one of those is going to refer not to the true base, but to the other addon's levelup() function.
These techniques are not particular to superloaded files; creating a backup function, then rewriting it with wrapped functionality, can be done anywhere in the code. loadPrevious, however, is a function that is only defined for files in the superload directory.
Using superloaded files, you can replace individual functions rather than entire modules of functions. Typically, people will still refer to these functions as being "overloaded" rather than "superloaded", because the function has been replaced rather than wrapped with extra functionality-- two mods that modify the same function, without calling a base function, will cause problems.
The best way to use superloads is to always call a base function inside of every function replaced.
Note also that it is generally poor form to superload files in /data directories. These are rarely actual modules, but rather calls to functions to create entities, create talents, define maps, etc.
Even though the following example doesn't demonstrate it, files in the engine may be superloaded as well. To do this, simply create a superload/engine/ directory, just as you might a superload/mod/ directory.
An example demonstrating superloading can be found at http://te4.org/dl/tmp/tome-example.teaa
A .teaa file is simply a renamed zip that contains the whole addon, this way the players do not even have to unzip it!
The example addon illustrate how to add a new class, new talents, new timed effects and how to hook onto a few useful locations in the code. Note that this example is slightly out of date.
Details about Superloading
16:42 DarkGod overload repalces a whole *file*
16:42 Reenen ok
16:42 DarkGod superload is hum ..
16:43 Reenen superload adds to a currently existing function
16:43 DarkGod when the engine wants to load a class; say mod.class.Foo
16:43 DarkGod it loads the module's one
16:43 DarkGod then it checks each addons if there is a superload for it
16:43 DarkGod if there is it loads the superload, passing it the existing one
16:43 DarkGod there the code can do waht it wants with it
16:44 DarkGod basically you replace a method with your own
16:44 DarkGod and *if* you wish your own method to call the previous one you do it
16:44 DarkGod (and it is a good idea to do so, so taht addons can "chain" superloads)
For a great source of more information, see http://forums.te4.org/viewtopic.php?f=36&t=36784