V4 Motivation and and Goals

We’re now beginning to publish some design documents for V4, the next major version of Vassal. The text here addresses some high-level questions of motivation and goals.

Why V4?

Vassal 3 has numerous design and architectural problems:

  • Data structures: There are many inappropriate data structures used in V3. To give one example: Piece traits, which are fundamental to the V3 design, are stored and evaluated sequentially as a linear chain. While this performs reasonably for small numbers of traits, it poses a serious performance problem when the number of traits becomes large, as it makes operations on pieces O(n) when they should be O(1). Behavior of traits is determined by their position in the trait sequence, so there is no straightforward way to flatten access to the traits, and the effects traits have on one another is frequently confusing or counterintuitive.

  • File format: The file format used by Vassal to date is XML containing a custom text-based data encoding that was designed to minimize the time spent parsing XML. In the early 1990s, Java’s XML parsing was slow, so this design choice diverted data that would have been XML to Vassal’s data encoding instead. XML parsing is no longer slow, so we’re now left with only the costs of this encoding and none of the benefits. The custom encoding is not human-readable and isn’t decoded by anything other than our own decoder. This makes module construction and maintenance unnecessarily difficult, since one can neither visually survey the contents nor apply standard tools to it. Furthermore, there is a pernicious interaction between piece traits and the data encoding, in that the data from outer traits wraps the data from inner ones—the data is re-encoded at each level, resulting in a quadratic blow-up in size.

  • Entanglement of business logic with the GUI: There is no model-view separation in Vassal, going back to the beginning. The sheer quantity of GUI code entangled with business logic militates against separation at this point.

  • Lack of tests or clear specification for writing any: We frequently find ourselves hesitating about fixing apparent bugs because we cannot conclusively establish what the behavior was supposed to be. We cannot correct bugs or improve code with confidence when there are few unit tests, and we cannot write unit tests when we cannot determine what is correct to begin with.

  • Java idiosyncrasies: Dealing with Java’s idiosyncrasies has historically consumed a shocking amount of development time for us. Some of these, such as users’ travails with installing the JVM and an assortment of JDK bugs, we’ve overcome after great effort; others, such as heap sizing, appear to be evergreen.

  • Decrepit ecosystem: Swing, the GUI toolkit used by Vassal 3, is effectively dead. Desktop Java is moribund and mobile Java has never existed. It’s increasingly difficult to find anybody who wants to contribute to an open-source Java project.

While none of these problems are individually insurmountable, the combination of them makes significant further progress on V3 untenable. Unpicking the Gordian knot is not the solution here. What is of value from V3 is the module library and our deep experience with the problem space—those are the things to take forward, not the V3 codebase.

This is why we are writing V4, rather than continuing to modify V3.


Some of our goals for V4 address the roadblocks we’ve hit with V3:

  • Human-readable file format, modifiable by standard tools: The new file format will be text-based and thus diffable and usefully storable under version control. This will make direct examination of it it a text editor possible and fruitful, which will aid in module creation and debugging, as well as facilitating creation and modification of modules via scripting and other command-line tools.

  • Transparent ontology which does not commit us to unperformant data structures: Properties of game objects will be flat, and thus directly accessible, rather than nested; we need not recreate the awkward representations which were tacked on to V3 over the years.

  • Separation between the model and view: It’s a fundamental principle of software architecture that display of data is not mixed with handling of data; keeping the two separate expedites development in every way.

  • A specification and unit tests: Tests eliminate bugs before they’re released, save development time, and head off user anguish. Changes to code can happen with confidence only when there are sufficient tests to demonstrate correct behavior. External-facing parts of V4 must have a specification so their behavior can be relied upon.

  • Development in a language ecosystem which isn’t dying: We aim to use languages and libraries which appear healthy, in order that we benefit from their ongoing development and support for years to come.

Some of our goals for V4 go beyond the limitations of V3:

  • Clients for all platforms, including mobile devices: There’s great demand for boardgames on all devices these days, and on some types of devices which didn’t exist when Vassal began; we aim to produce an app that may be run anywhere.

  • A security model providing guarantees: Some gaming scenarios—e.g., tournaments—require a trusted third party for dice rolling and management of secret information. We aim to provide those in V4.

  • Modern UI: We aim to have an aesthetically pleasing user interface, with smooth zooming, panning, and rotation.

  • Simplified module design and scripting: Module scripting should be direct, simple, and require no compilation. Module design should not require bizarre contortions to achieve seemingly straightforward things.

  • Support for more modes of play: We aim for notification-based asynchronous play to join live play and PBEM as options for playing games.

  • Conversion of existing modules: We will provide a converter for V3 modules so they may be used with the new format, insofar as that is possible.

See V4 Architecture for an overview of the V4 architecture.


So with making traits O(1), I assume you will be moving the traits to a hash data structure. I guess they will be keyed by things like the hotkey and menu key and things like that. So traits will be stored in multiple ways?

From the editor’s view, I’m guessing it will look the same but just order no longer matters?

But now you’ll have to detect and break loops somehow?

Great design goals, but a comment on the above…

One thing that I hate about modern “apps” is how smartphone/tablet limitations dumb down desktop programs and UIs. This is often driven by either laziness/resource-constraints on the part of the developers or the (IMHO incorrect) view that identical UIs on very different devices is preferable to taking advantage of the unique capabilities of each.

All of my Vassal gaming is on a PC. In the future, I could see possibly doing 5% on a tablet (e.g., on vacation), and none (ever!) on a smartphone.

I like my file bar at the top. I like the PC optimized UI.

Please don’t dumb down the UI to make it “friendly” to tiny screens.

PS - rotation is iffy IMHO, possibly introducing more problems than it’s worth (i.e., keep orientation of counters while board rotates?). If done, probably work an option to lock it out. Related observation - Table Top Simulator - physics based gaming application - horrible and the physics based approach actively detracts from it’s utility and fun of use.

My opinion, FWIW…

Thanks for all the work on V3 and V4!


Due to my horrible eyesight, I pushed (strongly) to get the ability to increase font size in V3 and rejoiced (angels sang) when it got implemented.

I strongly urge that the V4 design goal should include one for usability and visual impairments. Font sizes, magnifying options, color blind setting, etc. Toolbar text, map text, help text, counter labels, etc.


I agree with @Korval (although my dislike for apps “dumbed down” to fit on a phone may be less intense). I’m sure there are some modules of games with a small table presence that would be fine for play on a phone, but I’m not visualizing that for the 18xx module I am developing.

Although I have no experience with Table Top Simulator, I have played some on Tabletopia. I too find the 3D physics, like objects bouncing and tipping over, to very distracting from the play experience.

I also want to thank the VASSAL team for their efforts with making V3 more usable and the development of V4. I appreciate the vision and goals for V4. As one who is helping with play testing a prototype and building a module to help with further play testing, the goal of making the game log human readable looks wonderfully awesome.

Thanks again!

Yes, the idea is to have by-name property access.

I expect that it would be convenient for a piece editor to show a list of traits, similar to how traits are displayed now.

I don’t follow. What loops there would be to detect or break?

What if you have a trigger A that calls B, and B calls A?

I expect we will build in some sort of infinite loop detection and reporting wherever it is a possibility.

1 Like

wrt the build.xml file, could you share a snippet of the before and after? Just to get a feel of what you think the new serialization will look like? Stuffing nested properties into attributes was certainly a mistake but some extra eyes on the replacement can’t hurt.

A comment on some of the the goals which I appreciate and agree to most enthusiastically.

I love the idea of separating the model and the view. Currently I am trying to write an AI client (or at least rules-based), and there is a need for the module and game state model, but no need for the view.

Separating the model and view also makes it easier for non-graphic clients and multiple platform view clients. No one cares if you are on desktop, mobile, assistive device, or other to interact with the game. Think of all the chess notations where any web, desktop, or other client can read the game state, and provide an input to the next move.

Unit tests will not only help you maintain and progress the system, but it will also show new contributors what the patterns are for making certain things happen in the system.

Other goals such as making more human readable configuration and scripting are welcome!

1 Like

That will be coming in the next few documents, possibly the one after what I’m working on presently.

1 Like

Would this include the ability to play a VASSAL module asynchronously via a web browser, and not having to have VASSAL downloaded onto the machine displaying the web browser? (I’m hoping the answer is “YES!”)

I seriously doubt it and while I (in theory) like the idea, it opens up a host of problems.

  1. A machine has to be running both a web server and vassal continually
  2. Web servers open up all kinds of cyber attack vectors

So you either have your personal computer potentially vulnerable (which probably has stuff you don’t want compromised (e.g., banking info))


Someone stands up a commercial service (Vassal as a service). And then the lawyers get involved, game publishers expect cuts of profits, etc. etc. Lawsuits, cease and desist orders, etc. Death knell of Vassal as a not-for-profit hobby open-source project.

I can’t follow the reasoning here—why a web server would be required, what that has to do with security of your own system, or why the alternative is a commercial service followed by legal action. I suspect we’re not thinking of the same thing at all.


Maybe I’m confused, but if you wanted a web browser to access a Vassal instance running on the internet, doesn’t that imply web server functionality either integrated directly into Vassal or a separate web server that allows access to a separate Vassal instance?

In order to access it asynchronously (per the original post), it has to be running for long periods of time, rather than for the short and coordinated Vassal-to-Vassal sessions as is done now…

Anyway, that was what I was thinking… Maybe, I’m totally off-base…

Possibly the V4 Architecture document I just posted will clarify.

I don’t foresee any of the components being web servers. It would be awkward to use a web server for any of them. Web services don’t have much in common with a general purpose web server beyond using HTTP as a communications protocol.

As for what needs to be running—it’s not much different from now. The public game server for V3 needs to be running continuously, as does the web site if anyone is going to download anything from it.