Creation of Add-on libraries

An example add-on library for examination and testing is available at https://github.com/cwisniew/test-maptool-add-on-lib

There are two main ways to create an Add-on Library:

1. Create the library files and directory structure from scratch; or
2. Export a Library Token as an Add-on Library.

Each of these approaches is described below.

1. Create the library files and directory structure from scratch

Firstly you will need a text editor. There are many of them mentioned below -- if in doubt, use VS Code.

• Emacs
• Neovim
• Vim
• VS Code

After choosing a text editor, create a new directory to hold your Add-on.

Top-level files in the Add-on are metadata files; they hold information about your Add-on. The only file your Add-on needs to be accepted by MapTool is library.json.

You may have other non-metadata files in a subdirectory named library.

For macro code, you may have a mtscript directory inside library. Both of those subdirectories may have a publicly accessible directory which must be named public.

This structure is described in more detail in Technical definition of Add-on Libraries.

Creating library.json

The only required fields are

• a name string,
• an authors array,
• a short description string, and
• a namespace string.

The other fields are described on the Technical definition of Add-on Libraries page. Most of these are self-explanatory. Just remember bad things will happen if you use the same namespace as someone else, so try to use at least 3 words or a reversed domain name. In the example below, the namespace is io.github.Azhrei, which is a reverse of a hypothetical documentation page, Azhrei.github.io.

An example of a minimal library.json could be

 {
   "name": "test",
   "authors": ["you"],
   "namespace": "io.github.Azhrei",
   "shortDescription": "test"
 }

and that is it. You have made an Add-on! Those 6 lines are enough; just zip this file and then rename it so that it ends with .mtlib and have fun.

2. Export a Library Token as an Add-on Library

Library token context menu

The token pop-up menu includes a way to export your existing library tokens to an Add-on Library structure. This is useful for starting the conversion of an existing token library to an Add-on.

In all but the simplest Library Tokens you will want edit the extracted data. At a minimum, you will want to examine whether you prefer to rename the macros.

Things you will want to change

You should probably change the namespace in the library.json file to something that is unlikely to conflict with other users. It's a good practice to use a reversed hostname + Add-on name for this. For example, if you created an account at GitHub and are using the GitHub.io page mentioned above, an example namespace would be io.github.add-on-name.

All macros (except event-based ones) are created in mtscript/public/ with the pattern macro_number.mts. This naming pattern is because macro names have many things that might make them invalid -- or worse, dangerous -- as filenames. There is a macro_script_map.txt file saved in the top-level which contains the names of your macros and the filename that they were saved in.

Not all macro buttons on Library Tokens contain MTscript macros. They are sometimes used as containers for CSS or other text content. You will probably want to rename and move them to the library/public/ directory. Don't forget that renaming them means any references in your macros may need updating as well.

The onCampaignLoad macro will be saved as onInit.

All properties are saved in the library/properties/ directory. These are saved with the names prop_number.txt and a mapping file prop_file_map.txt is created to map these. (This may change slightly as the data access API evolves.)

These files and structures are described in more detail in Technical definition of Add-on Libraries.

After doing the above you should REALLY take the opportunity to source control your Add-on...