-
-
Notifications
You must be signed in to change notification settings - Fork 20
Getting Started
Material Deck (MD) works by connecting Foundry VTT to a Stream Deck (SD). It is required that you install the module in Foundry, install the SD software, install the SD plugin, and start the sdServer. Instruction on the installation can be found Instructions can be found here.
Communication between Foundry and the SD goes through websockets. Websocket is a communication protocol that allows fast bi-directional data transfer between connected devices. To do this, there needs to be a websocket server, which can then connect to multiple clients. Since both Foundry and the SD plugin are not able to host a server, it is necessary to run a separate server application.
In the SD software, you are able to assign actions to the SD buttons. The actions for MD are provided by the plugin, which, when installed, show up on the right side, under the Material Deck category. You can drag one of these actions to a specific SD button. Selecting the button in the software opens the property inspector (PI) in the lower left part of the SD software, which will load the configuration for the selected action (loading the configuration can take some time, so please be patient). Using this configuration you can configure the button to do what you want. Details on how to configure the various MD actions can be found here.
Once everything is installed, and the server is running, the communication goes as follows:
-If, in the SD software, a new action is assigned, an action is removed, an action is moved to a different key, or a configuration is changed, the SD sends a message to Foundry. Foundry has a buffer that stores the data for each button that has been assigned in the SD software. This buffer is updated with the new information. Foundry also checks if data needs to be send back to the SD, for example images, text, or background colors. If so, it will send this data, and the SD updates the button.
-If a SD button is pressed, the SD sends a message to Foundry, specifying a keyUp or keyDown event, and the selected action. Foundry then performs the required action.
-If things change in Foundry (such as the initative order, a token's icon or name, etc), Foundry checks the buffer if there is a relevant action assigned to a SD button. If so, it will send the newly updated data to the SD, which then updates the button.
With everything installed, you can start assigning actions to SD buttons. The actions for MD are provided by the plugin, which, when installed, show up on the right side of the SD software, under the Material Deck category. You can drag one of these actions to a specific SD button. Selecting the button in the software opens the property inspector (PI) in the lower left part of the SD software, which will load the configuration for the selected action (loading the configuration can take some time, so please be patient). Using this configuration you can configure the button to do what you want. Details on how to configure the various MD actions can be found here.
Besides Material Deck specific actions, you could also add other actions, just have a look through the different actions, and you can install more by pressing the 'More Actions' button on the lower right or by manually installing them if you find plugins on the internet. The actions you will probably want to look at are the 'Create Folder' and 'Switch Profile' actions. With the 'Create Folder' action, you can a button to open a folder, this folder can then contain different actions, allowing you to set up different screens, such as a combat tracker screen, or a playlist control screen. Using the 'Switch Profile' action, you can do similar things, but you'll be changing profiles.
You can delete actions by selecting them and pressing the delete key, or by pressing the trash can in the upper right in the property inspector. Another useful thing is that you can copy and paste actions (and their configuration) by right clicking the button in the SD software and clicking copy or paste (or use the CTRL+C and CTRL+V hotkeys).
Text that is assigned by Foundry, such as track names, can be problematic due to their length. The module automatically tries to split text up into multiple lines at spaces, but right now it will not split long words (this will change in the future). Long words or long sentences might not properly show up on the display. It is advisable to change the names of things like tracks, in order for them to display properly.
Not all image formats are (currently) supported. The following formats are supported:
- jpg/jpeg
- png
- svg
- webp Right now, the path to the icon is not allowed to contain '?' (except when it's directly after the format), and the file name must end with its format, unless the format is followed by a '?', as is the case with icons made with tokenizer.
Many of the MD actions will assign text to the buttons. Some have the option to specify whether you want to do this (such as the Playlist action), but in any case, it is possible to assign your own text. You do this by selecting the button, which opens the property inspector. You can write anything you want in the 'Title' field. You can press 'Enter' on your keyboard to write multi-line text
The module will only send the text itself to the SD. You can customize it further by pressing the icon on the right of the 'Title' field in the property inspector (T with a downwards pointing arrow). Here you can find various options.
Many of the MD actions will assign icons to the buttons. Some have the option to specify whether you want to do this (such as the Playlist action), but in any case, it is possible to assign your own icon. You can do this by pressing the downward arrow on the icon box in the left part of the property inspector, or by right clicking the icon box. You'll have the option to set the icon from a file, creating a new icon (which redirects you to the Stream Deck Key Creator, or setting it back to the default icon.
Various actions have default icons assigned to them (such as the 'Playlist'action, when set to 'Stop All'). Besides changing the icon on a button-by-button basis, as described above, you can change the default icon. The icons are stored in the MD plugin folder.
In windows: %appdata%\Elgato\StreamDeck\Plugins\com.cdeenen.materialdeck.sdPlugin\action\images
In macOS: ~/Library/Application Support/com.elgato.StreamDeck/Plugins/com.cdeenen.materialdeck.sdPlugin/action/images