Creation of Add-on libraries: Difference between revisions

Latest revision as of 23:59, 17 November 2023

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:

Create the library files and directory structure from scratch; or
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.

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

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 edit the library.json file, and change the namespace value from the default ("") 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 Library Token properties are saved to a directory called property/. You should move the contents of this directory to something accessible by MTscript functions related to Add-on libraries such as library/public/properties/. The Library Token properties are saved with file names prop_number.txt, and a mapping file prop_file_map.txt is created to map these the Library Token property names to the newly-created filenames.

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...

@@ Line 54: / Line 54: @@
 === Things you will want to change ===
-You should probably change the namespace in the {{code|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 {{code|io.github.''add-on-name''}}.
+# You should edit the {{code|library.json}} file, and change the namespace value from the default ("") 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 {{code|io.github.''add-on-name''}}.
+# All macros (except event-based ones) are created in {{code|mtscript/public/}} with the pattern {{code|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 {{code|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.
-All macros (except event-based ones) are created in {{code|mtscript/public/}} with the pattern {{code|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 {{code|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 Token]]s 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 {{code|library/public/}} directory.  Don't forget that renaming them means any references in your macros may need updating as well.
+# The {{code|onCampaignLoad}} macro will be saved as {{code|onInit}}.
-Not all macro buttons on [[Library Token]]s 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 {{code|library/public/}} directory.  Don't forget that renaming them means any references in your macros may need updating as well.
+# All Library Token properties are saved to a directory called {{code|property/}}. You should move the contents of this directory to something accessible by [[MTscript functions related to Add-on libraries]] such as {{code|library/public/properties/}}. The Library Token properties are saved with file names {{code|prop_''number''.txt}},  and a mapping file {{code|prop_file_map.txt}} is created to map these the Library Token property names to the newly-created filenames.
-The {{code|onCampaignLoad}} macro will be saved as {{code|onInit}}.
-All properties are saved in the {{code|library/properties/}} directory. These are saved with the names {{code|prop_''number''.txt}} and a mapping file {{code|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]].
 {{Note|After doing the above you should ''REALLY'' take the opportunity to source control your Add-on...}}