Guide to onTokenMove

... and all related stuff

Recently a great new feature has been added to MapTool. This guide shall aide you to use it. Every time a token is moved (by the user) a specific macro is called. This macro can even cancel that move.

Events

Just like onCampaignLoad the new events are macros on a lib:token that have to be named like the event. Note that (and this is different to oonCampaignLoad) these events should be only defined once - doing otherwise can lead to unexpected behaviour.

onTokenMove

The event macro onTokenMove is called whenever any token is moved via the user interface. That tokens path is available as content of macro.args. The moved token is the token in context, so you can get its id with currentToken().

onMultipleTokenMoves

The event macro onMultipleTokenMoves is only called when more than one tokens are moved at once. The macro.args contain a json array with all moved tokens ids. The is no token context.

Note that, before onMultipleTokenMoves is actually called, onTokenMove is called for each single token.

If you use both events at the same time it is recommended that you use the tokens.moveCount variable in onTokenMove and abort if its >1 and let onMultipleTokensMove handle it.

If you dont know what event to use you probably want to use onTokenMove.

Special Variables

tokens.denyMove has to be set to 1 to cancel the current movement.

tokens.moveCount contains the number of tokens moved.

Paths

In context of these events there will sometimes be specified or returned a path or a list of coordinates. These are in this specific format:

it is a json array containing json objects for each points. Each json object defines the keys x and y with the map coordinates.

[h: samplePath = json.append("",
    json.set("", "x", 50, "y", 50), 
    json.set("", "x",  0, "y",  0)
)]


<!-- samplePath contains 
[{"x":50,"y":50},{"x":0,"y":0}]
 -->

Related Functions

There is a number of functions that are very useful in combination with the onMove-events.

getLastPath()

getLastPath() returns the last path. Note that this returns exactly the same as is contained in macro.args in onTokenMove.

movedOverPoints(arrayOfCoordinates)

movedOverPoints() returns an array of coordinates with all "hit" cells considering the specified array of coordinates.

movedOverToken(tokenName, [lastPath])

movedOverToken() returns an array of coordinates with all "hit" cells where the moved token crosses the specified token.

Note that before b77 the token must be specified by name - not id.

getMoveCount()

getMoveCount() returns the calculated move cost according to the selected move metric.

Examples

Lets now give you some simple examples for most commons use cases.

Traps/Teleporting

TO DO

Movement cost tracking

<!-- this should be in onTokenMove -->
<!-- moved token is in context -->

<!-- get movement -->
[h: mov = getProperty("Movement")]
[h: usedMov = getMoveCount()]

<!-- deny move if not allowed, reduce mov prop otherwise -->
[r, if( mov >= usedMov ), code: {
    [h: mov = mov - usedMov]
    [h: setProperty("Movement", mov)]
};{
    [h: tokens.denyMove = 1]
    <span style="color:red;font-weight:bold;">Move limit exceeded.</span>    
}]

Exposure of Fog on gridless maps

Fog does not get cleared on gridless maps. But we can do this by using a simple onTokenMove-event.

<!-- this should be in onTokenMove -->
<!-- clear fog only if pc token moved -->
[h, if( isPC() ): exposeFOW()]