The difference between Global Key Commands and Global Hotkeys
VASSAL has two seemingly overlapping technologies: Global Key Commands (GKCs) and Global Hotkeys (GHs). As you might have already discovered they are used similarly but the objects the effect are different: GKCs effect game pieces, and GHs effect interface elements, such as toolbar buttons. In effect, a GH simulates you typing the hotkey that activates a toolbar button, enabling you to automate UI elements in your game.
GKCs on the other hand, are similarly used to automate game functions but they target game pieces.
So if you want to automate a UI element that contains a Hotkey: use a GH. If you want to automate a game piece: use a GKC.
Example Use: rolling for possible leader casualty
In the module I’ll use as an example, Red Badge of Courage - a US Civil War regiment-level game, certain fire combat results may trigger the need to check whether a leader has been killed as a result of combat. Instead of rolling the die, checking the result, and if the leaders is killed, manually moving the leader counter to the dead leader box on another map - I would like to automate this as a function of all leaders in the game. A small but helpful addition.
Steps
- Add a unique die for our function.
Although this is not necessary, I want to have a special die that is rolled only for Leader Casualty rolls. I will configure it with no button name - so that it is hidden and therefore won’t be added to the toolbar and won’t be used for anything other than my automated functions.
So this creates a new Dice Button that can be accessed globally by the name, LeaderLoss. It has no button text and no icon and so won’t be added to the toolbar. It rolls a single die with results between 0-9. It can be activated by any player typing Ctrl+Shift+G at any time. The Report format specifies what is written into the chat window using properties: $Piece_Name$ expands into the name of the current piece that activated the die roll, $name$ is the name of the dice (LeaderLoss) and $result$ is the total of the dice rolled (only one die in this case - if you had multiple dice the outcomes of the individual dice would be stored as $result1$, $result2$, etc…).
You can test this works by typing the hotkey.
- Use Trigger Action to provide a menu item on the game piece (or prototype) that can then spawn multiple consequences.
I have a “Leader” prototype that all of the individual leaders in the game are given. I’m adding this function into that prototype so all leaders will have access to it.
The description is just for me to spot it in the editor window. I have no match properties I want to filter on - I want the trigger to always activate. The Menu Command is the name that appears on the counter’s pop-up menu and the hotkey to activate the trigger is Ctrl+Shift+Q - so if I select a leader counter on the map and type the hotkey it will activate the trigger. At the moment, my trigger only has a single consequence - it performs the Key Command: rollLeaderCasualty - remember Key Commands trigger functions for pieces - since this is not a “Global” Key Command - it will trigger other functions in the triggering piece only. I use a trigger function because I often want to enact multiple consequences to one command and this allows me to sequence them as I need them to be sequenced - for example a Report Action that happens before the die roll (drum roll), then the die roll, then a Report Action after the die roll (sound of guillotine blade crashing down). Report Actions can be helpful when tracking down why a function doesn’t work.
I’m not using the Also Watch section - but this is very handy for having multiple entry points into the action you want. That way you can have a central Trigger that doesn’t have any menu item itself but is triggered by other actions and the hotkeys / key commands they generate.
- Use a Global Hotkey to roll the dice.
Again, description is solely for me to sort out my game piece elements. There is no menu command so this won’t appear in the pop-up menu on the game pieces. The Key Command is the same one I specified in the Trigger Action. And the Global Hotkey is the same one for the Dice Button we created first.
Putting it all together
Here’s the pop-up menu on my leaders:
And here’s the outcome when I choose the menu item:
Next installment: How to take the dice result and choose what effect to have on a unit.