Vassal V3.5.5
The documentation for Vassal states that the order of Startup GKC execution is “undefined” and recommends that only a single Startup GKC is defined. From my own blundering around I might be able to augment this advice slightly (on the other hand I could be totally off-base… caveat emptor).
The following does seem to work - whether it is useful or not, I leave to you to evaluate for your own application (for me, it is to be able to warn the user if they join a game that is based on a back-level version of the module - one that pre-dates any startup GKC logic) :
a) A Startup GKC positioned higher in the module seems to execute first, consistently. This is where I place the call-out to the piece with the startup logic. Bear in mind, as with other GKCs, the Startup GKC report will be issued before the Startup GKC logic runs.
b) A second or third GKC can follow; that is, at least to generate a report &/or Alerts that depends on the logic from the above Startup GKC. Such “report” GKCs can be defined with no command or search logic.
Remember that Startup GKCs execute for all players, both when starting a new game, opening a scenario or log file or joining an online game. Therefore, a typical startup will include an execute-once check - this will be executed by the Player who started the game/opened the scenario (which might be useful information, e.g. if you wish to limit certain actions to this player).
Apart from compatibility checking, here are some others uses that I have found for a startup GKC:–
-
Setting Global Options boolean preferences to their defined default.
I defined some boolean (checkbox) Global Options to allow users to customise the module UI to their preference. I soon found that first time users were not getting the Global Option set as expected, no matter what the default is. Once they manually set it, all was good. This startup component runs for all users and sets each preference (“pref”) as pref!=false or pref!=true, depending on what the desired default is (true and false, respectively). Once this runs, the defaults behave as expected. You might want to test for yourself if this is really needed and, if it was a Vassal bug, it may be fixed already. -
Setting Global Properties to their initial scenario startup values (One time)
Vassal can not reset Global Properties for pre-defined scenario files (it doesn’t know whether the pre-set scenario has correctly changed the GP or not). By incorporating GP initialisation into startup, you will be able to change the GP during module development and subsequent runs of the scenario file will pick up the new value. Either put all your “at scenario start” GPs into this routine or simply migrate each across when it becomes necessary. -
A “welcome” alert or other advisory messaging can be hooked off the Startup GKC.
Provide a Global Option user preference to allow the user to disable any alerts that they no longer need -
Tracking players joining a game (though in practice, I have used a more explicit player action - clicking on a “take seat” icon of some kind)
I have used this to set a “Side” icon with the player name… when the player joins directly in a player role.
Remember of course, players may join a game as , so whatever such side-based automation you do in startup will need an equivalent within the game (integration with the Side Switch Global Hotkey is a possible solution). -
Patching a scenario (One-Time, or as a special to work through scenario updates)
I’ve not done much of this yet but it could be used to amend scenario files rather than laboriously amending and re-saving the originals.
Hope this helps someone or perhaps generates some Startup GKC discussion for my education!