Issue 1:
All Deck Key Commands (except for Deck Global Key Commands) are defined inside the Deck itself (i.e. Shuffle, Send to Deck, Reverse). With 3.6, we are looking at adding a Face Up/Face Down Key Command and a Sort Deck Key Command. This is just not sustainable. What if someone wants more than one Sort Deck Command? What if you want to define multiple’ Send Contents to Another Deck’ Commands? What do we do when the next ‘Add a key to do this to the Deck’ comes along?
Issue 2: The definition of the Deck Key Commands are recorded inside the Deck and saved as part of the Save File. They do not respect the current settings in the module. Claudio is working on allowing the Refresh process to update the Deck settings, but I believe it was mistake that these settings where saved with the Deck in the first place. It is the opposite of how all other module components operate.
Proposal 1:
That all future Deck Key Commands be added as Child components of the Deck (like Deck Global Key Commands) AND that the setting of these Key Commands is NOT saved in the Save file, but are taken from the current settings in the module.
Advantages:
Allows for easy addition of new types of Deck Key Commands.
Allows multiple of the same type of Deck Key Commands to be added. i.e. multiple ‘Send Deck Contents to another Deck’ and the new ‘Sort Deck’ Key Commands.
Prevents the need to refresh Decks (using the yet to be written Deck refresh code) to ‘see’ changes in Deck Key Commands in save files and predefined setups.
Simplification of the Deck Configuration
With the new Folder facility, insert/duplicate facility and Drag and drop facility, these will be very easy to setup and maintain.
Disadvantages:
Some Key Commands will be defined inside the Deck, some as Children.
Some Key Commands (the existing ones) will still be saved in Save files. The new ones won’t.
Proposal 2:
That there be an opt-in conversion facility to convert the Key Commands in existing Decks to child Components. By default, new Decks in a module will be created as v2 Decks, existing v1 Decks will continue to work unchanged. When you edit a module for the first time in V3.6+, you will get a Dialog asking ‘Do you want to convert your Decks to the new version? Yes/No/Don’t Ask Again’? There will be a Global Option setting that will allow you to change your mind later if you say ‘Don’t ask Again’.
The Conversion process will do the following:
Extract any existing ‘Send all contents to another Deck’ Key Commands and convert them to child components of their Decks.
Extract any existing ‘Reversible’ Key Commands and convert them to child components of their Decks.
Create a new folder under each Deck in position 1 called ‘Key Commands’ to hold the converted Key Commands.
The Shuffle Key Command will remain in the main Deck Configuration as is it is closely tied to the ‘Reshuffle’ drop-down.
The extracted Send All and Reversible Commands will be changed to reflect the current module contents, NOT anything saved in save games.
Advantages:
Allows existing modules to continue to work unchanged as-is. Change over is completely opt-in by Designer.
Further cleans up the Deck Configurer Dialog.
More consistent - all key Commands (except Shuffle) will now be added as Child components like Deck GKC’s.
Allows a one-off ‘reset’ of all Decks in all save/setup files to match the module.
Disadvantages:
Could cause problems if certain save games or setups contain Key Command settings that no longer match the module AND you want to keep them that way. In that case, do not convert the module.
My 2 cents is mainly that this makes lots of sense from the perspectives of data storage and module extensibility, but that since we already have folks trained to look for most Deck key commands in its configurer, that the “Best of Both Worlds” approach would see most of the key commands detached into sub-component items (as you propose), BUT the bottom of the Deck Configurer would feature a “Dynamic Property” / “Trigger Action” style “add and subtract deck key commands” command center, and that this would allow adding (and removing) key commands of these various sorts right inside the configurer. This would keep the Deck situation more familiar but ALSO make the Deck commands much more discoverable to “aspiring module designers” – I tend to find that subcomponents are easy to forget about or fail to look for if they’re not “added by default” to the module (I was six months into being a VASSAL dev when I realized that [Global Options] could have custom preferences as subcomponents).
I guess my other 1 cent is I can’t think of a use case for not converting the key commands over?
Many years ago when I worked at NASA, I was the sole maintainer of a framework that was much like Vassal and that our entire department used. I reached a point where the framework’s first edition was no longer sustainable, and so I faced the same problems you face. I ended up building a second edition right under their noses, and they were none the wiser. My experience:
I didn’t ask the users if they wanted me to update or not, and I don’t think you should either. Our private-public agreement was that their parts functioned as they always did, and what when on under the hood was not their business. Besides, if you ask if they want the new deck sub-components or not, then you will have a line outside your “office” with people asking what are the upsides and down sides to their choice. And there will be people who are too afraid to check “yes” (the “ani-vaxxers”), which doesn’t help. I don’t think there is any reason not to just go ahead and don’t bother asking. It’s all part of the private agreement.
I think you should deprecate the old methods, which means no one is fixing old code related to them. Convert what you can, but support what you must. I consider what I see on the deck editing window the View, and I would not think it in any way controlled the Model. However, if you want to strip out the changed options on the deck-editing page, I would add a note at the bottom (you’d have plenty of space) that said: “Sort, shuffle, etc are sub-components are this deck. Right-click this deck component to create or edit them.” Again, though, I would probably try to keep the current view and change just the private model if possible.
I suggest you consider that whatever approach you take, it’s a template for how you deal with ALL such changes to Vassal, not just decks.
I am not keen on adding an internal key command configurer to the Deck. It would be a lot of work to go zero additional functionality. Stan’s suggestion of a note directing you to where to add key commands resolves the concern of missing out on seeing Key Commands.
That is my feeling as well, my understanding is that the fact that Decks in save games/setups are unchangeable is actually a problem, not of any benefit.
That chimes with my experience. I would say certainly a problem rather than a benefit, based on a module with 100+ presets and decks with properties that I would like to make very minor changes to.
On the overall proposal, given that existing modules can continue to run with the old deck setup or converted to the new structure, I agree with what Stan said. I’ll try to find some time to start getting involved in v3.6 testing and feedback.
I had a few thoughts with Brent’s initial post and wondered is there really any problem in how decks work?
I too do like removing the control of decks to the module and not leaving them inherent with the deck itself which should help in the whole updating module issues decks pose.
Since Brent is looking to fix this, is it also a good time to perhaps add some common robust features to decks? There are certainly capabilities to do these things in vassal, but it just takes, for lack of a better term, “programming” by the module developer.
i.e:
split a deck in half (or n times) function
deal n cards function
draw x then discard y function
Probably many other functions in card games (based on game) but these are possibly the most common you’ll ever find.
I’m happy to program it myself with protos but shortcut traits sure do save a lot of time
Splitting out functions into Deck Key Commands will make it vastly easier to add new Deck Key Commands that do ‘special Deck related stuff’ without cluttering up the Deck config itself.
One of the aims for 3.6 has been to try and make it simpler to do a lot of the ‘programming’ that designers have been forced to do to overcome the configuration limitations.
For example your ‘deal n cards’ function.
Instead of setting up a Send to Location on each card, then firing off a GKC to the deck specifying apply to ‘n’ card in a given deck,
you would add a ‘Deal from Deck’ Key Command to the Deck that would specify the number of cards to deal (constant or expression), the destination (All of the current Send To Location options) etc. The Cards would not need their own StL traits. The Key Command would be listening for a Global Hotkey, so could be initiated from anywhere.
One thorny problem that one comes across sometimes (as a module designer) is the “Draw 8 Cards” problem – when there are only 4 cards left in the Deck and so the Discard pile is going to need to be reshuffled. Now VASSAL does provide some reshuffle-when-deck-empty automation, BUT because Global Key Commands make their list of pieces before they start trying to apply themselves, what happens is you end up getting the 4 cards from the Deck, and the Discard reshuffles, but you DON’T then get the next 4 cards you need from the new pile. I have gotten around that through a series of little conditionals that check and see if they need to “send another draw cards command”, but it’s conceivable we could now (or eventually) decide to provide that. I guess especially if Deck now has more flavors of subcomponent. But in a way this is more like a “special purpose Deck Global Key Command” that would know to check again automatically after a reshuffle.
A similar/related problem is the “fill to my hand limit” function, e.g. my hand limit is 7 or whatever, and I’m already holding 2 cards, so it could know to get me 5 more (and automatically reshuffle the discard if applicable).
This could easily be handled by a new ‘Deal Cards’ Key Command that also had an option to Select which Deck(s) contains it’s discards and a rule about what to do when running out of cards.
By moving the Deck handling code into a Deck specific component, it should make make development much easier from our end and usage much easier from the designer end.
Hold on a moment. You keep throwing around the term “key command” with respect to decks, and I have a problem with that. Perhaps I have had a major misunderstanding on how things work, and now is a good time to straighten me out.
I believe (according to the docs too) that global key commands are sent to pieces—not decks nor at-start stacks because they aren’t pieces. (And I’m talking programmatically being issued from a piece.) It’s my understanding that the only way my piece can talk to a deck is via the hot key trait. In my world, global key commands attached to decks are almost useless because I can’t get to them.
Ideally I’d like pieces, decks, and at-start stacks to be classes derived from some AbstractPiece class, which would mean each would have its own properties and traits, and in particular, would receive GKCs. Ideally too, I could pass arguments with a GKC much like the usual function calls. Probably too ambitious, so I will leave it with this: Don’t eliminate my piece’s ability to talk to decks.
He means a Key Command that’s “activated by a hotkey” (sort of like Deck Global Key Commands are activated by hotkeys but then they send key commands to pieces e.g. cards).
