Mappings

Mappings are a feature of Zaparoo Core to assign custom ZapScript to a token based on some criteria to detect when that token has been scanned. This is useful for making tokens work with Zaparoo that don't have any rewritable storage, such as barcodes and NFC toys like Amiibos.

There are two main methods of managing mappings in an instance of Core. Other applications may use these methods to add management GUIs or automate creation of mappings.

If there is a conflict between these two methods, the mappings database will take precedence, as it's checked first when a scan happens.

Mapping config files

	This documentation refers to a feature of Zaparoo Core which is not yet released.

In a subfolder called mappings in the data folder of Core, it's possible to add any number of TOML files (like the config file) which will define new mappings to be enabled on service start. Check the page for your platform to see where this folder will be.

If you're planning to add a lot of mappings, it's better to use the mappings database instead, as this will have better performance and use less memory.

An example of a mapping config file called 1-test.toml in the mappings folder:

[[mappings.entry]]
token_key = 'id'
match_pattern = '044ed8daed7281'
zapscript = '**launch.random:snes'

This mapping would wait for a token with the ID "044ed8daed7281" (an NFC tag with this UID) to be scanned and then run the ZapScript "**launch.random:snes" instead of whatever value may have been written to the token originally.

The name of the file doesn't matter except that it must end with the .toml file extension. Files in the mappings folder are read in alphanumeric order and stored this way in memory, so it's optional but may be useful to name them with this in mind. A single file may contain any number of entries as long as each mapping has its own [[mappings.entry]] header.

The token_key option specifies which key of a token object this mapping will attempt to match against. It accepts 3 possible values: id, value, data. This option is optional and will default to id if empty.

The match_pattern option specifies the pattern used to match against the contents of the key specified. Its behavior is different depending on the format given:

By default, the pattern will be treated as an exact match, and must be exactly the same as the given key contents of the token, in full. When matching against the ID, the contents and pattern are both normalized to remove spaces, colons and is converted to lowercase. This is to make it easier to match against NFC tag UIDs and barcodes, which may not have a standard display format.
If the pattern contains one or more asterisks (*), it will use globbing to match.
If the pattern is surrounded by forward slashes (/), it will be treated as a regular expression.

Mappings database

See Core API for details.