Pintool [ Demonstration Video ] [ Update 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 Displays the control panel: All functions (and more) are also available using the macro codes below. 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. --library — Browse and copy saved pin styles from the Pin Library page. --transform — Apply transformations to pins (currently supports automatic text icon generation). 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 Preset sizes: teeny, tiny, small, medium, large, huge, gigantic bgColor — Background color (hex rgb or rgba for transparency) or transparent ) shape — teardrop, circle, diamond, square tooltipImageSize — small, medium, large, xl Display Mode customizationType — icon or image icon — Icon preset identifier base-dot, base-castle, base-skullSimple, base-spartanHelm, base-radioactive, base-heart, base-star, base-starSign, base-pin, base-speechBubble, base-file, base-plus, base-circleCross, base-dartBoard, base-badge, base-flagPin, base-crosshair, base-scrollOpen, base-diamond, base-photo, base-fourStarShort, base-circleStar, base-lock, base-crown, base-leaf, base-signpost, base-beer, base-compass, base-video, base-key, base-chest, base-village, base-swordUp, base-house, base-house2, base-church, base-government, base-blacksmith, base-stable, base-gear, base-bridge, base-mountain, base-exclamation, base-question pinImage — Roll20 image URL for custom pin image useTextIcon — true or false iconText — Up to 3 characters displayed as a text icon Note, setting icon, iconText, or pinImage will automatically change the customizationType to match. 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 No longer recommended. This was a hack. It has been left in for those who still want to use its ability to send the image to text. However, I would recommend using the Mod Script PinNote for this purpose. 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 Transform Command The transform command applies derived transformations to pins or transfers image data between pins and graphics. Formats: !pintool --transform autotext [filter|target] !pintool --transform imageto|pin !pintool --transform imageto|graphic Supported Transforms autotext Derives up to 3 characters from the pin’s title (or subLink if the title is empty) and converts the pin into a text icon. imageto|pin Copies the image from a selected graphic to a selected pin, setting the pin to use customizationType|image. imageto|graphic Copies the stored image from a selected pin to a selected graphic. Autotext Behavior Text is derived from the first alphanumeric characters found in the pin’s title. If the title is empty, subLink is used instead. If no valid characters are found, the pin is not modified. The filter| argument controls which pins are processed and follows the same targeting rules as the --set command. Image Transfer Behavior if transferring graphic image to pin Exactly one graphic and any number of pins must be selected. if transferring pin image to graphic Exactly one pin and any number of graphic must be selected. The direction of transfer is determined by the command argument. No filter options apply to image transfers. If the required objects are not selected, the command aborts with an error. Pin Library The --library command allows you to browse and copy saved pin styles from a dedicated page named Pin Library . Format: !pintool --library !pintool --library keyword|keyword Setup Create a page named exactly Pin Library . Create pins on that page configured with the styles you want to reuse. Add keywords to each pin title in square brackets: Camp [travel, wilderness] Battle [combat, viking] Treasure [loot] Behavior !pintool --library lists all available keywords. Selecting a keyword displays matching pin styles. Clicking a style copies its appearance to selected pins. Position, title, notes, and links are not overwritten. If the Pin Library page does not exist or contains no valid keyworded pins, the command will display an error. 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 !pintool --set bgColor|#307bb8 shape|circle — Sets selected pin color and shape !pintool --set pinImage|https://... — Sets custom pin image !pintool --transform autotext — Generates 3-letter text icons from titles !pintool --transform imageto|pin — Copies the image from a selected graphic to a selected pin !pintool --transform imageto|graphic — Copies the image stored on a pin to a selected graphic !pintool --library — Browse saved pin styles !pintool --set x|?{Input scale transformation using +-/* number} y|?{Input scale transformation using +-/* number} — Use when you have scaled a page and wish all of the pins to scale porportionately, preserving their spatial relationships 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
