Skip to content

Module Configuration

Jump to bottom
Material Foundry edited this page Feb 17, 2024 · 5 revisions

This wiki is deprecated, new documentation here.

The configuration for Material Plane is done through the configuration menu. This menu can be accessed in the 'Game Settings' sidebar tab.
The first thing you should do, is set 'Device' to 'Touch Screen' in the 'General' tab. This will configure the configuration menu to only display settings relevant to touch screens.

There are various tabs, depending on the device (DIY sensor, Beta sensor or touch screen), some tabs might not be shown:

  • General: General settings for the module
  • Connection: (Beta & DIY sensor only) Settings for connecting to the sensor
  • Sensor: (Beta & DIY sensor only) Sensor settings
  • Base Setup: (Beta sensor only) Base configuration, for linking bases to tokens or actors
  • Remote Control: (Beta sensor only) Remote control configuration, for allowing macro's to be triggered using a normal remote control
  • Downloads: (Beta & DIY sensor only) To download sensor and base firmware updates, or to download Material Server
  • Touch: (Touch screen only) Touch screen configuration

General Settings

The general settings cover settings that are relevant for all Material Plane users. It configures how the module behaves.
In these settings, terms like 'dropping the mini' are used. What's meant with this, is that when movement is no longer detected or a base is released, the token stops being controlled/active.

  • Target User: Here you configure which user has the TV connected to it. This user will be used by all the players and will handle all the interactions with the touch screen. Changing this setting will refresh the browser after closing the configuration menu
  • Device: Configure what device is used to track minis. Select either 'Material Plane Sensor' if you're using the DIY or Beta sensor, or 'Touch Screen' if you're using an IR Touch Frame or other Touch screen device. Changing this setting will refresh the browser after closing the configuration menu
  • Movement Method: With this setting you can configure how movement and vision is updated. There are 3 settings:
    • Default: This is similar to the default Foundry behavior. Moving a mini will move the corresponding token, but vision is only updated after the token is dropped. This option is the least performance intensive
    • Step-By-Step: When a mini is moved to the next grid space, the corresponding token's position and is immediately updated to that position. This means that the token will move in steps, where each new grid space forms a step
    • Live: When is mini is moved, the corresponding token's vision is updated live. This is the most resource intensive option, but is much more fluid and realistic than the others
  • Deselect Token After Drop: When a mini is moved, its corresponding token is automatically selected. With this option disabled, the token will stay selected until deselected through other means. This means that multiple tokens can be selected, so their vision is shared. With this option enabled, the token will be deselected once the mini is dropped. This means that when moving a mini, only the vision of that token is displayed
  • Draw Movement Marker: Enabling this will draw a green or red square on the grid space where the token would land if it is dropped. A green square means that the token is allowed to be moved there, while a red square means it isn't allowed to, probably due to a wall collision
  • Non-Owned Movement: With this setting disabled, only tokens that are owned by the target user can be controlled. With this setting enabled, all tokens can be controlled. This can be useful if NPC minis are used, and are being tracked with Material Plane. Non-owned tokens are allowed to pass through walls, but their vision is not shared with 'Target User'
  • Token Collision Prevention: (Experimental) When enabled, Material Plane will try to prevent token collisions. If one token ends up in an occupied grid space, an invisible straight line between the starting and ending position of the movement is drawn. Instead of moving onto the occupied space, the token will be placed on the nearest allowable space along the line
  • Hide Display Elements: Hides all the display (UI) elements for the target player (if the target player is not a GM). This will give a cleaner look, and the elements are mostly unused anyway when using Material Plane. The elements can be toggled on or of using the 'Ctrl' button on the keyboard. Changing this setting will refresh the browser after closing the configuration menu
  • Pen Menu Size: (Beta sensor only) Sets the size of the pen menu. Unit is relative to the grid size
  • Block Interactions: Blocks all canvas interactions if the configuration menu is open. This means that tokens cannot be moved if this setting is enabled. This can be useful during configuration, so you don't accidentally move tokens. This setting resets to enabled after a refresh

Connection

Beta & DIY sensor only.
The connection tab covers settings for configuring Material Plane to connect to the sensor.
If any of these settings are changed, the browser will refresh after closing the configuration.

  • Connect to the Sensor: Can be used to prevent the current client from trying to connect to the sensor
  • Sensor Module IP Address: The IP address and port of the sensor. By default this is 'materialsensor.local:30000'. If you've changed either the sensor name or the websocket port (in the webserver), you will need to change this accordingly ('[name].local:[websocket port]')
  • Use Material Server: You can use Material Server as a proxy in case your Foundry server is secured, or if you want to connect the sensor through USB
  • Material Server IP Address: The IP Address and port of Material Server. By default this is 'localhost:3001', but can be configured in Material Server

More info on using Material Server with Material Plane can be found here.


Sensor

Beta & DIY sensor only.
The sensor tab is used to configure the sensor. These settings can also be configured through the [sensor webserver](https://github.com/CDeenen/MaterialPlane/wiki/Sensor-Webserver).
This tab is divided into 2 sections: The configuration section on the left, and the data display section on the right.

Configuration

Here you can configure all settings related to detecting bases. The screen is divided into multiple drop-down sections, an explanation of every setting can be found when clicking the relevant section name.

Data Display

The data display section displays data of any detected bases (or other IR sources).

The rectangle at the top is a real-time representation of what the sensor sees (after calibration), where each detected IR point is displayed as a colored dot with a number next to it. The first detected IR point is always 0, and from there it counts up.

Below the rectangle is a table containing data for the first 4 IR points.
Some background information on how the sensor works is required to understand some of these fields:

The sensor works like a camera, so when an IR light source is in its vision, one or more camera pixels detect it. If all of the pixels that detect the light are close enough to each other, it will consider this collection of pixels to be a single IR point. If there is a big enough space between multiple collections of pixels, it will consider each collection to be a unique IR point.

  • X: X-coordinate of the point (after calibration)
  • Y: Y-coordinate of the point (after calibration)
  • Average Brightness: (Beta sensor only) The average brightness of all pixels of the IR point
  • Maximum Brightness: The brightness of the brightest pixel of the IR point
  • Area: (Beta sensor only) The area of the IR point. Higher means that more pixels have detected the IR light

Below that, the detected base ID and command are displayed (Beta sensor only).


Base Setup

Beta sensor only.
Each beta base sends out a unique ID when it is active. This ID allows Foundry to know exactly which base was moved, and can therefore be used to assign a base to a token or actor.

In the top right, you'll find the data of the most recent base and selected token. Activating a different base, or selecting a different token will update this data.
At the bottom, you can perform the assigning.

You can assign a base to a specific token on a specific scene, or to a specific actor (which will be active for all scenes).
You can assign a base to multiple tokens or actors. If a scene contains multiple tokens or actors that are assigned to it, it will only control the first.
If an assigned base is used, but the token or actor it is assigned to is not on the scene, the base will act like a normal unassigned base (allows control of any token).

By pressing the '+' button, you can add a new rule. Each rule has the following settings:
  • Base Id: The Id of the base that you want to link
  • Token Name: The name of the token that you want to link (only required if 'Link Actor' is not enabled)
  • Token Scene: The scene that you want this link to be active in (only required if 'Link Actor' is not enabled)
  • Actor Name: The name of the actor that you want to link (only required if 'Link Actor' is enabled)
  • Link Actor: Enabling this will link the actor, instead of the token. This makes the rule active for all scenes
  • Id: Pressing this button will take the most recently detected base Id, and fill this in
  • Data: Pressing this button will take the token data of the most recent selected token, and fill this in
  • Delete: Delete the rule

Basic linking will follow these steps:

  1. Activate the desired base
  2. Select the desired token
  3. Press the '+' button to add a new rule
  4. Press the 'Id" and 'Data' button to fill in the base Id and token data
  5. (Optional) enable 'Link Actor'

You can also manually enter all the data.

Example Configurations

In the top line of the image you can see that the base with ID 20267 is used to control a token named Akra (with actor name Akra (Dragonborn Cleric)). Since 'link' is deselected, only this specific token on the specific scene (Village) will be controlled. On other scenes, this base is unlinked. If desired, you can use the same base for different tokens on different scenes. This is most useful for NPC minis, since they are often onlly used on one scene, allowing you to use the same base for different NPCs.

On the bottom line, a linked base is displayed. In this case, the base with ID 21059 will control any token of actor Krusk (Half-Orc Paladin) on any scene. Since PCs are usually used on many different scenes, this allows you to only configure that base once.


Remote Control

Beta sensor only.

The Material Plane sensor is able to read IR codes sent by remote controls. In this tab you can configure these codes to trigger macros. You could gather some old unused remotes and give them to your player so they have a way to interact with Foundry. For example, you could press the up button on a remote to trigger a macro that pans the canvas up, or you could use the 1 button to trigger an attack macro.

IR remote controls use various protocols to communicate with their target devices. The sensor is able to read the following protocols:

  • NEC
  • Samsung
  • LG
  • LG32

Many other manufacturers also use these same protocols, so there is a good chance that your remote controls work.
Please note that you are not able to send multiple IR codes at the same time, and you are not able to move bases or use the pen at the same time as a remote control.

In the top right, you'll find the data of the most recently sent IR code. Sending a new code (by pressing a button on a remote control) will update this data.
At the bottom, you can configure the codes.
By pressing the '+' button, you can add a new rule. Each rule has the following settings:

  • Name: Name or description of the rule
  • Protocol: The IR protocol of the code
  • Code: The IR code
  • Macro: The macro to execute
  • Argument: You can fill in arguments that work with the Furnace or Advanced Macros. Read the documentation on those modules for more information on how to use macro arguments
  • Delay: Remote controls can often send out codes in quick succession. You probably don't want the macro to trigger every time, so you can configure a delay. This delay is the minimum time (in ms) that has to pass between each macro execution. So if it's set to 1000ms, the macro will trigger at most once per second
  • Copy: Pressing this button will take the most recent protocol and code data, and fill this in
  • Delete: Delete the rule

Example Configurations

Moving a token
Consider the top 4 rules in the image. These are each assigned to their own button on a single remote control (in this case the up, down, right and left buttons) that transmits codes using the NEC protocol. All of these rules call a macro called MoveToken, which will move the currently selected token 1 grid space in a specified direction each time the macro is called. The arguments determine the direction the token moves in (in this case, the first argument is the x-direction, and the second is the y-direction). So 0 1 will move the token 0 spaces in the x-direction, and 1 space in the y-direction.
The MoveToken macro is a script macro containing the following code:

if (!token) return;                               // Do nothing if no token is selected
const gridSize = canvas.scene.dimensions.size;    // Get the grid size of the current scene
const x = token.x + args[0] * gridSize;           // Calculate the new x-coordinate
const y = token.y - args[1] * gridSize;           // Calculate the new y-coordinate
token.document.update({x, y});                    // Update the position of the token

If the button is held down, the remote control will send the code at a very high rate. Through experimentation I've found that setting a delay of 150 ms is ideal for this rule. This is slow enough that you can easily move a token a single grid space, while being fast enough that you can move the token quite fast when holding down the button.

Selecting a token
Consider the bottom 2 rules. Here, a remote control using the NEC protocol is used to select a specific token. When the specified button is pressed, the SelectToken macro is called, using the token name Akra or Krusk as argument. So the Select Akra rule will select a token named Akra.
The SelectToken macro is a script macro containing the following code:

const tokenToFind = canvas.tokens.placeables.find(t => t.name == args[0]);   // Find a token in the current scene with the specified name
if (tokenToFind == undefined) return;                                        // If no token was found, do nothing
tokenToFind.control({releaseOthers: true});                                  // Select the token, while releasing all other selected tokens

I've set the delay to 500 ms, so holding down the button too long doesn't cause the macro to be called that often.


Downloads

Beta & DIY sensor only.
In the downloads tab, you can download firmware and Material Server, and you can check if you're currently using the latest module or firmware versions.

  • Current: The version that is currently installed (not available for the base and pen)
  • Minimum: The minimum version that is compatible with the currently installed module version
  • Latest: The latest version available for download
  • Variant: Variants that can be downloaded
  • Download: Button to download the latest version

Pressing the 'Refresh' button at the bottom will search again for the latest versions.


Touch

Touch screen only.
The touch settings cover settings that configure how touches are handled.
  • Tap Mode: You can tap the screen in order to interact with some canvas elements, such as opening doors. Here you can configure how taps are detected. More info on tapping here
  • Token Drop Timeout: Every time that a token is moved, a timer starts (or is reset). Once that timer has reached this value in milliseconds, it will drop the token. So if configured to 500ms and a mini hasn't been moved for 500ms, that mini will be dropped
  • Tap Timeout: Sets the timeout to detect a tap, move info here

Clone this wiki locally