[Script] Pintool - a Utility Script for Managing Map Pin Properties, Converting from Note Token-style Pins, and more

Pintool [ Demonstration Video ] The full documentation is shown below for completeness, but you don't need to read it all to ba bel to use the basic features of the script. Watch the video for a quick and intuitive introduction. NOTE: This is a brand new script for a feature that is in public beta. It has destructive potential if not used carefully. Work with a  copy  of your page until you are comfortable with it. PinTool provides bulk creation, inspection, and modification of  map pins  It also provides commands for conversion of old-style note tokens to new  map pins . Modify pin properties in bulk Target selected pins, all pins on a page, or explicit pin IDs Convert map tokens into structured handouts Place Map Pins onto map automatically from specified handout and header level Display images directly into chat Base Command:  !pintool Primary Commands --set  — Modify properties on one or more pins (selected pins, or all pins on a page). --convert  — Convert map tokens into a handout. Can optionall replace existing token pins upon creation --place  — Places pins on map based on specified handout and header level. --purge  — Removes all tokens on the map similar to the selected token, or pins similar to the selected pin. --help  — Open this help handout. Set Command Format: !pintool --set property|value [property|value ...] [filter|target] All supplied properties apply to every pin matched by the filter. Filter Options filter|selected  — (default) Selected pins filter|all  — All pins on the current page filter|ID ID ID  — Space-separated list of pin IDs Settable Properties Values are case-sensitive unless otherwise noted. Values indicated by "" just mean no value. Do not actually type quotes. See examples at end of Help document. Position x — Horizontal position on page, in pixels,  number y —  Vertical position on page, in pixels,  number Text & Content title — The title text displayed on the pin,  string notes — Notes content associated with the pin,  string tooltipImage  — Roll20 image identifier for the tooltip image displayed on the pin,  URL Links link  —  The ID of a handout or other object this pin links to.,  string (id) linkType  — The type of object linked,  "handout" or "" subLink|  — A sub-link identifier, typically a header in the handout, used for linking to specific sections , string subLinkType|  — The type of sub-link (which section of handout: notes or gmnotes)  — ""headerPlayer", "headerGM, "" Visibility visibleTo  — Controls overall visibility  — "all" or "" (empty string) tooltipVisibleTo — Controls who can see the tooltip  — "all" or "" (empty string) nameplateVisibleTo — Controls who can see the nameplate  — "all" or "" (empty string) imageVisibleTo  — Controls who can see the image  — "all" or "" (empty string) notesVisibleTo|  — Controls who can see the notes  — "all" or "" (empty string) gmNotesVisibleTo  — Controls who can see GM notes  — "all" or "" (empty string) Notes Behavior autoNotesType — Controls whether blockquote style in handout determines player visibility  — "blockquote" or "" (empty string) Appearance scale  —  Range: 0.25 – 2.0 State imageDesynced|false   —  Whether the pin's image is desynced from its linked object. Setting any desynced property sets all three to the same value.  — true, false notesDesynced|false   — Whether the pin's notes are desynced from its linked object. Setting any desynced property sets all three to the same value.  — true, false gmNotesDesynced|false  — Whether the pin's GM notes are desynced from its linked object. Setting any desynced property sets all three to the same value.  — true, false Convert Command The convert command builds or updates a handout by extracting data from map tokens. Format: !pintool --convert key|value key|value ... A single token must be selected. All tokens on the same page that represent the same character are processed. This script requires that all note pins must represent a common character. Required Arguments name|h1–h5 Header level used for each token’s name. title|string Name of the handout to create or update. May contain spaces. Optional Arguments gmnotes|format tooltip|format bar1_value|format bar1_max|format bar2_value|format bar2_max|format bar3_value|format bar3_max|format Format  may be: h1–h6 blockquote code normal Behavior Flags supernotesGMText|true Wraps GM Notes text before a visible separator line (-----) in a blockquote. If there is no ----- and this setting is true, than the contents of that section will be set to blockquote. The purpose of this is to make all notes that are not specified as gmnotes, player-visible. If you do not use this feature in supernotes, you can ignore this setting. imagelinks|true Adds clickable [Image] links after images that send them to chat. This is a feature in progress, since inline images in a pin may yet eventually be supported. Convert Rules Arguments are  not  prefixed with --, only the base commands (see beginning of help document for a list of these). Argument order is preserved and controls output order. title| values may contain spaces. Images in notes are converted to inline images links. Only tokens on the same page representing the same character are included in the handout. Place Command The  place  command creates or replaces map pins on the current page based on headers found in an existing handout. Format: !pintool --place name|h1–h4 handout|Exact Handout Name Required Arguments name|h1–h4 Header level to scan for in the handout. Each matching header becomes a pin. handout|string Exact, case-sensitive name of an existing handout. Must be unique. Do not use quotes. Behavior Both  Notes  and  GM Notes  of the handout are scanned. Headers found in Notes create pins with  subLinkType|headerPlayer. Headers found in GM Notes create pins with  subLinkType|headerGM. If a pin already exists for a given header on the page, it is  replaced  and retains its existing position. New pins are placed left-to-right across the top grid row of the page, continuing onto additional rows as needed. Pins are created using the same default properties as  --convert replace|true. Notes Handout names may contain spaces. If no matching headers are found, no pins are created. If more than one handout matches the given name, the command aborts. Purge Command The  purge  command removes all tokens on the map similar to the selected token (i.e. that represent the same character), or pins similar to the selected pin  (i.e. that are linked to the same handout) . Format: !pintool --purge tokens Required Arguments tokens  or  pins Example Macros !pintool --set scale|1   — Sets selected pin to size Medium !pintool --set scale|1 filter|all  — Sets all pins on page to size Medium !pintool --set scale|1 filter|-123456789abcd - 123456789abce  - 123456789abcf   —  Sets 3 specific pins on page to size Medium !pintool --set title|Camp notesVisibleTo|all  — Sets title on selected custom pin and makes notes visible to all !pintool --set autoNotesType|  —  changes blockquote behavior on pins. !pintool --convert name|h2 title|Goblin Notes gmnotes|blockquote   — Good all-purpose conversion command General Rules All commands are GM-only. Invalid values abort the entire command. Converting, Placing, or Purging pins can take considerable time, up to 1 second per pin. This is because of the need for the Roll20 engine (not the script) to update the handout to keep all pink links in sync. This is unavoidable

Version History 1.0.2 Cleaned up Help Documentation. Added basic control panel 1.0.1 Added burndown to many parts to account for timeouts - Thanks to the Aaron 1.0.0 Debut

Awesome job done Keith, thank you so much for sharing the script!   Am very much enjoying the use of the pins and was wondering how best to convert my existing ones, so  for me it is sort of a late X-Mas gift ;) Am reading that the  convert  option needs the token to be associated with a character.  My problem is that on many of my maps I have the data included as tooltip text for a  token, and no character linked. guess to convert such tokens is not possible at the moment ? Cheers!

Thanks Alessandro! It should be very possible. There's just an extra step. (Remember to work on a copy of your page for safety's sake. Map Pins are still in beta, and hence, so is this script. 1. Create a simple character for all of the note tokens to be associate with. You don't need to fill in anything, it just needs to exist. Let's call it "Site" for this example. 2. Select all of your note tokens. You can do this all at once or in batches. Make sure you have Tokenmod installed and run the following macro: !token-mod --set represents|Site All of your selected note tokens should now represent the Site character. No other data should have changed. If you want to use the text from the tokens' tooltip, here is the bare minimum command: !pintool --convert name|h2 tooltip|normal title|HANDOUTNAME replace|true Change HANDOUTNAME to whatever you want to call your handout. 3.  Select any of the site tokens and run that command. The script will iterate through every token on the page that represents the "Site" character, and create a handout where the name of the token is the header (h2), the contents of the tooltip is the text. It then places a map pin in the same spot as each of your not tokens. 4. You may want to do some cleanup afterward. If you want to remove all of the note tokens, select one of them and run !pintool --purge tokens and confirm. If you need help fine tuning the map pin settings afterward, let me know.

Thanks a lot! Have tried it but apparently am missing something.... Let me try to explain how I proceeded: I have used tokenmod to link the tokens to a character (2014 or 2024 doesn't matter apparently), next I used Tokenmod to give the tokens a name, then used the "Enumerate Tokens" option (native roll20) to make names unique. After marking a single token or more like in the following screenshots, finally, as last step, fired the suggested Pintool command. But for some reason no new generated pins appear?

Hmm. That macro looks correct. Try deleting the handout and trying again. If that doesn't work, feel free to message me an invite, and I can come take a look in your game and see what the issue might be.

Tested with a newer game am occasionaly using to load game addons. As API scripts only Tokenmod + Pintool and it is working in a very smooth way. So the issue am facing is probably related to the many scripts am using in that game, or maybe because the game was migrated to Jumpgate, or some other weird combination of things that is interfering with pin generation. Who knows. The game evolved over years in a single mess ;) Interesting is that by using the --place parameter (i.e.  !pintool --place name|h1–h4 handout|Exact Handout Name) , i get the pins generated on the top left of the map actually. That's good enough for me :D  And a big thank you for the help offered Keith!

Version 1.0.2 Pintool now has a graphic interface for its most common editing functions. Each button controls a setting on selected pins, or press the "++" part of the button to perform that edit on ll pins on the page.

Hi Keith, I currently use a blank token and your super notes script to send the location description from the tokens GM Notes section in a nice scroll format to chat so players can read along as I describe the location. I'd like to use map pins and initially have them hidden so I can send the location description to chat then make them visible so players can go back and re read descriptions as they choose. Is there a way the player facing block text can be sent to chat ?

Hi FFR! If you mean sending a pin text description to chat, no, not currently. There might be some options, going forward. There are a couple of things to consider. The description Tooltip of a Map Pin can either be a manual entry, or a link to a handout. A script could probably leverage sending the contents of a manual entry to handout, since the notes text is actually stored on the pin. Linked text however would require a more specialized approach: Check the pin for a link Find that area of the linked handout Get all of the text from that linked header onward to, but not including, the next header of that level Format it to send to chat. None of that second procedure is insurmountable, but none of the described code exists within PinTool presently. I have been exploring a new script (originally part of the PinTool project) that would do this and more. I'm thinking of calling it ViewPort , but it's still in the exploratory phase. I want to solidify PinTool with the next wave of Map Pin features coming through the pipeline first. However, I agree that Map Pins would be well-served by some basic Macro compliance. That alone might solve your problem with something like @{selected|notes} or similar. I'll pass that suggestion up the line.

In the meantime, I'll also check with Timmaugh to see if any of his metascripts can be of use here.

This is a helper script that is not part of PinTool Here is a (marginally tested) short script that allows you to send notes , GMNotes and custom images from custom pins (not linked ones) to chat using any Supernotes template (You must have Supernotes installed). Arguments Arguments are case-insensitive and use the format --key|value. --to|<target> Controls where the message is sent. --to|pc Sends a public message to chat. GM notes are never included. --to|gm Whispers the message to the GM only. GM notes are included. --to|self Whispers the message to the invoking player. GM notes are included only if the invoker is a GM. If a non-GM runs the command, --to is ignored and treated as pc. --template|<name> optional Selects a Supernotes display template. If omitted or invalid, the generic template is used silently. Examples: !pinnote !pinnote --to|gm !pinnote --to|self --template|dark !pinnote --template|wizard Requirements Exactly one map pin should be selected. If none are selected, the script reports an error.. If multiple are selected, only the first pin is used. The pin must be a custom pin. If it is set to display a handout link, the script will exist with an error message The pin must contain notes. If the pin’s Notes field is empty, nothing is sent and an error is shown. Supernotes must be installed, in order to supply the templates. If it is missing, the script exits and notifies the GM.

Hi Keith, Thank you so much for looking into this. Just tried it out and got a chat message that says " This pin is not desynced from its linked handout".

Keith, Apologies just read the note at the top about non linked pins. Can confirm when using a non linked pin it does send the note to chat but didn't use the Wizard template. Do you know if there is a way to initially create the pin from a hand out then kill the link to make it a custom pin ?

Keith, Have tested further. Created a custom marker, ran the command and message came through to chat with the wizard template so all working perfectly. Only issue I can see coming up is the 300 character tooltip limitation cutting longer text short. Don't suppose there's a way around this ? Creating a custom marker is not an issue for me as I used to copy and paste text onto invisible tokens anyway and the map pin is so much neater than tokens. Thank you so much for creating this.  

Yup, you've correctly figured out the needed pin settings. Here's a handy little "secret". The --set command (like token mod) can exceed the character limit that you can type manually. If you already have the content, use this command followed by that text. !pintool --set notes|

Keith, Amazing tip. Thanks as always

The PinNote script above has been modified so that it also extracts from linked pins, pulling the information from the linked handout. Notes: The text processing routines are not as robust as Supernotes. Not all templates will be ideal. Even if you specify --to|pc, it will not send GM text. If there is no sublink (header), it will send the entire handout. Test carefully. Although this does not write any data to anything, and is safe to run, I have not done robust enough testing to guarantee that spoilers might not be sent.