JV_Map Manual

JV_Map version 0.10.6

JV_Map home page: http://www.pobox.com/~rknop/jv_map.



JV_Map is a PBEM wargame aid written in Java 1.1. It was written to be compatable with V_Map and (as of this writing) supports VMP version 1.5 and 2.0 files. (Support of the 2.0 file spec isn't complete as of yet.)

PBEM Wargaming

People who play wargames and microgames are few enough that you may not be able to find opponents locally. The internet has proved a great way to communicate with people all aroud the world, and to bring together widely separated people with common interests. It is only natural to seek wargame opponents on the net. After all, people have been playing chess by mail for years; playing games by E-mail can only be faster, since (barring certain specific ISPs and mail hosts) E-mail arrives within seconds or minutes, rather than the days it takes standard mail to arrive.

You could send your moves back and forth entirely by text. Indicate which pieces are moving, and to which board positions (either by hex number, or by assigning a grid to the board). Players at either end could each keep a board with the current game configuration. However, things are much more convenient if you have a virtual game board on your computer, and can send the actual board across E-mail to your opponent. That way, they can immediately look and see where the pieces are; they don't have to interpret a lot of moves and numbers. Also, there is no danger of a mistaken or dropped move meaning that the two players have their boards out of sync.

In principle, you could use a paint or draw program, sending the graphic files back and forth (assuming you could agree on a format). However, those data files tend to be large, and it is a waste of bandwidth and space to send these huge image files back and forth when really the information needed is much more compact (i.e. the positions of some tends of counters on a board).

Programs like JV_Map provide the missing link. They give you a game board, and the ability to move counters back on the game board. The moves in the game are sent back and forth as very small text files. Because they're plain text, every E-mail reader can handle them (although many still find it convenient to send the files as attachments). Send your normal communication back and forth in E-mail, just as if you were talking. When somebody needs to look at the board to make a decision, whoever last moved the counters around can send a copy of the board state (this small text file) to the other person.

Why Java?

When I first started getting into microgames in the last couple of years, naturally I looked for a way of playing them via E-mail. I found that there were several free and commercial programs for Windows out there that served this function, but none for Linux (my OS of choice). Being a programmer, I resolved to write my own. I decided to write it in Java, so that in principle the program would work anywhere Java does. (This means that I would also incidentally be providing a PBEM Wargame aid for Mac users in addition to Unix users such as myself.) Fortunately, Todd Zircher got wind of my project soon, and convinced me to make the program compatable with his V_Map. The compatability between the two programs effectively provides a wider audience for JV_Map. I didn't have to convince other people to install Java on their machines; if they had windows, they could use V_Map while I used JV_Map.

When I first started writing JV_Map, there wasn't a stable Java 1.2 availble for Linux. Although there is now, MacOS 9 still only supports Java 1.1. Although I'd love to use Swing and some of the other features of the Java 2 platform, I will strive to keep JV_Map compatable with Java 1.1 as long as Java 2 is not widely availble on the Mac.

Note that JV_Map will not run within a browser. It is not a Java applet, it's a full Java application. As such, to use it, you need a Java runtime environment on our machine.

JV_Map Features

Missing Features

Notice the 0 at the beginning of the version number.... There are some things that I mean for JV_Map to support, but which it doesn't yet.

Future Directions

For the most part, I'm pretty satisifed with JV_Map for what it is. I want to fix up the missing features, but it's quite usable right now. However, I'd eventually like to take JV_Map to the next level. Some thoughts of where I think I'll be going with this:

Running JV_Map

(To be written. In the mean time, see the JV_Map installation web page.

The Main JV_Map Window

The main JV_Map window shows information about the current game that the program is running, and gives you the controls for loading, saving, and setting up the game.

Game Information

At the top of the main JV_Map window (beneath the menu bar) is some general information about the game running.


The name of the game. This is just a title, which is for your convenience. It will be saved with VMP 2.0 files, but will not be saved in VMP 1.5 files. Depending on your Java implementation, the game name may also appear in the title bar of your window.


This is always blank with the current version of JV_Map! However, future versions will allow you to indicate which player you are. (JV_Map does know about counter ownership. Right now, all counters created will be owned by player 0, the GM. However, in the future, counters you create will be tagged as owned by you.)


The filename of the last VMP file to which this game was saved, or from which this game was loaded.


The directory where the filename is located. This is only important because the image files (the image for the maps and counter set) must be in the same directory as a VMP file for the program to be able to find them when it loads that file.


This is a list of maps in the current game. When you first load a game, all of these maps will be displayed. If you close a map window, the map doesn't dissapear; it is just hidden. You can reshow it by clicking on either the "Show All" button, or by selecting that map from the list and clicking on the "Show" button. Most of the rest of the buttons are self-explanitory.

The "Add" and "Edit" buttons open the "Edit Map" window:

With this window, you can change the image, title, and other parameters of the map. For the image, you can load a GIF, JPEG, or BMP image. (If your opponent is using V_Map, you should use BMP images.) The image must be in the same directory as the VMP file; otherwise, if you later try to load the VMP file into JV_Map, it won't be able to find the images.

The x0 and y0 parameters specify the position of the top left corner of the map, in pixels. (I think it's top left!) These are not used internally by the program at all, but may be useful for you to keep track of which maps are positioned relative to which other maps in games where you have multiple maps that lay next to each other. Future versions of JV_Map may use this information.

If you are adding a new map, you will also have the opportunity to specify the number of this map. Usually the default will be fine. Map numbers must be unique within a game.


This is a list of the players in the game. The e-mail address appears in angle brackets. Player 0 is a special player: this is the GM of the game. If your game does not have a GM, then there should be no player 0.

At the moment, JV_Map doesn't do much with the players. In the future, it will keep track of the players, will allow for player passwords, will have the option of only letting players move their own counters, and may even have encrypted counters so that only the player may see the "real" value of his own counters.

Clicking "Add" or "Edit" brings up the "Edit Player" window:

This window's function is pretty obvious. If you select "Add" rather than "Edit", you will also have a wiget in which to indicate the player's number. Usually the default is fine. Player numbers must be unique within a game.

Tiles Set

At the very bottom of the main JV_Map window is the image name for the tiles set (or counter set), and an indication of the number of counters in the set (columns x rows). To add or chnage a counter set, click the "Change" button.

Menu Commands on the Main JV_Map Window

The Map Window

This is where the main action happens. The map window has the map image, with scroll bars that let you move around the image. Sitting on the map are the counters of the game. You can add counters, remove counters, exchange counters, and, of course, move counters.

Moving Counters

It's real easy. Just move the mouse pointer over the counter you want to move. Press and hold the left mouse button. Drag the counter to where you want it to go. Release the left mouse button.

Please avoid use of the cupholder on your computer during this operation.

Counter Popups

Use the "standard popup trigger" on your machine while the pointer is over a counter to get a list of actions you can perform on that counter. On Linux, this means press and hold the right mouse button. I have no idea what this means on other systems; it's a Java thing. Because I don't want to count on every system having a "standard popup trigger," you can also get the popup menu by holding down the shift key while pressing and holding the left mouse button.


You will probably never use this. When you select it, the counter is tied to the mouse pointer. Move the mouse to where you want the thing to go, and click the left button to put it down. It's probably easier to just drag the counters around without using this menu item.


In JV_Map and V_Map, it's standard to assume that the even numbered counters (i.e. the 2nd, 4th, 6th, etc. on each row) are the backs of the odd numbered counters. In some counter sets, this will not be the case. However, for instance, with the Ogre/GEV counter set, every other counter is a disabled version of the counter to the left. This menu item just flips back and forth between the two ajacent counters, meaning that it's just a "flip" for those counter sets where the even counters are the backs of the odd counters.


This is how you exchange a counter for a different counter. You will be presented with a window showing all the counters in the tiles set for the game. Click on the one that you wish to replace the counter whose popup menu you opened, or click "Cancel" to keep the current counter.

Push to Bottom

Move this counter down underneath all of the other counters. (This is useful when counters are stacked on top of each other.)

Bring to Top

Move this counter on top of all of the other counters.


Remove the counter from the board. Deleted counters are gone for good; however, you can always add a new counter of the same type. The counter comment of a deleted counter will be lost.

Counter Comments

At the bottom of the popup menu is either the text "(Add Comment)" or the comment for this counter. Select this item to edit the comment. This is just a text string associated with the counter. Use it to store the name of the counter, or notes about the counter, or just ignore it if you don't care.

Adding Counters

To add a counter, hold down the shift key and the left mouse button (or use the "standard popup trigger" for your platform, e.g. the right mouse button on Linux) over a blank area of the map. (By blank, I mean where there are no counters. JV_Map just displays an image, it doesn't know anything about terrian or other features on the map itself.) You will get a popup menu with a handful of choices, one of which is "Add Counter". Select that, and a window opens with all of the counter images for the current game. Click on the desired counter image, and a counter with that image will be added to the map at the position where your mouse was when you opened the popup menu.

You can have multiple counters with the same image; JV_Map does not keep track of the number of counters of each type in a given counter set. It's up to you to make sure you aren't adding more counters of a given type than is allowed by the game's rules.


It may from time to time happen that the map image gets screwed up. Usually, this indicates a bug in JV_Map, although it just might be a bug in Java. If things are looking screwy, from the popup menu you can get off of the map (as opposed to off of the counters), there is "Redraw" option that should fix things. I've noted, for instance, that if you try to run JV_Map with Kaffe, the map isn't drawn when its window is first opened; a quick Redraw fixes that. Also, some earlier versions of JV_Map suffered from dissapearing counters. If you scrolled the window around, sometimes when a region of the map scrolled onto the screen the counters there wouldn't be displayed. I think this bug is gone, but if you see it, or if you are just worried, a quick Redraw fixes the problem.

JV_Map Dice

JV_Map has a built in die roller which is capable of generating random numbers that simulate the rolls of all sorts of dice. It can E-mail the results of these rolls to all the players (or to anybody else). This way, you don't have to believe your opponent when he tells you what the rolls were; JV_Map can send him a copy of the rolls at the same time you see them.

Why Not to Use It

Because it's far too easy to cheat. Yeah, because it E-mails the rolls out, you can't just keep rerolling until you get something you like. Your opponent will see all of the rerolls. However, think about it: if you want to cheat, all you have to do is write an E-mail message that looks exactly like the message that JV_Map sends.

OK, you say, why don't you just embed some sort of PGP signature into the messages, so you can be sure that the program generated the numbers? In that case, all that one has to do to cheat is to modify the program's generation of the numbers to generate the numbers it wants. If the key is embedded and capable of signing random output, it will still sign whatever output a hacked version of the program will write.

The only really good way to roll dice in PBEM wargames is to use an authenticated third-party dice server such as the one at PBM.com or Irony Games. These will send E-mail to all recepients, and what's more are signed with a PGP key you can use to verify that the mail came from where it claimed to come from. Because you don't have access to that key, you can't put a signature on bad rolls, as you would be able to if the key were embedded in a program such as JV_Map running on your computer.

All of that being said, if you trust your opponent, it can be really convenient just to use the JV_Map die roller and get it over with. And, in the end, a lot of games implicitly require you to trust your opponent anyway. For example, if counters move upside down, and the counter set has blank backs of counters, you have to trust your opponent not to peek. (Future versions of JV_Map may prevent your opponent from peeking, but at the moment there is no technical restriction on it.)

Rolling Dice

Select "Roll Dice" from the "Tools" menu on the main window, and you will see:

This window lets you roll handfulls of dice multiple times.

Indicate what the rolls are for, one line per roll, in the big text area. When you're done, click "Roll 'Em" at the bottom of the screen. You'll get a result window something like:

E-mailing Results

If you select the "E-mail roll results?" checkbox, then JV_Map will attempt to mail the exact text of the results to the people you indicate.

SMTP Server

This is your outgoing mail server. Give it the same name that you gave to your mail client when you set that up. You can avoid typing this every time by creating a file ".jvmaprc" in your home directory and adding a line "rknop.jvmap.smtpserver=servername" to that file.

NOTE for AOL users: AOL has its own proprietary E-mail system. It doesn't use SMTP, which is the recognized internet standard for E-mail. (This might also explain why you can't use anything but the AOL-supplied E-mail client, if you've ever tried that.) It must have SMTP translation somewhere, since AOL users can send mail to the rest of the internet, but it doesn't have SMTP servers available to its users. This means that if you are on AOL, you will unfortunately not be able to send JV_Map's dice out via E-mail, unless you find another SMTP server out there on the net which will let AOL users connect to it and use it. (I don't know of any such servers.)


The port on which your SMTP server is running mail services. This will almost always be 25. You can configure it by setting "rknop.jvmap.smtpport=port" in your .jvmaprc file.

Your E-mail

This is whom the E-mail messages sent by JV_Map will appear to be from. You can configure this by setting "rknop.jvmap.email=email" in your .jvmaprc file.


The subject line of the E-mail message to send


Recepients must be standard E-mail addresses; normal names with e-mail addresses in angle brackets won't work. Each recipient address must be on its own line.