Latest revision as of 10:01, 18 February 2022

Page Updated:   2022-02-18

[edit] Overview

The API is known to have some issues, and a version 3.0 is under works.

Page navigator simplifies moving your players from map to map and allows them to interact with destinations on the map directly by moving their token to the destination. Player movement between maps regardless of the trigger is controlled by the GM unless the GM has defined a page or pages as player accessible, or has turned off the player movement restriction. See below for a complete guide on using the script.

[edit] Using the Script

[edit] Commands

​The api command to trigger the script is !nav. The commands that can be passed with !nav are:

• help — Shows the Help screen
• pages — Brings up a dialog of all non-archived pages in the Campaign for specifying a page to send players to. The exact behavior is dependent on the next argument, which can be:
  • whole — To move all players to the selected page.
  • current — To move only those players currently in the player ribbon to the selected page.
  • player — To move a specific player(s) to the selected page. This must be followed by at least one token or character id and will move the owners of that token/character to the selected page or will only move the messaging player if the gm has set player control to only themselves.
  • return — If sent by the gm; returns all designated players (via token/character id) to the player ribbon. If sent by a player, returns that player to the player ribbon.
• config — If sent by the gm; brings up the configuration options. Has no effect if sent by a player.

[edit] Defining Destinations

In order for Page Navigator's token collision functionality to work, you must properly set up the destination tokens. The script looks for the following token properties when determining if a token is a destination or not:

• Layer — The token must be on the GM layer.
• Marked as destination — The token must be marked as a destination correctly. The script looks for the flying-flag status marker by default, but it can be set to look for any status marker or to look for tokens based on name only.
• Token Name — The name must exactly match the name of whatever page you want it to link to. This includes the player accessible tag you have designated in the configuration options for player pages.

[edit] Buttons

There are several API button dialogs that may be generated while using this script. These are descriptions of what each button will do.

• Dialog for a token colliding with a destination-token:
  • Whole Party — Will move all players in the game to the player ribbon, and will move the player ribbon to the page described in the dialog.
  • Current Party — Will move the player ribbon to the designated page, but will not affect any players split from the party.
  • Controlling Player(s) — Will move any players set to control the token or its associated character (if it represents a character) to the designated page.
• Dialog for the pages command: The dialogs that are produced by using !nav pages produce a button for each page that the sender of the message has access to. These buttons will send players to the indicated map based on how pages was called (e.g. whole party, current party, or specified players).

[edit] Access

Page Navigator functions differently based on the access allowed by the triggering player.

• Setting Access — Pages are GM access only by default. To set a page to Player access, simply add the tag that you have selected to the end of the page name. By default the tag is set to .players. Any text after the tag will not be shown in any button labels or dialogs.
  • Example: Test Page - GM only page

vs. Test Page.players - player visible page

• GM Access — If the !nav pages ... command is sent from a GM, all pages are populated as API buttons. The GM receives a whispered movement prompt for all token collision prompted navigation requests.
• Player Access — If the !nav pages ... command is sent from a player, only those pages flagged as player pages are populated as API buttons. Players only receive a whispered movement prompt when their token collides with a player accessible destination.

[edit] Config

Page Navigator has several options that you can adjust according to your preferences.

• Players can move — This button cycles between allowing players to move everyone in the game (default), only those currently in the player ribbon, or only themselves.
• Players can access all pages — Sets the access state to restricted (default) or open. This defines whether a player can directly access only player pages or all pages respectively.
• Player page tag — Triggers a roll query prompt to specify what tag you would like to use to mark pages as player accessible
• Destination tokens marked by — A list of all status markers that can be applied to tokens along with an option for name only. The currently selected one is highlighted in green.
• Update Destinations & Pages — Triggers the scripts update behavior to update the stored pages and destination-tokens. Use after you have added a page and/or a token linked to a page.

[edit] Changelog

v2.11 (2018-02-08)

• link bugfixes

Version 1.3

• Large Update with a lot of changes. Read the changelog and the updated instructions above before upgrading to this version if you are currently using a previous version.
• msg.selected support enabled - The script will now respond to what you have selected when you trigger any of the !nav pages commands, assuming you don't enter anything in the 4th argument. (e.g. !nav pages [pages command] [4th argument])
• The script now stores the destination tokens and pages in the state rather than finding them with each trigger. Please use the update button in the config dialog to update the stored destinations and pages before using the first time.
• The tag for defining pages as player accessible is now customizable. It's default is no longer "players"; it is now .players. This change was due to programming necessities for making it customizable.
• Any command except for !nav help and !nav pages ... requires gm access. Gm's should not use any of these commands except for !nav config as they are meant to handle the pressing of an API button and have very specific requirements for arguments. WARNING!: If you use these hidden commands, you risk breaking the stored variables and the script.
• Erroneous chat commands being sent when there were no valid pages or players has been stopped. An error message is now generated instead.
• There are now error messages if the conditions required by each command are not met.
• Handling for non-controlled characters/tokens has been added
• The Help screen now appears if the next argument after !nav was invalid, or if only !nav is entered. - will add handling for further down incorrect arguments in the next beta/release iteration.
• The Help screen has now been updated to reflect the new capabilities of the beta version.
• New Commands
  • !nav pages return - If sent by the GM, returns the controlling players of all selected tokens to the player ribbon. If sent by a player, returns that player to the player ribbon if the ribbon is on a player accessible page; sends a request to return to the GM if it is not.
  • !nav config - The script now has several settings that you can modify to customize the navigation behavior:
    • Player Control - Adjust whether players can move the whole party, the current party, or themselves only via the !nav pagescommands (the exception is !nav pages return which only allows players to move themselves regardless).
      • Possible Values: Whole Party (Default), Current Party, Themselves only.
    • Access all pages - Toggles whether or not players have access to all campaign pages or not.
      • Possible Values: off (Default), on
    • You can now set how you want your campaign's destination tokens identified.
      • Possible Values: any status marker (Default: flying-flag) or name only
    • Update - Updates the stored destination tokens and pages.

Version 0.1.031

• Minor update. The help dialog has been adjusted so that it does not present one block of text. Instead specific help topics are available via API button.
• The handling of page names has been changed so that the "players" tag no longer shows up in buttons and dialogs. Because of this change, the tag must now be at the end of the page name. Any text after the "players" will not show up in buttons or dialogs.

Version 0.1.03

• Had also not updated the help screen with what buttons are created. Help screen has been updated as shown to the left.

Version 0.1.02

• Had forgotten to update the help, or this post with changes to the command syntax for the script.
• There is a new syntax for using !nav pages all. It now uses !nav pages whole instead. Thanks for pointing this out Ziechael.

Version 0.1.01

• Fixed the issue with splitting the party. The party can now be split as much as you would like in any way you would like.
• The script now has logic for determining what pages the GM would like players to have access to and which they shouldn't have via looking for "players" (including "") in the page name.
• The script will whisper formatted API buttons based on whether pages are flagged with "players" or not.

Version 0.1.0

• All players who control a triggering token will now be separated from the party if the "specific players" button is pressed.
• There is now a command to manually move players to any nonarchived page.
• Players are now notified via chat when players are being moved to new pages.

Version 0.0.5

• Noticed that I had programmed the script so that it would trigger if there was any collision with a destination token during the move. The script will now only trigger if the moved token finishes its move sharing space with the destination token.

Version 0.0.4

• Release

[edit] See Also

• API:Script Index (partial) list of other APIs