wibble199/foundryvtt-terrain-height-tools

Foundry Virtual Tabletop module for painting terrain height and calculating line of sight

Terrain Height Tools

Tools for painting grid cells with terrain heights and calculating line of sight with respect to these heights.

Designed for LANCER, Terrain Height Tools takes inspiration from the way painting tiles works in the Political Map Overlay module by cirrahn; and augments it with some line of sight calculation functionality and the ability to render the heights on the token layer.

Installation

Simply search for 'Terrain Height Tools' in the Foundry 'Install Module' screen and install it from there.

Alternatively, paste this URL into the 'Manifest URL' field of the 'Install Module' dialog in the Foundry configuration: https://github.com/Wibble199/FoundryVTT-Terrain-Height-Tools/releases/latest/download/module.json, then enable the module in your world.

Important

Note that the latest version this module currently only supports Foundry v11.x.

The latest version that supports Foundry v10.x is v0.1.4

Usage

Once installed, the first thing you need to do is configure the paintable terrain types for your world. You can think of terrain types like colours of paint for your paintbrush. This can be done either by:

• Going on to 'Configure Settings' in the Foundry right-hand menu, clicking 'Terrain Height Tools' on the navigation list, then clicking the 'Configure Terrain Types' button.
• Alternatively, you can click the new 'Terrain Height Tools' button on the scene controls (icon is 3 vertical bars of different heights), selecting the 'Paint' tool (icon is a paintbrush), and clicking the cog button on the top right of the 'Terrain Palette' window that appears.

See below for more details about configuring terrain types.

Once at least one type of terrain has been configured, you can then use the tools in the 'Terrain Height Tools' menu to paint terrain onto the map. To do this, you need to click the type of terrain you want to paint in the 'Terrain Palette' window and choose a height for the terrain. You can also optionally enter an elevation. Adjacent grid cells will merge together if their terrain types, their heights, and their elevations are the same.

Line of Sight

Terrain Height Tools provides two tools for testing line of sight (LoS) against the terrain that has been drawn to the scene. Both of them can be found under the tokens menu.

The first, is the humble 'Line of Sight Ruler'. The ruler behaves similarlly to the standard ruler built in to Foundry. You can click and drag between two points, and it will test the line of sight along this line, and highlight any intersections with the terrain. You will also see a 'H' number next to either end of the ruler. This represents the height of that endpoint. You can change this either by using the + and - keys on your keyboard, or typing values into the config window that appears.

The second tool is the 'Token Line of Sight' tool. When you click this tool, you will see a config window appear. Click on the bullseye icon and then click on a token on the scene, for both the boxes that appear. Terrain Height Tools will then draw 3 LoS rays: one from the centre of the first token to the centre of the second; one between the left-most edges of the tokens; and one between the right-most edges. The H value of these lines depends on how the LoS is configured, but it is based on the token's elevation + a modifier multiplied by the token's width (there is no 'vertical height' field for tokens in Foundry, so tokens are assumed to be as tall as they are wide); For example in the default configuration a token with an elevation of 3 and a size of 2, the H would be 5; This represents the top of the token. The tool can instead draw the LoS from the middle or the bottom of a token.

When the LoS rays are drawn to the scene, you will see a line drawn from the source point to the target point. This line is formatted depending on what state it is in at that point:

• A solid white line means that the line is not intersecting with anything.
• A coloured line means that the line is touching or intersecting with some terrain. The colour matches the terrain's colour.
  • If a coloured line is solid, it means that the ray touches a terrain shape, but does not actually intersect it.
  • If a coloured line is dashed, it means that the ray completely intersects a shape.

It's also worth noting that the ray is calculated in 3D space, so if you see it abruptly stop intersecting a shape part way through, it has likely impacted the top or bottom of the shape.

Configuring Terrain Types

To add a new terrain type simply:

1. Click the "Add Terrain Type" button in the bottom left.
2. Give it a name (labelled 2 in the above image). Note that this is what shows in the palette window, NOT what is shown to players on the scene canvas.
3. Select whether or not the terrain type should have a height/elevation.
   • This is the default, however for some types (e.g. objective/control zones) it may not make sense to give them a height. This setting will disable the height option in the palette, and prevent you from accidentally having areas with different heights. Note that disabling this will NOT affect already-painted grid cells.
4. Configure the style of the area that will be painted on the scene - these settings should be familiar if you have used the default Foundry drawing tool before.
   • One thing to note though is that the 'Text Label' (number 8 in the above image), which is what the area will be labelled as, allows a %h% and/or a %e% placeholder to be used. These will be replaced with the height or elevation value of the painted terrain respectively. For example, if you create a type with a label of H%h%, when painted on the scene at height 2, it will have a label of H2. If painted at height 4, it will have a label of H4, etc. Likewise, a label of H%h%+%e% would show H3+4 if it was a height 3 terrain at an elevation of 4.
5. Click 'Save Changes' in the bottom right, and your new terrain type will show up in the palette.

There are some other useful buttons:

• Button 1 expands/collapses the terrain type configuration. Just helps keep the menu tidy!
• Buttons 3 and 4 on the above image are to move the terrain types up and down. This only affects their order in the palette, but you can shift your most-used terrain types to the top if you wish.
• Button 5 allows you to duplicate an existing terrain type, copying all the configuration.
• Button 6 is to delete the terrain type.
• 'Import Preset' (button 9) allows you to easily import a config preset that has been submitted by members of the community. If you would like to submit a preset, please create an issue or pull request on GitHub.
• 'Import JSON' (button 10) allows you to paste JSON in to import some terrain types that have been exported previously.
• 'Export JSON' (button 11) will give you a JSON that you can share with other people, or copy to other worlds and will copy all your terrain types.

Module Settings

Here is a quick reference of the settings module presents in the 'Configure Settings' button of Foundry:

All Users

• Terrain Height Map Visibility Radius - If not zero, the terrain height map will only be shown in a radius of that many grid cells around the mouse cursor. If zero, the entire map will be visible.
• Other User's LoS Ruler Opacity - How opaque/transparent other user's line of sight rulers will appear to you.
• Token LoS: Auto-populate Primary Token - If true, when selecting the Token Line of Sight tool, THT will attempt to populate the first token for LoS measurement. It will prioritise a selected token on the scene if you have one, or if there isn't one it'll attempt to fallback to the token that represents the actor you have configured as your character.
• Token LoS: Auto-populate Secondary Token - If true, when selecting the Token Line of Sight tool, THT will attempt to populate the second token for LoS measurement. It will use the first targeted token on the scene, if there is one.

GM Only

• Terrain Types - Button to open the terrain type configuration (see above)
• Terrain Height Map Above Tiles - This determines whether or not the terrain height map is shown above or below ground-level tiles. The height map is ALWAYS shown below overhead tiles. This can also be configured on a per-scene basis using the 'Terrain Height Map Layer' option on the 'Grid' tab of the scene config settings.
• Display Line of Sight Ruler (GM) - If true, the GM's Line of Sight measurements will be shown to other players.
• Display Line of Sight Ruler (Player) - If true, players' Line of Sight measurements will be shown to other players.

API

Terrain Height Tools exposes an API that can be used by macros, scripts or, other modules. Please see the API documentation for more.

foundryvtt-terrain-height-tools's Issues

[FEATURE] Hotkey for switching to Terrain Height LoS Ruler

With the new release of the tool, I figured there should be a hotkey control for it for easier access.

[Feature Request] Example Terrain Presets

It would be convenient to have one or two presets for terrain that could be loaded and customized to ease in setting up from scratch, examples of what is possible, or for users evaluating whether this module suits their needs.

An idea for ux is that it could be a button that fills in the preset data to the text box.

A possible bonus feature could be allowing systems to define their own presets by providing a path to a json file for THT to load as a preset via a hook or defined on the CONFIG global.

Line of Sight

I have been testing the module in v11 and is the LoS calculations still a feature? Because it doesnt work and the player always have vision of everything

Update to v11

Hi. I was using this module very well. Thank you for creating the module, but lancer system was recently updated to V11. Is there any chance you could update this module to work with V11? Thanks as always.

Automatically Select Token for LoS Tool

The token LoS tool works incredibly well, however it would be nice if your currently selected token was automatically selected as the first token when you open the tool.
This functionally would be great for players and possibly nice for GMs in some cases.
My feeling is that the GM would unselect their current token or open the LoS tool and deselect their current token to make checks otherwise.
For players this is going to be much less frequent, as the majority of their checks are their own, selected token compared to another.

Setting to Respect Vision

Would it be possible to get a setting that respects vision so terrain layers that are within the fog of war aren't rendered for players?

Floating terrain or terrain at height > 0

Firstly, thank you so much for this module already. Works amazing for 99% of maps. For zero-g maps i would love to place cover floating in space which would involved setting two "height" values. the top and bottom of the terrain. Right now, all terrain starts at height 0.

I'm not requesting integration with Walls and Wall Height, just for a way to do floating terrain.

Pictured: A Terrain wall placed at H2-H4, which should not block line of sight for two S1 units at H0

Font choices not saving

Hi, love the module! I'm just having one odd issue: Any time I open the configuration page, the fonts in all terrain types reset to Arial (even if I don't open the various submenus). This has the unfortunate side effect of causing all fonts on the board to be lost whenever I save changes. For reference, I am using Foundry v.11.315 and Terrain Height Tools v.0.20. Any insight or help you can provide would be much appreciated!

Add API to allow macros/modules to trigger line of sight check between tokens

Currently, the API provides functions to allow triggering a LoS check between points.

It would also be useful to be able to trigger this between tokens, as per the new LoS tool - either by an API function which takes two tokens as parameters (e.g. by id) and shows the LoS ruler between them, or by API functions which take a single token as a parameter and display the LoS ruler once both are set.

My use case is an in-person game using Material Plane - an infra-red tracking setup for physical minis which comes with a "pen" that can be used to trigger macros. While it's possible to treat this as a mouse (and use the LoS tool via the current UX), it's clunky, so it would be much smoother for me to be able to select the tokens using the pen and trigger a macro to show the LoS calculation.

This could also be used to, e.g. provide a macro to allow the user to draw the LoS ruler between their controlled token and a targeted token.

Publish on the foundry package listing

The package listing doesn't have any releases, so this module can't be installed by searching in foundry. The package is registered, so you just need to add the releases to the page.

Package management docs: https://foundryvtt.com/article/package-management