Material Keys is a Foundry VTT module that allows you to control various features of Foundry using a Novation Launchpad Mini Mk3 or through the built-in emulator. The Launchpad is a MIDI controller, that has 80 physical keys, each with an RGB LED.
Material Keys currently has 8 different functions:
- Soundboard
- Playlist Control
- Playlist Volume Control
- Visual Effects Control
- Combat Tracker
- Token Health Tracker
- Macroboard
- Soundscape
This video shows most of the features, and how to set everything up.
Besides the Material Keys module and the Launchpad, you will also need to use a companion app, called Material Server. Material Server is a simple app that will bridge the communication between the Launchpad and Foundry, since Foundry does not support USB devices natively. The app can be downloaded here.
Connection between the app and both Foundry and the Launchpad should be automatic, if not, you can find more details here.
The module needs to be enabled (both in 'Manage Modules' and in the module settings), and the correct Material Server address must be set for the module to work. Please see the section on the module settings below.
3 different key types can be found on the Launchpad:
- Function keys: The 8 vertical keys on the right, the function of these keys is to change between the various Material Keys functions
- Control keys: The 8 horizontal keys on the top, the function of which will change depending on the selected function
- Main keys: The other 64 keys that form the majority of keys
In the module settings screen, you can find some settings, and 3 buttons:
- Help: Opens this screen.
- Playlist Configuration: Enter the playlist configuration screen.
- Soundboard Configuration: Enter the soundboard configuration screen.
- Macro Configuration: Enter the macro configuration screen.
- Enable Module: Enables the module.
- Brightness: Sets the LED brightness of the Launchpad.
- Material Server Address: Fill in the address of Material Server (usually if you run it on the same computer as you're using for Foundry, this can be localhost:3001). This is not necessarily the IP address of Foundry! It is the IP address of the computer that's running Material Server. The default value will work for 99% of people, only change it if you know what you're doing. More info on Material Server can be found here
- Number of Connection Warnings - Sets the number of times you will get a warning when Material Deck cannot connect to Material Server. Will be unlimited if set to 0.
Using the Soundboard, you can easily play audio tracks.
You could, for example, set up some keys to play battle effects, such as clashing swords, arrow hits, or explosions. Another thing you could do is to create an atmosphere, by setting some keys to play, for example, weather sounds.
You can enter the Soundboard by pressing the first Function key from the top.
Once you've set up the soundboard, pressing a key will play the pre-set sound and change the LED to indicate the sound is playing. Pressing the key again will stop the sound.
The red button on the top left (left-most Control key) will stop all currently playing sounds.
The Soundboard is set-up in the Soundboard Configuration screen, which can be found in the module settings.
The screen is divided into boxes, each labeled 'Sound #', where each represents a single sound and its settings. This screen will be refered to as a page.
By pressing the arrows at the top right and top left, you can go to the next or previous page. Sound 1 is the top left main key, Sound 2 is the one to the right of that, etc.
You can set up a total of 256 sounds. Since there are only 64 keys on the Launchpad, you have to access the next 64 sounds by pressing the first Function key from the top.
For each sound there are multiple options:
- Name: (Optional) Set a name for the sound. This is only used in the emulator (see below).
- Playlist: Sets the playlist from which you want to select a sound. If you select 'File Picker', a file picker will appear instead of the sound selection drop-down menu.
- Sound: This is either a drop-down menu where you can select a sound from the selected playlist, or a file picker. When using the file picker, it is possible to use wildcard names, this means that you can randomly play a sound from a selection. To do this, navigate to the folder that contains the sounds, in the textbox append the folder name with the common part of the name of the sounds you want to play, followed by an asterisk. For example, if you have the sounds 'Thunder.wav', 'Thunder2.wav' and 'Thunder3.wav' in the folder 'Assets', you could fill in the following: 'Assets/Thunder*', which will play one of the three sounds randomly when you press the key on the Launchpad.
- Toggle: This determines what should be done once a sound is activated. You can either change the LED color ('Color'), cause the LED to blink on and off ('Blink'), or cause the LED to fade on and off ('Fade'). Once the sound has finished playing, the LED will automatically switch to the off mode.
- On: This sets the color when the chosen sound is playing, and 'Toggle' is set to 'Color'. See below for information on what the color number represents.
- Off: This sets the color when the chosen sound is not playing. See below for information on what the color number represents.
- Playback: Sets the playback mode. The sound can either play once ('Once'), be played on repeat ('Repeat'), or only be played as long as the key is pressed ('Hold').
- Volume: Sets the playback volume. This volume is relative to the 'Interface' volume set in the 'Audio Playlists' tab in the Foundry sidebar.
At the bottom you have the following buttons:
- Clear Page - Clears all the sounds on the current page. Please note that this is irreversible.
- Clear All - Clears all the sounds. Please note that this is irreversible.
- Import - Import the soundboard from a file. This will override your current soundboard, and is irreversible.
- Export - Export your soundboard to a file.
The LED color is represented by a number. This number corresponds with a factory programmed color, as can be seen in the image below. Besides filling in a number, you could also press the palette button next to the number field, which allows the Launchpad to display all the available colors. There are 2 groups of 64 colors, and by pressing the fading green function key (rightmost key), you can switch between the groups. The currently selected color will be fading, and pressing a key will send the color of that key to the Soundboard Configuration screen.
An empty color field will be interpreted as a 0, which means that the LED will be off.
The playlist control screen gives easy control over up to 8 playlists. For each of these playlists, up to 32 tracks can be directly controlled.
For each of these tracks and playlists, you have an indicator showing that the track/playlist is playing and you can stop or play tracks or playlists.
You can enter the playlist control by pressing the second function key from the top.
The screen is divided into 8 columns, where each column represents a playlist. The control (uppermost) key indicates and controls the playlist. If that playlist is playing, the LED will turn green (by default), if that playlist is not playing, it will turn red (by default). Pressing the key when the playlist is not playing will start the playlist, pressing the key when the playlist is playing will stop it. The same functionality can be found in the other 8 keys in the column. These 8 keys represent 8 tracks in the playlist. If there are more than 8 tracks in the playlist, pressing the playlist control function key will toggle between up to 4 pages, where each page controls 8 tracks. Below the playlist control function key, up to 4 function keys will start blinking or fading, this indicates how many pages are available (determined by the amount of function keys that are lit), and the blinking led indicates on which page you currently are. The playlist control function key will also change color to correspond with the selected page.
Note 1: Pressing any of the blinking or fading function keys will take you out of the playlist control screen, and into the screen that key is assigned to (for example, pressing the key below the playlist function key will open the playlist volume control screen). You have to toggle between the pages by pressing the playlist control function key (second function key from the top).
Note 2: This page functionality is not shown in the image below.
The playlist control can be configured in the playlist configuration screen, which can be found in the module settings.
Settings:
- Default Play Method: The default play method determines what to do when a track is playing, while another track is requested. By setting it to 'Unrestricted', you can play as many tracks at the same time as you want. Setting it to 'One track per playlist' will automatically stop all playing tracks in the playlist, ensuring that only one track is playing at a time. Setting 'Play Method' to 'One track in total' will limit playback to only one track in total.
Note: This play method only applies if tracks are started using the Launchpad, you can still play more tracks using Foundry's internal audio player. - Playing Color: Sets the color of the keys when a track/playlist is playing. See the 'Soundboard' section for instructions on how to set the color.
- Stopped Color: Sets the color of the keys when a track/playlist is not playing. See the 'Soundboard' section for instructions on how to set the color.
Playlists Here you can select which playlists correspond to which column in the Playlist Control screen. Besides that, you can select the play mode (see above) for each playlist individually.
The playlist volume control screen gives control over the volume of the tracks that have been set up in the Playlist Control.
You can enter the playlist volume control by pressing the third function key from the top.
The 8 control keys in the top represent the 8 playlists from the playlist control screen. The fading LED indicates which playlist you are currently controlling, and selecting a different control key will switch the control to the corresponding playlist.
The main keys are again divided into 8 columns, but here each column represents a track, which correspond to 8 tracks in the playlist. The amount of LEDs that are on represents the volume of the track. Pressing any of the keys sets the volume to that level. If a playlist and/or track is playing, the corresponding LEDs will turn green (by default). If there are more than 8 tracks in the playlist, pressing the playlist volume control function key will toggle between up to 4 pages, where each page controls 8 tracks.
You can change the colors of the LEDs in the 'Playlist Configuration', see above.
Below the volume control function key, up to 4 function keys will start blinking or fading, this indicates how many pages are available (determined by the amount of function keys that are lit), and the blinking led indicates on which page you currently are. The volume control function key will also change color to correspond with the selected page.
Note 1: Pressing any of the blinking or fading function keys will take you out of the volume control screen, and into the screen that key is assigned to (for example, pressing the key below the volume control key will open the visual effects control screen). You have to toggle between the pages by pressing the volume control function key (third function key from the top).
Note 2: This page functionality is not shown in the image below.
The visual effects control screen gives you control over certain visual effects. For most of these effects, the FXMaster module is required. The visual effects control has 2 tabs.
You can enter the visual effects control by pressing the fourth function key from the top. Furthermore, you can switch between the two tabs by pressing that key again, changing the color from green (tab 1) to red (tab 2).
There are 3 sections on this tab, separated by empty keys.
- Darkness: On the left, there is a column of greyscale keys. These keys change the darkness level of the current scene, with the brightness of the keys corresponding to the darkness level.
- Color overlay: (FXMaster required) The second section, containing a column of colored keys, creates an overlay of that color. So, pressing the green key gives the scene a green overlay.
- Extended color overlay: (FXMaster required) The third section, containing 3 columns of red, green and blue keys, give further control over these colored overlays. Pressing the main keys in this section set the amount of red, green or blue in the overlay, by pressing the correspondingly colored keys. The 3 control (topmost) keys display this color, and pressing one of those keys clears the overlay.
Tab 2 contains 2 sections, both requiring FXMaster:
- Weather effects: The keys on the left control the FXMaster weather effects. The keys are colored in a way to approximate the weather effect, for example blue for rain, or grey for fog. You can switch on as many of the effects as you like, where fading keys indicate that that effects is on. Pressing one of the red keys in the bottom disables all weather effects.
Available effects:- Leftmost column (top to bottom): Autumn Leaves, Rain, Snow, Snowstorm, Bubbles
- Middle column (top to bottom): Clouds, Embers, Rain without splash, Stars
- Right column (top to bottom): Crows, Bats, Fog, Topdown Rain
- Filters: To the right of the weather effects, there are 4 buttons. They control the FXMaster filters. From the top to the bottom: Underwater Filter, Predator Filter, Old Film Filter and Bloom Filter. Filters that are on are indicated by a fading key. The red key at the bottom disables all filters.
The combat tracker screen gives a rough indication of the initiative order, and it can be used to start or stop the combat and go to the next or previous turn.
You can enter the combat tracker screen by pressing the fifth function key from the top.
The combat tracker can be divided into 2 parts:
The top part gives the initative tracker. If there are tokens in Foundry's combat tracker, these will be displayed on the top rows. The color can be green, yellow or red, indicating a friendly, neutral or hostile token, respectively. Alternatively it can be white, which means that the token has been defeated. Pressing one of these buttons will pan the screen to that token, and select the token. Once combat has started, a fading LED will indicate whose turn it is. If more than 8 tokens are in the combat tracker, they will fill up the rows below. A total of 32 tokens can be displayed.
The bottom part gives 3 control buttons: start/stop combat, previous turn, next turn.
If no tokens are in Foundry's combat tracker, all buttons will fade, indicating that they are inactive.
One one or more tokens are in the combat tracker, the start/stop button will stop fading, indicating that it can be pressed to start the combat.
Once combat has started, all buttons stop fading, and the color of the buttons change. The start/stop button now turns red to indicate that it is now the stop combat button, and the next/previous buttons turn green.
The token health screen gives a rough indication of the relative health of each token in the combat tracker.
You can enter the token health screen by pressing the 6th function button from the top.
Each column, including the control keys, correspond with a token in the combat tracker. They are horizontally ordered by initiative, and colored to indicate hostility, just like the combat tracker. The amount of LEDs that are on, represent the relative health of the token, so an empty bar means the token has 0 health, while a full bar means the token has full health. A blinking column indicates whose turn it is.
If there are more than 8 tokens in the initiative tracker, you can press the same function key again to go to the next 8 tokens, which changes the color of the function key to indicate this. Above the health tracker function key, up to 4 function keys will start blinking or fading, this indicates how many pages are available (determined by the amount of function keys that are lit), and the blinking led indicates on which page you currently are. A total of 32 tokens can be displayed.
Note 1: Pressing any of the blinking or fading function keys will take you out of the health tracker screen, and into the screen that key is assigned to (for example, pressing the key above the health tracker function key will open the combat tracker screen). You have to toggle between the pages by pressing the health tracker function key (6th function key from the top).
Note 2: This page functionality is not shown in the image below.
Note 3: The health tracker might not work in your system. I have confirmed compatibility with DnD5e and pathfinder 2e. If your system isn't compatible, please let me know.
The macroboard allows you to trigger macro's. You can use chat or script macro's, and when you have Advanced Macros installed or you're on Foundry V11, you can use macro arguments.
You can enter the Macroboard by pressing the 7th function button from the top.
Once you've set up the macroboard, pressing a key will trigger the pre-set macro.
The macroboard is set-up in the Macro Configuration screen, which can be found in the module settings.
The screen is divided into boxes, each labeled 'Macro #', where each represents a single sound and its settings. This screen will be refered to as a page.
By pressing the arrows at the top right and top left, you can go to the next or previous page. Macro 1 is the top left main key, Macro 2 is the one to the right of that, etc.
You can set up a total of 256 macros. Since there are only 64 keys on the Launchpad, you have to access the next 64 macros by pressing the 7th Function key from the top.
For each sound there are multiple options:
- Macro: Using the drop-down menu you can select the desired macro
- Macro Arguments: (Advanced Macros or Foundry V11 required) Here you can enter macro arguments, see below.
- Color: This sets the color of the corresponding macro key. See the Soundboard section for information on what the color number represents
At the bottom you have the following buttons:
- Clear Page - Clears all the macros on the current page. Please note that this is irreversible.
- Clear All - Clears all the macros. Please note that this is irreversible.
- Import - Import the macroboard from a file. This will override your current macroboard, and is irreversible.
- Export - Export your macroboard to a file.
When you have Advanced Macros installed or you're on Foundry V11 you can use macro arguments.
Macro Arguments in Foundry V11
In Foundry v11 you enter objects as macro arguments, which can be retrieved in the macro from the scope object, for example, scope.x.
Take the following macro to move the selected token to coordinates x and y:
token.document.update({x: scope.x, y: scope.y})
If you want to call this macro from Material Keys to move the token to x=1000 and y=1500, you'd use the following arguments:
{"x":1000, "y":1500}
Please note that you must include the quotation marks around the object keys.
Macro Arguments using Advanced Macros
Please read the Advanced Macros documentation.
If, for example, you wanted to execute a macro named 'My Macro' with the arguments 'argument1 argument2 argument3', you would use for example /amacro "My Macro" 100 50 "test" in the chat. In the macro configuration screen you would only fill in the arguments, so: 100 50 "test".
The Soundscape function allows you to control the Soundscape module. You can, for example, change the volume of the different channels, mute or solo them, and play sounds from the soundboard.
You enter the Soundscape function by pressing the 8th function button from the top.
There are 4 different pages, which can be accessed using the top-left control keys, from left to right:
- Channel Volume
- Channel Configuration
- Master Volume
- Soundboard
The volume of each channel is represented by the columns on the Launchpad. The amount of Launchpad keys that are lit indicate the volume, and pressing one of the keys changes the volume in Soundscape.
Each channel is represented by a column on the Launchpad. The 4 buttons do the following, from top to bottom:
- Red: Mute channel
- Yellow: Solo channel
- Blue: Link channel
- Green: Channel is playing
Pressing one of these keys applies the corresponding setting in Soundscape.
The left-most column of keys represents the Soundscape master volume. Pressing one of the keys changes the volume accordingly.
The Main Keys section of the Launchpad is divided into 3 parts:
- Top-left 15 keys: These represent the 15 soundboard sounds of Soundscape. Green means there is a sound configured, red means there is no sound configured.
- Top-right key: Pressing this stops all currently playing soundboard sounds.
- Bottom row: These represent the soundboard volume. Pressing one of the keys changes the volume accordingly.
Material Keys has a built-in Launchpad emulator. This emulator has the same buttons as a Launchpad Mini or Launchpad X. It mirrors what is displayed on your physical Launchpad (if there is any connected),
and the buttons can be pressed as if it were a real Launchpad. The emulator does show some extra information, such as sound/macro/playlist/token names. It can be useful as a quick reference, in case you have forgotten
what sounds/playlists/macros you have assigned to the launchpad.
You can access the emulator in the sidebar, under the 'Game Settings'.
Foundry VTT: Tested on V10 and V11
Module Incompatibilities: None known
If you have any suggestions or bugs to report, feel free to contact me on Discord (Cris#6864), or send me an email: cdeenen@outlook.com.
Author: Cristian Deenen (Cris#6864 on Discord)
Abandoned modules are a (potential) problem for Foundry, because users and/or other modules might rely on abandoned modules, which might break in future Foundry updates.
I consider this module abandoned if all of the below cases apply:
- This module/github page has not received any updates in at least 3 months
- I have not posted anything on "the Foundry" and "the League of Extraordinary Foundry VTT Developers" Discord servers in at least 3 months
- I have not responded to emails or PMs on Discord in at least 1 month
- I have not announced a temporary break from development, unless the announced end date of this break has been passed by at least 3 months
I require the "League of Extraordinary Foundry VTT Developers" admins to send me an email 2 weeks before the reassignment takes place, to give me one last chance to prevent the reassignment.
I require to be credited for my work in all future releases.