Making a Tome of Knowledge

[Mobbstar]

This topic is explaining how to create a Tome of Knowledge (ver 2.0) for your mod!

Read the readme.txt for up-to-date information.

 

Getting Started

 

1. Download the core mod and install it. It needs to be enabled for the tome to be constructable.
2. Make a valid mod. That means a mod folder with modinfo.lua and modmain.lua, as explained by just about any "getting started" guide in the mod forums.
3. Open the ToK modmain and readme for comparison.

 

Writing the Pages

 

For this, I recommend importing a script. To do so, follow these steps:

1. in modmain, place local my_pack = GLOBAL.require "myfile"
2. Create a Lua file in the scripts folder (mods/mymod/scripts) that is called the same as "myfile" in the above snippet. It needs to be a Lua file.
3. At the end of the file, write return my_pack

 

You must make a data table now. If you did the above steps, place it above the return line. Else, place it in modmain. Begin like this:

 

local my_pack = {

    --placeholder

}

 

That is your data table. You need to add a new table for each page. Do that like so:

 

local my_pack = {

    {

        --more placeholder

    },

    {

        --more placeholder

    },

}

 

The above would make two empty pages. You can fill them with the following (or not, all is optional):

 

{

    head = "This is the title of the page",

    page = [[This is the actual text on the page, which

goes over several lines (presumably). You

may need to tinker with the exact layout

(line length, etc.). In this case we use a

multi-line string, that's the double brackets.]],

    atlas = "images/guide/mybookimages/thatimage.xml",

    tex = "thatimage.tex",

},

 

Keep in mind that "atlas" and "tex" are bound together, you need both for showing an image. You also need to load the assets in modmain.lua first:

 

Assets = { --use the existing Assets table if there is one!
    Asset("ATLAS","images/guide/mybookimages/thatimage.xml"),
    Asset("IMAGE","images/guide/mybookimages/thatimage.tex"),
}

 

Now we're done with that milestone!

 

Using MakeTome

 

To actually make the book, you need to call a function called "MakeTome" in modmain.lua:

for k,v in pairs(GLOBAL.ModManager.mods) do
    if v.modinfo and v.modinfo.id == "tok" then

       GLOBAL.MakeTome("myprefab",my_pack,"myanim")
    end
end

 

But this function can do more! This is a list of arguments/parameters you can give:

1. prefab name - Straight forward. This is what the book is called in game code.
2. pages - The data table for pages (as seen previously)
3. animation - Get a list of standard animations in readme
4. custom build - Optionally, use non-standard textures (explained in readme)
5. spawn behaviour - Whether and how your tome spawns in new worlds. false or nil mean "I handle that", true or "NEAR" mean "spawn near the player start location" and "FAR" means "spawn anywhere in the world".
6. spawn chance - If nil or 1, your tome always spawns. if between 0 and 1, the tome only spawns occasionally (lower numbers make it rarer). If -1, force-spawn is disabled entirely too.
7. ToC - explained a bit later
8. locked to chapters - explained a bit later

 

Now you have the means of making a standard tome of knowledge to inform players of your mod's content!

 

Assembling a Table of Contents

 

This is advanced tome-making. The table of contents (toc) is a list of buttons that can link to pages or trigger functions.

 

Similiar to the pages, you need a data table to begin with, and a new table in that for every button. However, there are different fields you can give:

 

{

    name = "Name in ToC",

    goto = "Name of target header",

    condition = HypotheticalTestWhetherClickableFunction,

    cb = HypotheticalOnClickedFunction,

},

 

To compliment that, the option "locked to chapters" previously mentioned allows you to prevent the reader from scrolling to a new chapter (header). Thus you can lock certain pages until the ToC button activates.

 

Closing

 

That's all you need to know to make what you want from ToK, be it a guide or a spellbook!

 

Some very advanced things are possible to good modders, but with this guide even the new and unskilled ones should be able to make something cool. It's not a shame if you don't understand the full potential or point behind certain functions.

 

If you have concern, requests, problems, bug reports, whatever, just feel free to tell me. I'm open for constructive criticism, I'm open for notifications. As long as you have a point, I will listen to you.