Addons

2026-01-19T21:11:57Z

Ratbuddy: note on the addon dir structure

[[Category:Development]][[Category:Addons]]
Addons are way for third parties to modify existing modules inside t-engine, as well as publish them in the Steam Workshop. (Here's a non-comprensive [[Addon List]].) This page covers how you write addons for ToME.

==Intro==

You're making an addon. The addon is named "coolstuff". The first thing you do is make a directory "tome-coolstuff" ('''the tome- prefix is mandatory or your addon will not load!''') inside your Steam install of ToME. On my mac, that path is:
~/Library/Application Support/Steam/SteamApps/common/TalesMajEyal/game/addons/

And on Windows, it's usually something like
C:\Program Files (x86)\Steam\SteamApps\common\TalesMajEyal\game\addons

On Linux, the path is
~/.steam/steam/SteamApps/common/TalesMajEyal/game/addons

Your addons directory should have these files in it already:
tome-addon-dev.teaa
tome-items-vault.teaa
tome-possessors.teaa

If you can't find the directory, search for one of those file names.

===Getting Started===

Every addon has an <nowiki>init.lua</nowiki> file. The <nowiki>init.lua</nowiki> file looks like this:

-- My Cool Addon
-- tome-coolstuff/init.lua

long_name = "My Awesome Addon"
short_name = "coolstuff" -- Determines the name of your addon's file.
for_module = "tome"
version = {1,3,1}
addon_version = {1,0,0}
weight = 100 -- The lower this value, the sooner your addon will load compared to other addons.
author = {'coolguy@invalid.com'}
homepage = 'iamsocool.geocities.com'
description = [[Oh my god this stuff is so totally cool.
Holy crap I mean it's really super cool, like, wow.
]] -- the [[ ]] things are like quote marks that can span multiple lines
tags = {'cool', "stuff", 'cool stuff'} -- tags MUST immediately follow description

overload = true
superload = false
data = true
hooks = true

''addon_version'' is (unsurprisingly) the version of your addon. This is used by the game for automatically downloading addon updates. It's also useful if players want to see which addon version they're currently using. Set it to {1,0,0} initially and increment the value when releasing updates.

''version'' is the module (i.e., ToME) version required for the addon. When making a new addon, you should typically set this to the current ToME version. When releasing addon updates, you should modify this value if your addon changes rely on features from a more recent ToME version.

Properly setting ''overload'', ''superload'', ''hooks'', and ''data'' is super important, because they determine which directories in your addon will be loaded by the game.

===Directory Structure===

* '''overload''': Files in this directory will automatically replace files in the base game. This is very powerful but also incredibly dangerous. (Of course, replacing things like icons is less dangerous than replacing code.)
* '''superload''': Files in this directory will be read and executed after the base game's file of the same name. This is very powerful but much less dangerous. This is a great way to add content (like new Artifact items) or tweak content (modify a talent's cost or requirements) without accidentally stepping on other tweaks or future content updates.
* '''data''': Files in this directory will just sit there and be ignored unless you explicitly tell the game to read them. Files in this area live in their own "namespace" and filenames here will never interfere with other addons or the base game. This is a great place to put new classes, talent trees, or races.
* '''hooks''': Only one file in this directory is automatically executed: <nowiki>load.lua</nowiki>. This file is a great way to get your "data" files executed at the proper time. It's also a way to augment some parts of the game which specifically support hooks: the Example module shows how the "Actor:takeHit" function is hooked to make the tourist take no damage. You can also use hooks to load add-on data in to the module, eg. new talents. Find a list of available hooks [[hooks|here]].

The Example addon can be found here: http://te4.org/dl/tmp/tome-example.teaa

A .teaa file is simply a renamed zip that contains the whole addon, so feel free to rename and unzip your favorite addon to see a living example of all the stuff discussed in this article. The <nowiki>tome-example.teaa</nowiki> addon illustrates 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 it's a bit old, though.) When zipping, make sure to zip the files but not the folder. For example, tome-addonname.zip/init.lua, not tome-addonname.zip/tome-addonname/init.lua.

You can also just put a folder 'tome-addonname' in addons and it will be loaded directly, no need to zip or rename.

== Grammar and Syntax ==
* The addon folder must be in the format <nowiki>[ModuleName]-[AddonShortName]</nowiki>. For you, that means <nowiki>tome-coolstuff</nowiki> is your folder name.

===Overloading===
Each <nowiki>.teaa</nowiki> file is just a zip file. The main ToME game code is stored in <nowiki>game/modules/tome.team</nowiki>, and it is also just a renamed zip file.

Copy <nowiki>tome.team</nowiki> somewhere, rename it to <nowiki>tome-1.1.5.zip</nowiki> and unzip it.

You'll see two directories: "data" and "mod". Most of the stuff you'll want to mess with at first is in "data".

When you use overload to replace a file, the path and name must match exactly the structure in <nowiki>tome.team</nowiki>. So for example, to replace the types of leather boots in the game, I'd look in the unzipped ToME code and find:
tome-1.1.5/data/general/objects/leather-boots.lua
... and so to overload that, I'd create a file in my addon:
tome-coolstuff/overload/data/general/objects/leather-boots.lua

===Superloading===

Just like overloading, superloading requires that you know the file structure of the game so you can make your files get read and executed at the right time. When the game reads in your superload file, you can get access to the previous file's contents using the <nowiki>loadPrevious(...)</nowiki> function.

For example, if we wanted to add a new boot ego, we could do something like this. First, we'd find the boot ego code:
data/general/objects/egos/light-boots.lua

Next, we'd make a file in our <nowiki>superload</nowiki> directory:
tome-coolstuff/superload/data/general/objects/egos/light-boots.lua

... and we'd make sure that our <nowiki>init.lua</nowiki> file had the line:
superload = true

We're ready to add the boot ego!

local _M = loadPrevious(...)
newEntity{
power_source = {arcane=true},
name = " of sensing", suffix=true, instant_resolve=true,
keywords = {sensing=true},
level_range = {1, 50},
rarity = 4,
cost = 2,
wielder = {
see_invisible = resolvers.mbonus_material(20, 5),
see_stealth = resolvers.mbonus_material(20, 5),
blind_immune = resolvers.mbonus_material(30, 20, function(e, v) v=v/100 return 0, v end),
},
}

return _M
====Modifying mod Stuff====

Hold on, that example still didn't use _M at all! So what is _M for? Since most things in the <nowiki>data</nowiki> directory are stored in easily accessible structures, you don't need _M to get them. _M is generally used for stuff in the <nowiki>mod</nowiki> directory: the most dangerous stuff to modify. Here's an example which modifies the "levelup" function in <nowiki>mod/Actor.lua</nowiki>. Your file for this code should be in <nowiki>/superload/mod/Actor.lua</nowiki>.
local _M = loadPrevious(...)
local base_levelup = _M.levelup

function _M:levelup()
-- Do stuff "before" loading the original file

-- execute the original function
local retval = base_levelup(self)

-- Do stuff "after" loading the original file

-- return whatever the original function would have returned
return retval
end

return _M

Whenever possible, superloaded functions should call the original function rather than replacing it entirely. This maintains compatibility with other addons.

==Uploading your Addon==

{{:Addon Uploading}}

Meteor rain (talent)

2016-12-24T16:40:17Z

Ratbuddy: Ratbuddy moved page Meteor rain (talent) to Meteor Rain (talent): In-game it says Meteor Rain, not Meteor rain.

#REDIRECT [[Meteor Rain (talent)]]

Meteor Rain (talent)

2016-12-24T16:40:16Z

Ratbuddy: Ratbuddy moved page Meteor rain (talent) to Meteor Rain (talent): In-game it says Meteor Rain, not Meteor rain.

{{Ability_box
|game_version=1.4.6
|name=Meteor Rain
|category_type=[[NPC Only (category type)|NPC Only]]
|category=Spell
|image=Meteor rain.png
|cooldown=30
|cost=70 Mana
|desc=
Uses arcane forces to summon {{cts|3.3|4.8|log}} meteors that fall on the ground, smashing all around in a radius 2 for {{ctspd|15|250}} fire and {{ctspd|15|250}} physical damage.
The hit zone will also turn into lava for 8 turns.
The effects will increase with your Spellpower.
}}

Tales of Maj'Eyal - User contributions [en]

Addons

Meteor rain (talent)

Meteor Rain (talent)