v3.3.3-beta1 - MacOS keyboard style & conflicts

In my testing, it soon became apparent that adopting the command key (⌘) instead of control as the primary key modifier on MacOS creates more potential for key conflict for Mac users. Users will notice a conflicts whenever a Command key fails to trap as expected on a map and falls through to the main Vassal engine. The issue can be looked at from the Module Player and Editor viewpoints.

Module Player
The following keys are operational during normal module use and these are common to the equivalent functions in other MacOS apps.
⌘, - Preferences
⌘H - Hide Current Vassal Window
⌥⌘H - Hide Other Vassal Windows
⌘Q - Quit the module

Of these probably ⌘H is the main likely conflict. It is likely to be a common key in wargame modules (H being short for “Hit”).

I looked into GIMP for an example of how such conflicts might be handled. GIMP uses one of the above keys within the Apps; ⌘, GIMP therefore has no shortcut for Preferences. Therefore, one idea I suggest is that the shortcuts are disabled for the Hide Window functions, at least on MacOS.

Module Editor:
Users of the Module Editor are affected by a much longer list of command keys-
⌘X - Cut
⌘C -Copy
⌘V - Paste
⌘M - Move
⌘P - Properties
⌘T - Translate
⌘S - Save
⌘A - Save As…
This may result in unexpected effect such as the Save As… dialogue, perhaps also undesirable effect like a Cut of a module component (not sure, as I haven’t checked whether this can actually happen). Possibly awareness will be enough to deal with this issue for module editor users. However, I wonder if there is another solution.

When the input focus is active on a map attached to the main window, any keys that are not trapped by the module will get passed up to the main window; Text appears in the chat window, the commands available from the main window will be processed.

So one solution to command key conflicts, whilst maintaining compatibility with the earlier Vassal UI, would be to filter all non-text characters whilst allowing text (including Delete and Return) to be passed through. Possibly ALT/Option keys should also be filtered, or recommend that Vassal modules avoid using these.

I don’t really understand why this was done. Macs has a CTRL key and could do keyboard shortcuts. The Command key would match the Windows/META key. I’ve never had a problem pressing CTRL+something for VASSAL commands.

Disabling Command+H for Hide Application because it may be used inside a module as CTRL+H is just… dumb. This makes VASSAL worse on Mac imo.

Did this stem from the change related to adding/removing from selections? Or is it a distinct change unrelated to that one?

MacOS is dumb. This was changed so that Vassal uses the Mac keyboard in a Mac-standard way, where Control is not Control but Command.

There is also a user preference that lets the user change it back to how it was before.

This is exactly why we put the preference in to allow Mac users to opt for the “old vassal” (non-standard Mac) configuration.

I certainly don’t recommend blocking the normal behavior of Command H just because a module “might” use it.

There will of course be an issue when a module designer (on some other platform) has put something of common use on that key, not thinking about the Mac implications. I suppose we could put in some kind of sneaky workaround (like Control + Command will ALSO perform those keystrokes) for Mac users who would like to use the “normal(ish)” Mac interface but have to content with non-Mac-friendly module key assignments.


So it’s a change out of spite?

VASSAL is not using shortcuts for menu items but custom commands in a custom way. Macs are perfectly capable of distinguishing between CTRL and CMD as observed by all previous VASSAL versions. It just means with every new user I introduce to VASSAL I have to first instruct them to turn off this new feature so the UI is consistent. Every Windows module designer won’t know or care and every Mac user of this module will be confused why all the help files tell them to press CTRL+something and it doesn’t work.

Some wonderful great new features announced for v3.3.3, but I am at a total loss to understand why this change is needed or how it will improve anything.

PS I understand the CTRL+click for contextual menu is an issue for Mac users that still operate a single mouse button, and that this may then conflict with the selection toggle, so that key is moved to Command. But that doesn’t mean all contextual menu items and key commands need to be translated to the Command key – there is no conflict there except for a mouse-click + CTRL modifier action button trait or something. And these “standard” Command-based keyboard shortcuts resolve from menu items in the menubar, which the VASSAL commands are not (standard macOS does not use keyboard shortcuts in contextual menus).

Thus spake bdgza:

[This message has been edited.]

“Flint1b” wrote:

MacOS is dumb. This was changed so that Vassal uses the Mac keyboard
in a Mac-standard way, where Control is not Control but Command.

So it’s a change out of spite?

Argh. No, it’s not.

The point of the change is to make VASSAL running on a Mac behave as
other apps on a Mac do.


The reasons for the change were, in no particular order:

  • To bring Vassal into line with the Apple-recommended way of presenting shortcut keys on the Mac, which is indeed in line with the way most Mac apps are designed/created and therefore what most Mac users are normally used to.
  • When we upgraded Java versions (a matter of somewhat existential importance) we discovered that Java in the meantime has become less cooperative with some of our old interface shenanigans. We aren’t an island unto ourselves - we exist in a sea of libraries and JDKs that we depend on, so there is definitely a pull to “get in line” with the way the rest of our world is going.
  • We want Vassal to remain attractive to new users, and that includes in particular new users on Macs, and moving in the direction of a more standard Mac interface is one of the ways to accomplish that – presenting a less “alien” interface to Mac users trying it for the first time.

All of that being said, we were entirely aware that long-time users may well want to keep the old “not Mac approved” interface and we certainly made a commitment to keep it available.

If you’re a non-Mac user designing modules that Mac users also play, the best, most platform-independent-minded thing you can do is probably to move away from Ctrl+H, Ctrl+Q, and Ctrl+, as keyboard shortcuts. Being platform independent and supporting several platforms well is not without its sacrifices – believe me we’re extra extra familiar with THAT proposition. But obviously the alternative of using the “Legacy Mac” preference is also available.



I am also a cross-platform developer. I don’t agree with the argument that doing this change makes VASSAL easier for beginning Mac users is a good enough one. Yes, it would be nice if VASSAL is less alien, welcoming, etc., but it needs to be done from the ground up as part of the design, not patched on top at this stage. Dialogs don’t respond to Return and Esc for default and cancel, Mac menus don’t actually have standard keyboard combos like Command-N for new game or Command-O for Open Module. Swapping some keys around isn’t going to magically solve the alien-ness of VASSAL.

The technical argument is weak imo. Are Java apps going to not be allowed to listen for the key presses they want? If the JDK or dependencies forced this change then you wouldn’t be able to still offer the “legacy” option to keep it as it is. You think this will be broken in a Java update and legacy will stop working?

This change breaks so many things for very little (if any) gain. Things that have worked well (enough) for all these years are thrown into turmoil and could break existing modules. Like every other module designer I have used CTRL+H in all modules. I quote: “designing modules that Mac users also play”; aren’t all modules supposed to work on all platforms? Are we going to have a bunch of modules that only work on a certain platform? “This module works best on Windows”

I find the user preference itself confusing, it does not make it clear what the true implications of this setting are. I also think this should be two options:

  1. Use Legacy Mac mouse mappings (for Contextual menus and piece selection)
  2. User original module keyboard shortcuts (don’t auto-map CTRL to Command)

I am sure that a lot of work went into this, and that there were good intentions, but the more I look into this the more I am convinced this is not a good idea to be patched in like this, and should be reserved for a completely new / breaking version like VASSAL 4. The contextual menu switch fix: good; using Command instead of Control for piece selection: fine; Auto-mapping CTRL to Command where it was not intended: bad.

And I will keep telling the other Vassal devs to stop supporting MacOS altogether, kick every line of Mac-specific code out of the codebase, stop building MacOS installers. The MacOS users are a small minority of all Vassal users. They can just download the “other” release, install Java on their own, and run the .jar file.

As a member of that minority, I trust those other Vassal devs to defend us from your personal Jihad, the implications of which for fragmentation and holding module development back seem obvious to me (until such time as Mac users are completely expunged, of course).

I try to stay out of platform debates and it would help focus the point of this thread if antipathy to the platform could be expressed elsewhere.

A bdgza points out, there are two distinct changes here and they need addressing separately. I was surprised to find the two changes tied together in one option setting and I am ok with the idea of separate options. I would ask first though, should using the Legacy Mac mouse mappings be seen as an option or a bug-fix? Unlike keyboard mappings, which can be a style and usability debate, the left-click and related select issues are integral to how a Mac user will be interacting when using a single-button mouse - and (I suspect, much more common) a MacBook or other trackpad user, with no mouse at all. In which case, should there be an option for the mouse mapping change… the affected users should be helped by this fix, what are the downsides ?

I will contribute my new thoughts on the other change in a separate reply.

Thus spake Flint1b:

And I will keep telling the other Vassal devs to stop supporting MacOS
altogether, kick every line of Mac-specific code out of the codebase,
stop building MacOS installers. The MacOS users are a small minority of
all Vassal users. They can just download the “other” release, install
Java on their own, and run the .jar file.

He’s not going to convince me on this point. It’s important that we
follow native conventions as much as possible. We’re not changing that.
That won’t change in V4, either.


Concerning the control/command keyboard shortcut option, thinking about the replies and giving some more thoughts as a Mac user, this is a bit long, so I hope it is helpful. I am not addressing any underlying technical drivers of the change, such as Brian referred to. Parts 1 & 2 of my contribution, will be moot, depending on the outcome against Part 3.

1) Why would a Mac user want this change? These are not game changing reasons but from the user viewpoint there are reasons worth considering, and that may be more significant than one might think…
a) It is commonplace for applications to follow the Apple style guide and give priority to the Command key in places that Windows would give it to the Control key. Speaking as a Mac user that has crossed from PC to Mac to PC and back again, you soon develop a, preference for command as a modifier key. Even though I have been using Vassal always on Mac, I still find myself occasionally going for the command key.
b) The most common Apple Mac keyboard is probably that found on the MacBook. It has two command keys and one (smaller) control key. Based on key size alone, it is 3x easier to use a Command+ combo than Control+ Even the Option key has more real-estate.
c) Some Mac users will not be so affected either way, if like me they tend to use the right-click drop-downs instead of shortcuts. In many game modules, I am not sure it makes much difference to efficiency (usually).

2. Legacy
The preference option should be for users to decide; the underlying purpose of the change is in doubt (as in fact, it is) if module developers feel the need to dictate the preference setting for their module. However, I can understand that it adds a complication to support - “OK, you’re using a Mac… now what is your preference for Command over Control?”. Hmmm… there is a conflict between flexibility/user acceptance and long-term support complications. Should there even be a Preference option and should it be permanent or a transition option to be removed after due warning?

The legacy option aside, the module will auto-configure to hint the relevant platform shortcut. Module documentation, at most, just needs to mention that Mac users can read “Control” as “Command” and vice-versa. At best, a list of key commands would include a column for Mac and other, but this is not necessary. Many Mac users will be well aware of the issue, as they have probably used apps on PCs as well. Is there something else that a module developer really needs to concern themselves about ? Apart from…

3. Key Conflict
This is where I started and it remains the main issue so far for me (along with other user-impact issues). Bdgza’s points about design from the ground up seem to broaden the issue, perhaps to a level that can’t be resolved in a point release, as in fact he argues, but for now I keep to the more obvious (to me) aspects.

As I tried using v3.3.3 during the course of yesterday it became apparent that this is even more of a problem that I thought. Command-keys were being passed through to the Vassal level, even if actioned by the module (apologies if this is just an issue with my module, as I don’t understand enough about what the system is doing to know what is expected behaviour or not). So for example, Command-H would apply a hit and, sure enough, hide the vassal window. Not helpful. And sorry, Brian, I agree with bdzga, “reprimanding” module developers (I’m being light-hearted) is not the way forward. As bdzga confirmed, Control/H will be very commonly used; it is logical that it would be - wargames produce Hits. If you consider for a moment the implications of changing this in one commonly used module, it is bad enough. Suddenly a key must change, and people who have been using that key for years must now remember to use a different one, and for what? That is a price too high (and that’s from a supporter of this change).

Now consider that a module developer shares the vision of this change and thinks about persuading their users to make the switch. But wait! That same community also uses 3+ other modules for a wargame in the same series. Naturally, though the modules have had different developers at different times, the developers have followed the same pattern, by design or by the magic of “H”, those other modules also use CTRL/H. So now the developer is going to ask the users to use a different key in one module in the series? Or is going to ask to change all the modules? One such series is Commands & Colors, a popular collection of modules. I won’t be pursuing that line.

It is very unlucky that Command-H is such a key conflict. The few others will only be apparent during module editing or are uncommon enough (probably) to be tolerable.

Which is why I came up with the “dumb” idea to displace the system level default for Command-H. Dumb it may be, but I got the idea from GIMP, which does it for Command-, . Looking at the idea dispassionately, it depends largely on how many Mac users have a habit of needing to hide their Vassal window with a key press (Vassal @ Work, maybe??!). Speaking only for myself, I didn’t even appreciate that that function was there, but then I tend to use the mouse and would hide windows that way. And it depends on whether those same Mac users would value the Command-key change more… because unless the change can address this key conflict then I do not think it is feasible. The value of the change diminishes rapidly as soon as significant modules in the catalogue actually require that users are in “legacy” mode. Speaking as one such user, I would not want to be changing my preferences between modules; it is one-time, all or nothing.

So here is my conclusion based on key conflicts alone, either
A) A solution to key conflict is found, at minimum to avoid the conflict with Command-H. Without a solution to this, a Preference option helps not a bit.


B) Accept that Vassal on Mac is indeed, again as bdgza suggests, a different world. Leave well alone, for now at least.

Option B is not so crazy as it might first seem to the dyed-in-the-wool Mac user. In fact, Vassal IS a different world. It is different from many applications because it allows the module developer free rein to re-define the operation of any and all keyboard press combinations. This is potentially far more intrusive than a common-or-garden app that might allow the user to (re)define some macro keys (incidentally, user-controlled, whereas Vassal modules are controlled by a third-party and effectively pre-defined once they reach the user). Maybe good practice for a module developer is to limit use of the Command key (ie META) and thereby reserve it to the Vassal level. This avoids such conflicts, on Mac at least. One nagging doubt; how have the other platforms avoided key conflicts like this, when Control is the preferred modifier on those platforms?

Thank you for reading, if you got this far.

I appreciate all the recent contributions–genuinely I do. But this bit right here is pure lunacy (and flatly wrong).

A Mac preference to allow Vassal to override the conflicting system keys is. An avenue worth exploring.

I want the preference to be to disable the new mapping and have VASSAL function as it did <= 3.3.2. If the user chooses to have the mappings enabled they can include the conflict overrides also – why would the user want to choose settings that cause problems? But the entire CTRL->Command, with or without overrides for standard Mac shortcuts, should be possible to disable.

If the “legacy” mouse is also offered as an option (instead of as a standard fix) it should be a separate preference from the key remapping preference.

We have mentioned CTRL-H → Command-H for Hide Application, but what about modules that use CTRL-Q → Command-Q and Quit VASSAL?

Isn’t CTRL-Q the Quit module Vassal shortcut on a PC ? And, presuming so, would that be a reason to believe that CTRL-Q is not used by module developers as a general rule?

CTRL-Q does nothing for VASSAL on Windows (unless mean Linux?). But Alt+F4 would quit VASSAL on Windows, and this is an accepted keyboard combo for Mac module designers.

I think it would definitely be worthwhile to put some thought into this moving to VASSAL 4, to exclude certain keyboard combinations that are problematic for Windows / Linux / macOS.