Difference between revisions of "Addons"

Revision as of 03:10, 25 January 2014

Addons are way for third parties to modify existing modules inside t-engine. Since the game Tales of Maj'Eyal is a t-engine module, this is how you write addons for ToME, just like the ones in the Steam Workshop.

Intro

You're making an addon. The addon is named "coolstuff". The first thing you do is make a directory "tome-coolstuff" inside your Steam install of ToME. On my mac, that path is:

~/Library/Application Support/Steam/SteamApps/common/TalesMajEyal/game/addons/

Someone with Windows or Linux, please add the appropriate paths for those platforms!

Your addons directory should have these files in it already:

tome-addon-dev.teaa
tome-items-vault.teaa
tome-stone-wardens.teaa

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

Getting Started

Every addon has an init.lua file. The init.lua file looks like this:

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

long_name = "My Awesome Addon"
short_name = "coolstuff"
for_module = "tome"
version = { 1, 1, 6 }
weight = 100
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

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

Those last four are super important, because they determine what directories in your addon ToME will look at.

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: load.lua. 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 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 tome-example.teaa 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.)

Grammar and Syntax

• The addon folder must be in the format [ModuleName]-[AddonName]. For you, that means tome-coolstuff is your folder name.
• The short_name in init.lua must match the [AddonName]. For you, that means coolstuff.

Overloading

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

Copy tome.team somewhere, rename it to tome-1.1.5.zip 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 tome.team. 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 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 loadPrevious(...) 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 superload directory:

tome-coolstuff/superload/data/general/objects/egos/light-boots.lua

... and we'd make sure that our init.lua 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 Existing Stuff

Notice how we created that _M variable above and then didn't do anything with it. That's because we were only creating new content, rather than tweaking existing content. The _M variable is where the existing content lives. Let's modify an existing talent in another superload file, let's modify the cost of the Arcane spell Arcane Power:

tome-coolstuff/superload/data/talents/spells/arcane.lua

local _M = loadPrevious(...)

Talents.talents_def.T_ARCANE_POWER.sustain_mana = 20

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 data directory are purely data, and stored in easily accessible structures, you don't need _M to get them. _M is generally used for stuff in the mod directory: the most dangerous stuff to modify. Here's an example which modifies the "levelup" function in mod/Actor.lua

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

Uploading your Addon

You've been playing around with your addon, making changes and copying stuff from other popular addons. You've tested your stuff, and you're pretty satisfied that it won't crash the game. Good job! Now you want to share your work.

• Main Menu -> Options -> Developer Mode (bottom option)
• Start a new game.
  • Note that being in Developer Mode puts an extra screen between "New Game" and building a character. Pick the top option ("ToME").
• Hit ctrl+d and pick the bottom option (just hit the up arrow)
• MD5s are now calculated automatically. You will probably never need to get an MD5. Ignore that unless you know why you need one.
• You will only need to register your addon ONCE, so after you do that the first time, you can ignore that option too.
• If you've already registered your addon, pick "Publish Addon to te4.org". This is the option you'll pick over and over as you create new versions.
• If you're using Steam, then after you upload to te4.org, hit ctrl+d again and this time pick "Publish Addon to Steam Workshop"