Skip to content

p4535992/foundryvtt-arms-reach

Repository files navigation

FoundryVTT Arms Reach

Latest Release Download Count

Forge Installs

Foundry Core Compatible Version

Latest Version

Foundry Hub Endorsements

GitHub all releases

Translation status

Little Utilities, Arms Reach for door, journal, stairways, token, ecc.

This project is born like a upgrade of the project Arms Reach ty to psyny, in preparation of foundry vtt 0.8.0, but after a while i put some feature here and there and now i got something a little more complex.

I'll try to make this module system indipendent , but if anyone has some rule distance computation for a specific system i can put some more settings for manage that.

Known issue/Limitation

  • I know there is some measure distance issue expecially with diagonals, here some details Can "reach" further to the east and Not working well with Doors on Diagonal walls, this problem is limited only to the Door interaction distance calculation, the current solution for this cases is push the "Shift" button to snap out from the grid movement and move the token these 2 px the distance calculation need to validate the interaction, these cases are so few that i will not spend more time on that, anyone is welcome to ope a PR about it
  • The module setting "Avoid deselects the controlled token" doesn't work well with the option "Release on left click" of foundry , if you own more than a token you will find yourself to manually reselect the token anyway
  • When you scale a placeable object the event (click, ecc.), are limited only to the original coordinates {x, y} and not the "scaled" image

Installation

It's always easiest to install modules from the in game add-on browser.

To install this module manually:

  1. Inside the Foundry "Configuration and Setup" screen, click "Add-on Modules"
  2. Click "Install Module"
  3. In the "Manifest URL" field, paste the following url: https://raw.githubusercontent.com/p4535992/foundryvtt-arms-reach/master/src/module.json
  4. Click 'Install' and wait for installation to complete
  5. Don't forget to enable the module in game using the "Manage Module" button

libWrapper

This module uses the libWrapper library for wrapping core methods. It is a hard dependency and it is recommended for the best experience and compatibility with other modules.

Module compatibility

API

A little api to use in macro cc. for check if the placeable object reachable with variant based on the string id or the string tag from the module tagger.

The api is reachable from the variable game.modules.get('arms-reach').api or from the socket libary socketLib on the variable game.modules.get('arms-reach').socket if present and active.

isReachable(token: Token, placeableObject: PlaceableObject, maxDistance?: number, useGrid?: boolean, userId?: string):boolean ⇒ boolean

Calculate the distance between the source token and the target placeable objet Returns: boolean - The boolean value for tell if the target is near enough to the source token

Param Type Description
token Token The source token
placeableObject placeableObject The target placeable object
maxDistance number OPTIONAL: explicit distance (units or grid) to check
useGrid boolean OPTIONAL: if true it will explicit calculate the grid distance instead the unit distance
userID string OPTIONAL: user id for the distance checking

Example: game.modules.get('arms-reach').api.isReachable(token: Token, placeableObject: PlaceableObject, maxDistance?: number, useGrid?: boolean, userId?: string):boolean

isReachableByTag(token: Token, tag: string, maxDistance?: number, useGrid?: boolean, userId?: string):boolean ⇒ boolean

Calculate the distance between the source token and the first target placeable objet with a specific tag, the method 'isReachableByTag' need the Tagger Module installed and active for work. Returns: boolean - The boolean value for tell if the first target with the specific tag is near enough to the source token

Param Type Description
token Token The source token
tag string The tag from the Tagger Module to check for start the distance calculation
maxDistance number OPTIONAL: explicit distance (units or grid) to check
useGrid boolean OPTIONAL: if true it will explicit calculate the grid distance instead the unit distance
userID string OPTIONAL: user id for the distance checking

Example: game.modules.get('arms-reach').api.isReachableByTag(token: Token, tag: string, maxDistance?: number, useGrid?: boolean, userId?: string): boolean

isReachableById(token: Token, placeableObjectId: string, maxDistance?: number, useGrid?: boolean, userId?: string):boolean ⇒ boolean

Calculate the distance between the source token and the target placeable objet Returns: boolean - The boolean value for tell if the target is near enough to the source token

Param Type Description
token Token The source token
placeableObjectId string The target placeable object id reference
maxDistance number OPTIONAL: explicit distance (units or grid) to check
useGrid boolean OPTIONAL: if true it will explicit calculate the grid distance instead the unit distance
userID string OPTIONAL: user id for the distance checking

Example: game.modules.get('arms-reach').api.isReachableById(token: Token, placeableObjectId: string, maxDistance?: number, useGrid?: boolean, userId?: string): boolean

isReachableByIdOrName(token: Token, placeableObjectIdOrName: string, maxDistance?: number, useGrid?: boolean, userId?: string):boolean ⇒ boolean

Calculate the distance between the source token and the target placeable objet Returns: boolean - The boolean value for tell if the target is near enough to the source token

Param Type Description
token Token The source token
placeableObjectIdOrName placeableObject The target placeable object id or name or label or entry reference
maxDistance number OPTIONAL: explicit distance (units or grid) to check
useGrid boolean OPTIONAL: if true it will explicit calculate the grid distance instead the unit distance
userID string OPTIONAL: user id for the distance checking

Example: game.modules.get('arms-reach').api.isReachableByIdOrName(token: Token, placeableObjectIdOrName: string, maxDistance?: number, useGrid?: boolean, userId?: string): boolean

isReachableUniversal(placeableObject: PlaceableObject, placeableObject: PlaceableObject, maxDistance?: number, useGrid?: boolean, userId?: string):boolean ⇒ boolean

Calculate the distance between the source token and the target placeable objet Returns: boolean - The boolean value for tell if the target is near enough to the source token

Param Type Description
token Token The source token
placeableObject placeableObject The target placeable object
maxDistance number OPTIONAL: explicit distance (units or grid) to check
useGrid boolean OPTIONAL: if true it will explicit calculate the grid distance instead the unit distance
userID string OPTIONAL: user id for the distance checking

Example: game.modules.get('arms-reach').api.isReachableUniversal(placeableObject: PlaceableObject, placeableObject: PlaceableObject, maxDistance?: number, useGrid?: boolean, userId?: string):boolean

isReachableByTagUniversal(placeableObject: PlaceableObject, tag: string, maxDistance?: number, useGrid?: boolean, userId?: string):boolean ⇒ boolean

Calculate the distance between the source token and the first target placeable objet with a specific tag, the method 'isReachableByTag' need the Tagger Module installed and active for work. Returns: boolean - The boolean value for tell if the first target with the specific tag is near enough to the source token

Param Type Description
placeableObject placeableObject The source placeableobject
tag string The tag from the Tagger Module to check for start the distance calculation
maxDistance number OPTIONAL: explicit distance (units or grid) to check
useGrid boolean OPTIONAL: if true it will explicit calculate the grid distance instead the unit distance
userID string OPTIONAL: user id for the distance checking

Example: game.modules.get('arms-reach').api.isReachableByTagUniversal(placeableObject: PlaceableObject, tag: string, maxDistance?: number, useGrid?: boolean, userId?: string): boolean

isReachableByIdUniversal(placeableObject: PlaceableObject, placeableObjectId: string, maxDistance?: number, useGrid?: boolean, userId?: string):boolean ⇒ boolean

Calculate the distance between the source token and the target placeable objet Returns: boolean - The boolean value for tell if the target is near enough to the source token

Param Type Description
placeableObject placeableObject The source placeableobject
placeableObjectId string The target placeable object id reference
maxDistance number OPTIONAL: explicit distance (units or grid) to check
useGrid boolean OPTIONAL: if true it will explicit calculate the grid distance instead the unit distance
userID string OPTIONAL: user id for the distance checking

Example: game.modules.get('arms-reach').api.isReachableByIdUniversal(placeableObject: PlaceableObject, placeableObjectId: string, maxDistance?: number, useGrid?: boolean, userId?: string): boolean

isReachableByIdOrNameUniversal(placeableObject: PlaceableObject, placeableObjectIdOrName: string, maxDistance?: number, useGrid?: boolean, userId?: string):boolean ⇒ boolean

Calculate the distance between the source token and the target placeable objet Returns: boolean - The boolean value for tell if the target is near enough to the source token

Param Type Description
placeableObject placeableObject The source placeableobject
placeableObjectIdOrName placeableObject The target placeable object id or name or label or entry reference
maxDistance number OPTIONAL: explicit distance (units or grid) to check
useGrid boolean OPTIONAL: if true it will explicit calculate the grid distance instead the unit distance
userID string OPTIONAL: user id for the distance checking

Example: game.modules.get('arms-reach').api.isReachableByIdOrNameUniversal(placeableObject: PlaceableObject, placeableObjectIdOrName: string, maxDistance?: number, useGrid?: boolean, userId?: string): boolean

Integration with Socketlib module

You can use the socketLib for call the same functions:

await game.modules.get('arms-reach').socket.executeAsGM('isReachable', token: Token, placeableObject: PlaceableObject, maxDistance?: number, useGrid?: boolean, userId?: string):Promise

await game.modules.get('arms-reach').socket.executeAsGM('isReachableByTag', token: Token, tag: string, maxDistance?: number, useGrid?: boolean, userId?: string): Promise

await game.modules.get('arms-reach').socket.executeAsGM('isReachableById', token: Token, placeableObjectId: string, maxDistance?: number, useGrid?: boolean, userId?: string): Promise

await game.modules.get('arms-reach').socket.executeAsGM('isReachableByIdOrName', token: Token, placeableObjectIdOrName: string, maxDistance?: number, useGrid?: boolean, userId?: string): Promise

NOTE: for now the optional parameter 'userId' is not used from the api, i hope to add in the future some filter so a specific actor for a specific user has some limitation.

Features

The interaction distance is measure by the distance between a token and a placeable object like door, journal, stairways, ecc.

To interact with a door, journal, ecc., the player need to have a token selected (or own a token) for make the calculation distance working well

Door Feature

  • Enable the GM to select the maximum distance that players can interact with a door (needs a token selected) (DM bypass this limitation)

  • Pressing 'e' opens/closes a door nearest of current selected token

NOTE: If no token is selected and you are a GM this feature is not activated

Stairways Feature

  • If the module 'stairways' is present and active and the module settings is true there is a distance check interaction when you click on the stairways icon.

Note/Journal Feature

  • Add distance calculation for note and journal on the canvas
  • Automatically flag journal notes to show on the map without having to have your players turn it on themselves.

Token Feature

  • Add distance calculation for owned source token and generic target token on the canvas for open the sheet and emulate a loot chest
  • GM can use this feature but beware there is probably some glitch in some use case because they owned every token
  • [OPTIONAL] You can set the name of your explicit source token (not the character name) on the specific module setting
  • If no explicit source token is setted on the module setting the module take the first selected token of the player, if no selected token ias present it will try to get the first owwned token of the player
  • It's advisable for this feature to use the Tagger Module instead the name and sheet checker is more dinamic.

Light Feature (Beta need feedback)

Drawing Feature (Beta it should be working but only on the API level)

  • Add distance calculation for drawings on the canvas

Tile Feature (Beta it should be working but only on the API level)

  • Add distance calculation for tiles on the canvas

Sounds Feature (Beta it should be working but only on the API level)

  • Add distance calculation for sounds on the canvas

Templates Feature (Beta it should be working but only on the API level)

  • Add distance calculation for templates on the canvas

Wall Feature (Beta it should be working but only on the API level)

  • Add distance calculation for walls on the canvas (door are a special case with specific rule)

Tagger Feature

  • Add integration with Tagger Module, you decide specifically for which placeable objects on the canvas the distance calculation should be triggered
  • IMPORTANT: the tagger you must used for any placeable object is the string 'armsreach'
  • From 2.2.11 this feature is been splitted for each category of placeable object (Wall, Token, Note, ecc.) for a better customization

Customize the distance interaction in every placeable object Wall, Light, Stairway, ecc.

Build

Install all packages

npm install

dev

dev will let you develop you own code with hot reloading on the browser

npm run dev

build

build will build and set up a symlink between dist and your dataPath.

npm run build

build:watch

build:watch will build and watch for changes, rebuilding automatically.

npm run build:watch

prettier-format

prettier-format launch the prettier plugin based on the configuration here

npm run-script prettier-format

lint

lint launch the eslint process based on the configuration here

npm run-script lint

lint:fix

lint:fix launch the eslint process with the fix argument

npm run-script lint:fix

build:json

build:json unpack LevelDB pack on src/packs to the json db sources in src/packs/_sourcevery useful for backup your items and manually fix some hard issue with some text editor

npm run-script build:json

build:clean

build:clean clean packs json sources in src/packs/_source. NOTE: usually this command is launched after the command build:json and after make some modifications on the json source files with some text editor, but before the build:db

npm run-script build:clean

build:db

build:db packs the json db sources in src/packs/_source to LevelDB pack on src/packs with the new jsons. NOTE: usually this command is launched after the command build:json and after make some modifications on the json source files with some text editor

npm run-script build:db

Issues

Any issues, bugs, or feature requests are always welcome to be reported directly to the Issue Tracker, or using the Bug Reporter Module.

License

This package is under an MIT license and the Foundry Virtual Tabletop Limited License Agreement for module development.

Credit

Thanks to anyone who helps me with this code! I appreciate the user community's feedback on this project!

A very big thanks to manuelVo, because i was to stupid to understand thing like measurement of Foundry by myself. A very big thanks to Saibot393, and his GeometricUtils class for token distance calculation.