lib:Elevation Manual

File:lib elevation.png

Lib:Elevation tries to fit into the MapTool UI to add accessible elevation tools for map-making.

Welcome to Lib:Elevation!

• Download Lib:Elevation from GitHub
• View the RPTools Forum Post
• Ask questions and discuss in the MapTool Discord in the #map-drawing-tools channel

This library adds an elevation feature to MapTool, allowing you to set Visual and Movement blocking layers based on elevation and set maps, doors, and other tokens for an elevation. Additionally, player or NPC tokens with an Elevation property can automattically view the elevation they are at when it is their initiative turn.

Campaign Setup

Note that the library is designed to (mostly) work without any of the items below defined, but they should be added for you to benefit from the features of the library.

• Drag the colored elevation macros to your Campaign/GM panels for quick access. The overlay UI may have some of these options, but it is nice to have the buttons handy.
• To show token elevation on mouse-over stat sheets, add a campaign property for 'Elevation'. This is a default MapTool property. If you'd like to use a different property name for elevation in your campaign, you can change it in the getElevationPropName function.
• To show token elevation on mouse-over stat sheets, add a campaign property for 'Elevation'. This is a default MapTool property. If you'd like to use a different property name for elevation in your campaign, you can change it in the getElevationPropName function.
• To show special states for token-layer tokens at different elevations, add two states: isAbove to mark tokens on a higher defined map elevation level, and isBelow for tokens below the current map elevation level. I use partly transparent, 'Yield' (down arrow) and 'Triangle' images in the 2x2 grid. Tokens will also appear faded when not on the current elevation.
• To highlight/mark elevation tokens for GMs (doors, background maps, etc. set to a particular elevation), add an 'isElevationToken' state to your game and check the 'GM' and 'Mouseover' options. I use the 'Shaded' type state set to teal and 25% opacity. You can also change the property name in getLinkedStateName.

Usage

By default, new maps have no elevations explicitly defined and won't show the elevation list overlay for the GM. Once two or more elevations are present, a selection list will appear so the GM can easily switch elevations. Changing elevations changes them for all connected players, unlike layers which the GM can freely choose between without impacting how players see the map.

Each elevation saves a set of blocking layers (VBL and MBL) for the map, and can have tokens linked to it (elevation tokens) which will be hidden when a different elevation is chosen (unless that elevation also uses that elevation token). Changing between elevation layers swaps out which blocking layers are active and which elevation tokens are visible.

On a new map without any elevations defined, the implicit default elevation is zero - but adding a different elevation will set that as the only elevation.

Elevation Management Buttons

There are some additional buttons, and you can check the tooltips of any button for more information. Here is a rundown:

• Add Elev will add a new defined elevation. You can either start with the same MBL/VBL that the current elevation has, or start with a fresh slate. Similarly, you can copy the elevation tokens from the current elevation, hide those tokens (like you would when switching), or leave them unlinked to the new elevation but still visible - useful if you want to link only some of them, like the map stamp.
• ↑↑↑, ↓↓↓, and ↑↓ switches the map elevation up, down, or to a map elevation you choose.
• T↑↓ button switches the map elevation to the selected token.
• Link Tokens links the selected token to an elevation you select. You can use Unlink Tokns to undo this, or Select Tokens to select all the current map elevation's linked tokens.

Token Management Buttons

These buttons simply let you change the elevation of the selected token(s). Hovering over them provides a quick view of the change they will effect.

Please note that using these buttons usually also switches to the new elevation.

About Elevation

In Lib:Elevation, map elevations are special objects set at an elevation number defining walls and other visual/movement barriers at that elevation and higher (until the next defined map elevation). For instance, you may want three elevations 10 feet apart - Low ground (0), High ground (10), and Flying (20+). Each elevation should be considered to 'fill' the vertical space until the next elevation.

Here are some ideas on how to use this feature:

• Set up outdoor maps where climbing to a higher elevation removes vision barriers from lower elevations.
• Remove vision entirely to simulate flying or scrying.
• Change the background map at different elevations for a truly 'vertical' feeling, such as flying islands or tall, fog-filled canyons.

Limitations

There are of course limitations given the current state of MapTool and the limits of my development time.

• Hard fog of war is exposed for all elevations. This limits usefulness for indoor areas, as the fog for one level may greatly impact vision of another area.
• While tokens can have their own elevation, the map can only display one elevation at a time. That means that all your players stuck in a maze will see what the Flying character is seeing on their turn.

For any questions, please go to the MapTool discord and ping Melek in #map-drawing-tools.

Developer notes

Here are outlines the data structures and basic mechanism behind the library.

Library Properties

Property	Type	Purpose
libData.elevation.elevations	JSON Object	Map IDs are keys for the current elevation. The current elevation is set when saving a map or loading a map, which happens whenever the map is switched with a UI macro. Essentially, this is almost always the 'display' elevation, unless you have manually used macros to load different elevation layers or hide/load elevation tokens from different elevations.
libData.elevation.maps	JSON Object	Map IDs are keys for JSON objects containing elevation data. This data structure is described below.

Data Structures

Note that Lib:Elevation uses Map and Token IDs stored on the library; this means that the library is pretty tightly coupled with a campaign. Any change to the IDs expected by the data structure will lead to undefined behavior. Importing/Exporting maps with elevation data is not currently supported.

libData.elevation.maps

This JSON object uses Map IDs as keys to a JSON object containing elevation data, called 'Map Elevation Objects'. Each Map Elevation Object contains numeric keys designating the elevation it describes. Each elevation in turn contains an object with the following optional keys - no keys are mandatory, though omitting some keys will define default behavior:

Key	Type	Purpose
label	String	A display name for the elevation. Defined elevations don't require names.
vbl	JSON Array	VBL is a shape object array as returned by getVBL().
mbl	JSON Array	MBL is a shape object array as returned by getMBL().
tokens	JSON Object	Token ID keys containing token appearance objects. Token appearance is described below.

Token appearance objects

Token appearance are the exact parameters of how a token appears on the map. These keys are used in getTokenAppearance() and setTokenAppearance(). The token appearance JSON Object includes the following keys and the associated token data:

Key	Data function
ID	Same as Field ID
Layer	getLayer(ID)
X	getTokenX(1, ID)
Y	getTokenY(1, ID)
Z	getTokenDrawOrder(ID)
Height	getTokenHeight(ID)
Width	getTokenWidth(ID)
Size	getSize(ID)
Facing	getTokenFacing(ID)
Opacity	getTokenOpacity(ID)
Visible	getVisible(ID)
Shape	getTokenShape(ID)
Layout	getTokenLayoutProps(';', ID)

Token Fade Data Lists

Tokens on other elevations are faded with the elevation.setTokenElevationStates function have their opacity reduced and are assigned either the isAbove or isBelow state. Additionally, according to the fadedTokenSight option (see below for options documentation), sight can be disabled or changed to a different type for faded tokens.

When tokens are faded, their normal settings for opacity, sight type, and the has sight checkbox are saved in a string list in the following format: opacity, sight_type, has_sight

This is stored by default on the token in the libRefData.elevation.fadeData property. This property can be changed in the elevation.getTokenFadePropName method.

Options

There is a simple options API using elevation.getOption and elevation.setOption. This is a simple JSON object with keys (option names) and the option value, where a missing key is treated as '0'. Here are the available options:

• fadedSightType Determines how faded tokens have their sight settings changed when faded.
  • 0 - Do not change sight settings when faded.
  • 1 - Uncheck 'Has Sight' when faded. Prior settings are restored when unfaded.
  • sight_type - Assigns the sight type. Does not alter the 'Has Sight' checkbox. Prior settings are retored when token is unfaded.
• useFogHack restores fog of war each time an elevation is loaded/reloaded.
  • 0 - Disable fog hack.
  • 1 - Enable fog hack.

Sample libData.elevation.maps object

A trivial example object may look like this:

{
 "A14EF2FE619B42AF828CBBAC0192131A": {
    "0": {
        "label": "Ground level",
        "vbl": "JSON Shapes Array",
        "mbl": "JSON Shapes Array",
        "tokens": {
            "BC752679AF784C7DB19EA9ACCF05A362": "JSON Token Appearance Object",
            "19EA9ACCF05A362BC752679AF784C7DB": "JSON Token Appearance Object"
        }
    },
    "60": {
        "label": "Cliff top",
        "vbl": "JSON Shapes Array",
        "mbl": "JSON Shapes Array",
        "tokens": {
            "BC752679AF784C7DB19EA9ACCF05A362": "JSON Token Appearance Object",
            "19EA9ACCF05A362BC752679AF784C7DB": "JSON Token Appearance Object"
         }
     }
 },
 "28CBBAC0192131AA14EF2FE619B42AF8": {
    "0": {
        "label": "Sea Level",
        "vbl": "JSON Shapes Array",
        "mbl": "JSON Shapes Array"
    },
    "10": {
        "label": "Flying",
        "vbl": "JSON Shapes Array",
         "mbl": "JSON Shapes Array"
    }
 }
}