Debug mode? Text editor?

I’m an experienced programmer but new to Vassal. Does Vassal have a debug mode or any other tools to help with programming that I’m not seeing? It would great to monitor and edit properties in realtime. I’ve resorted to creating “cheat-code” keyboard shortcuts and creating a giant text label that I’m constantly adding and removing $labels$ as I need to monitor them. Is there an easier way?

Also, I’d much rather just use a text editor like Notepad++ than fumble around with the graphical interface. Is that feasible or is the code for the buildfile brittle? i.e. typos completely break modules…

Thanks and sorry if these questions are silly. I’m stumbling around in the dark…

The buildfile is XML, but it’s pretty vile-looking and you won’t be able to reliably do much of anything apart from emergency edits like “I just deleted the Player Sides node which can’t be added back in the Editor and I need to paste it back in from another module’s buildfile”.

There is no debugging mode, so lots of Report traits and text labels to monitor values of things is about the best you can do.

Well at least an XML file means a text editor can be used to search for typos and globally change/rename properties with a search function. It’s also a great way to find duplicates or properties that are accidentally misnamed like “German_Infantry” and “Germany_Infantry”. One of those could take hours to find with the Module Editor. Notepad++ has a great split-screen for comparing two versions of a text document as well. Great for finding new code that broke your program…

Yeah in November I was exactly where you are now. I do use XMLSPY to edit my buildFile and it’s SUPER-useful for “search” and “search/replace” kinds of thing. Also for moving blocks-O-crud around. I do also create scads of Global Properties with it, e.g. when I need three groups of 20 global properties in a particular naming scheme – global properties are safe to copy and duplicate. PIECES unfortunately have pretty hard-to-parse coding, but you CAN do search-and-replace with a reasonable amount of care. One word of warning there can be slight issues if you CREATE new pieces in it (by duplicating other ones) and don’t give them unique gpid’s – it will eventually straighten itself out but if you just avoid creating new pieces that way you’ll be… safer. BTW the buildFile, if you haven’t found it, is inside your VMOD file which is actually literally just a ZIP file renamed to the VMOD file extension – so just get 7Zip or whatever and you can pop your buildFile out to scrud around with.

Meanwhile you’ve obviously discovered “lots of text labels”. I will also insert “Report” traits in various places to see if triggers are firing or what they think is in the properties at the time they’re hitting or not hitting their matching expression.

FINALLY, since you say experienced programmer – Vassal IS an open-source Java project, and so if you want to REALLY “dive into the abyss”, you can get Eclipse running (e.g. is only slightly out of date) pull down the Vassal source for 3.2.17, and go to town. As in ALL THE THINGS – breakpoints, what’s happening in expressions, etc, etc. But it does mean you’re debugging the java source for the whole platform, and so there’s a certain amount of drinking-from-the-firehose when all you really want to know is “did this global property get set to 1 or not”. It’s a deep deep rabbit hole, but I followed it and it led to… goodness.

I have a custom “chat” class for the chat window, and I’ve started to experiment with “console-style” commands for it (e.g. “/force chatter height 160”). I’m toying with setting it up to let me query & set properties and stuff on the chat line. When I start to get a feel for “how long it’s going to be until Vassal 4” that will probably nudge me toward either getting that all nice and set up or else writing some similar thing for Vassal 4… soooo many rabbit holes.


No, that’s pretty much it. I’ve considered writing some sort of debug mode at different times over the years, but the Vassal security model is also brittle, to say the least, and it would just open up too big a can of worms.

Yep. The buildfile is xml and can be manipulated with xml tools or standard text editors without too much problem. Gross edits like cutting and pasting lines is ok, as is the search and replace of obvious text strings like command names and image file names.

However, the data within some of the xml values representing piece definitions and the like is not designed to be edited externally and is EXTREMELY brittle. Save often.

Debugging Vassal takes me back to the days when I programmed in FORTRAN. Symbolic debuggers to me are life itself. I have not done what Cattlesquat has done (Eclipse) because I know I’ll just start fixing bugs, and those days are behind me. Anyway, here’s some things I do:

The Inventory window can be very helpful in dumping properties en masse, especially for pieces that seem to have vanished.

Sometimes I will create a special piece whose only job is to tell me its X and Y location via the text trait. It can be very helpful laying out orderly and precise “send to” locations. This is more a layout feature than a debugging one.

You can add a report trait to any piece that is linked to a key code (e.g. control-alt-F1) that has no function in the piece. It won’t show up in the right click menu, but if you select the piece and hit the key code anyways, the piece will spill its guts, i.e. print everything you put in the report string in the chat window. It’s a nice way to see the properties it sees at any time.

Thanks for the tip on the report trait. That is going to be very useful.

Haha! I started programming with FORTRAN 90, unless you count BASIC on my Atari. Yeah five years ago I fell down the rabbit hole of trying to debug TripleA, another Java-based tabletop boardgame engine for Axis&Allies style games. Never again. I hate trying to work on other people’s code. I’m a perfectionist to a fault - I even fix blank lines and uneven spacing or tabs. I compulsively start reorganizing hierarchies so everything is orderly and I’ll rewrite code that works because inefficiency drives me nuts. Best not to even know it exists or I’ll lie awake at night wanting to fix something I saw that was poorly written…

Wait, what??

You are going to love working on Vassal - there is a whole lot to fix for perfectionists, including reorganization, refactoring, blank lines, we got rid of uneven spacing and tabs but there will be a lot of work now fixing the other formatting issues, we use the checkstyle plugin which reports them so they are easy to find and fix. And the best part is that your PRs get accepted sooner or later and it becomes YOUR code and not other peoples code anymore.

Look at the latest build log for instance, all these warnings starting at line … 53491#L556 need fixing, and once these are fixed we will enable the next set of warnings that will need fixing.

Yeah we need you in here m3tan!

Sometimes I will create a special piece whose only job is to tell me its X and Y location via the text trait.

Hey this sounds great, any pointer on how that is done?

Sure. I create an at-start stack in my target window with one piece. It’s traits are does-not-stack and text. The text trait is ($CurrentX$,$CurrentY$). When I drag the piece around, it reports its current pixel location. Make sure the text is big enough to see. Delete when done.

Sadly the ship has sailed on me being a full-time Vassal programmer. I had a lot of free time thanks to lockdown, but my work schedule is basically back to normal again. I’ll still contribute as time permits but my module still isn’t quite finished and now I’ve probably got 5 hours/week for Vassal instead of 5 hours/day.

One programming trick I employ is using asterisks () to comment out expressions. It’s quick but also highly visible at a glance - asterisks stick out like a sore thumb. So I’ve created a “Debug” Prototype for all my pieces that contains a Text Label that “spills its guts”. The prototype is everywhere but its default name in each piece is Debug. When I need it, I just remove the * from the name. When I’m done with it, I add back the *. Super useful. At some point, I’d like to think that my module is so perfect that I can permanently delete my Debug prototype, but it’s probably there forever…