MapTool 1.11 introduced [[Add-On Library|add-on libraries]] which are intended to be an easier to work with replacement for [[Library Token]]s while also offering a lot more functionality.
[[Library Token]]s will still function the way that they currently do in MapTool 1.11 and future versions, but will not be getting a lot of the new features that add-on libraries will get, so it is recommended that framework developers transition to add-on libraries if supporting MapTool 1.11 and above.
An example add-on library for examination and testing is available at https://github.com/cwisniew/test-maptool-add-on-lib
An example add-on library for examination and testing is available at https://github.com/cwisniew/test-maptool-add-on-lib
== Managing the Add-On Libraries for Your Campaign ==
The dialog to manage the add-on libraries for your campaign can be reached using the {{ui location|File > Add On Libraries...}} menu option.
This dialog can be used to add or remove add-on libraries, view the details of all add-ons in the campaign and view their license/read me files.
== Drag and Drop ==
As of MapTool 1.12, add-on libraries can be dragged and dropped onto the map from your system's file explorer. This will either add the add-on library to the campaign or replace it if it is already in the campaign.
<p style="clear: both"/>
<p style="clear: both"/>
== Format of add-on library files ==
<p style="clear: both" />There are two main ways to create an Add-on Library:
Add-on libraries can be shared in a {{code|.mtlib}} file. This file is a zip file with a specific structure and content. You can import these libraries with the {{ui location|File > Add On Libraries...}} menu option.
| {{code|library.json}} || Configuration information for the add-on library ||
|-
| {{code|mts_properties.json}} || Properties for macro script functions in the add-on library ||
|-
| {{code|events.json}} || Events definition for events supported by the add-on library ||
|-
| {{code|library/}} || Contents of the add-on library ||
|-
| {{code|library/public/}} || Contents of the library that are accessible via {{code|lib://}} URI ||
|-
| {{code|library/mtscript/}} || Directory containing the macro Script files for the add-on library. ||
|-
| {{code|library/mtscript/public/}} || Directory containing the macro Script files that can be called via {{code|[macro(): ]}} outside of the add-on library. ||
| {{code|name}} || The name of the add-on. || Yes || -
|-
| {{code|website}} || The website for your add-on. || No || -
|-
| {{code|gitUrl}} || The url for the git source repository. || No || -
|-
| {{code|authors}} || An array of the authors of the add-on. || Yes || -
|-
| {{code|license}} || The name or short description of the license. || No || -
|-
| {{code|namespace}} || The namespace of the add-on. || Yes || -
|-
| {{code|description}} || The description of the add-on. || No || -
|-
| {{code|shortDescription}} || The short description of the add-on. || Yes || -
|-
| {{code|allowsUriAccess}} || Should add-on allow URI access to contents. || No || -
|-
| {{code|readMeFile}} || The path to the readme file for the add-on.
Can be plain text or GitHub-Flavored Markdown. || No || -
|-
| {{code|licenseFile}} || The path to the license file for the add-on. || No || -
|-
| {{code|requires}} || An array of the add-ons that are prerequisites (namespaces). || No || Added in 1.13
|-
| {{code|exports}} || An array of directories and files that are exported to other add-ons. || No || Added in 1.13
|}
The {{code|readMeFile}} and {{code|licenseFile}} can be plain text, HTML, or GitHub-Flavored Markdown (GFM).
These can be viewed from the Add-on Library dialog.
{{Note|GitHub provides a way to host your own static site at '''''username''.github.io'''. If you do not have your own host, this can be used for both your add-on website and reversed for a unique namespace. (There is no requirement for there to be an actual website running at the address used for the namespace.)}}
== Events File Format: {{code|events.json}} ==
This configuration file controls which files are executed for which events.
Add-ons do not respond to the {{code|onCampaignLoad}} event. Instead they have 2 new events:
* {{code|onFirstInit}} - This is called only once, when the add-on is first added to the campaign. Add the same add-on a second time (overwriting the existing one) and it will not be called again unless the add-on is removed first.
* {{code|onInit}} - This is called every time the campaign is loaded (including after the initial onFirstInit event), similar to how {{code|onCampaignLoad}} is called on [[Library Token]]s. It's also called on the client when the campaign is sent to the client on the initial connection.
As of 1.13, the {{code|onFirstInit}} and {{code|onInit}} events can specify a JavaScript file to run. Unlike the MTS script, you must specify the full path to the file. If you have an entry for both MTS and JavaScript, the JavaScript script will be run first.
# Create the library files and directory structure from scratch; or
# Export a Library Token as an Add-on Library.
The other events must be in the {{code|legacyEvents}} section. As the name implies, these events are now considered to be legacy events. New events will be added in the future to replace these (these will not be removed).
Each of these approaches is described below.<p style="clear: both" />
== 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 just use [https://code.visualstudio.com/ VS Code].
*[https://www.gnu.org/software/emacs/ Emacs]
*[https://neovim.io/ Neovim]
*[https://www.vim.org/ Vim]
*[https://code.visualstudio.com/ VS Code]
after choosing a text editor, create a new directory to hold your Add-on.
Currently, only macro scripts are supported for {{code|legacyEvents}}; in the future, JavaScript scripts will also be supported.
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''.
== MTScript macros ==
You may have other non metadata files in a subdirectory which must be named ''library''.
The {{code|library/public}} directory is only exposed via the {{code|lib://}} URI if {{code|allowsUriAccess}} is set (see the configuration file discussion, above).
For macro code you may have a mtscript directory inside library, both of those subdirectories may have a public directory which must be named public.
MTScript macros must all end with the file extension {{code|.mts}} to be recognized.
This structure is described in more detail in: [[Technical definition of Add-on Libraries|Technical definition of Add-on Libraries.]]
Only MTScript files in {{code|library/mtscript/public}} can be called using {{roll|macro}} from outside of the add-on.
===Creating library.json===
The path of the file becomes the macro name for the {{roll|macro}} call.
the only required fields are*a name string
The namespace of the add-on library is used for the {{code|@}} portion (the "location" of the macro).
*a authors array
*a short description string
*a namespace string
the other fields are described in [[Creation of add-on libraries #Configuration File Format: library.json | Creation of add-on libraries]] 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 host name.
Add-on libraries support both public and private macro functions. Public macro functions must reside in the {{code|library/mtscript/public}} and can be called from anywhere (chat, other add-ons, [[Library Token]]s, and macro buttons). You can call them using the following syntax:
an example of a minimal library.json could be
{
"name": "test",
"authors": ["you"],
"namespace": "test.test.test",
"shortDescription":"test"
}
and that is it. you made an add-on those 6 lines are enough, just zip this file and then it rename so that it ends with .mtlib and have fun.
<source language="mtscript">
== 2. Export a [[Library Token]] as an Add-on Library ==
The above executes the MTScript macro in the file {{code|library/mtscript/public/GetTargets.mts}}.
{{Note|The {{code|public/}} is omitted from the macro name when calling it. You can also use subdirectories to organize your macros and would call them like {{code|[macro("somedir/macroname@lib:net.rptools.maptool.test-library")]}}.}}
The {{code|@this}} shorthand can also be used for calling a macro from within the same add-on, similar to how it works for [[Library Token]]s. For example, {{code|[macro("mtscript2@this")]}}.
Macro script files that are not in the {{code|public/}} directory can only be called from within the add-on itself or by events. Given a library with the namespace {{code|net.mylib.addon}} with the following files:
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.
<source>
In all but the simplest [[Library Token]]s you will want edit the extracted data. At a minimum, you will want to examine whether you prefer to rename the macros.
mtsscript/func1.mts
mtsscript/public/func2.mts
</source>
Then:
<source language="mtscript">
[macro("func2@lib:net.mylib.addon")]
</source>
can be called from anywhere, but
<source language="mtscript">
[macro("func1@lib:net.mylib.addon")]
</source>
can only be called from a macro (or via an triggered event) that is on the {{code|net.mylib.addon}} add-on.
{{Note|Since the {{code|public/}} is not required, if you have two files with the same name excluding the {{code|public/}} directory component, then only the one in {{code|public/}} will be able to be executed. You will not be able to call the other macro.}}
The above works not just with {{roll|macro}} but the other places you would expect it to as well, such as {{func|defineFunction}} for user-defined functions and macro links.
The {{code|mts_properties.json}} file contains property information about macro scripts.
It is not required and currrently only allows you to set properties used in macro links.
<source language="javascript">
{
"properties": [
{
"filename": "public/auto_exec.mts",
"autoExecute": true,
"description": "Auto executable macro link"
},
{
"filename": "public/myUDF.mts",
"description": "My Test UDF in a drop in lib."
}
]
}
</source>
Where:
* {{code|filename}} - is the path of the file for the MacroScript function (excluding the {{code|mtscript/}} prefix).
* {{code|autoExecute}} - determines if a macro link created for this macro will be auto executable or not.
* {{code|description}} - is the description that will appear in the UDF listing; unlike [[Library Token]]s, this is just a plain string and not evaluated if it contains {{code|[]}}.
== {{code|public/}} Directory ==
The contents of this directory are exposed as a {{code|lib://}} URI as long as the {{code|allowsUriAccess}} is set to true in the configuration file. The public directory part of the filename is discared, for example {{code|public/myhtml.html}} -> {{code|lib://net.myaddons.addon1/myhtml.html}}.
You can add images to this directory and use {{code|<nowiki>src="lib://"</nowiki>}} in image tags in HTML. It will eventually work with audio (probably already does but I haven't tested it yet so I'm not claiming it will 🙂).
These assets will be included correctly in the campaign file when saving, so you do not need to add them to image tables or image tokens or any other tricks to make sure that they are included.
There are some differences to be aware of when using [[Library Token]] property support for add-ons.
The name is case sensitive, unless tokens where it is not case sensitive.
The values stored do not need to be be converted to/from strings like they do with [[Library Token]]s. In many cases related to large json values, this should result in a speed improvement.
The default properties list for the campain are not present for add-ons as they are not tokens, unlike [[Library Token]]s.
== Converting [[Library Token]]s ==
The token popup menu includes a way to export your existing library tokens to an add-on. This is useful for starting the conversion of an existing token library to an add-on. However, in all but the simplest [[Library Token]]s you will want edit the extracted data. At a minimum, you will want to examine whether you prefer to rename the macros.
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.)
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/structures are described in more detail in: [[Technical definition of Add-on Libraries|Technical definition of Add-on Libraries.]]
{{Note|After doing the above you should REALLY take the opportunity to source control your add-on...}}
{{Note|After doing the above you should REALLY take the opportunity to source control your add-on...}}
=== Things still to be addressed. ===
* There is only minimal checking of data when importing add-ons so error reporting is not great.
* Expanding the JavaScript API which will make this much more useful (part of another change set).
* Better replacement for user defined functions.
* Providing an equivalent to [[Library Token]]s buttons.
* Ability to check URL for later version and update from that (most likely GitHub to start with)
* Link maps to required add-ons when exporting/importing.
* Documentation / procedures for creating a GitHub release for your add-on.
* The data store could be slightly smarter about large text blocks that remain static and attempt to cache them.
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 which must be named library.
For macro code you may have a mtscript directory inside library, both of those subdirectories may have a public directory which must be named public.
the other fields are described in Creation of add-on libraries most of these are self explanatory just remember badthings will happen if you use the same namespace as someone else so try to use at least 3 words or a reversed host name.
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.addon-name.
All macros (except event-based ones) are created in mtscript/public with the pattern macro_number.mts. This is because macro names have many things that might make them invalid -- or worse, dangerous -- 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 used as containers for CSS or other text content. You will probably want to rename and move them to the library/public/ directory.
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.)
