Strategic Primer exploration program user’s guide

In running a turn of Strategic Primer, one of the most time-consuming tasks is generating what an explorer has seen, and updating the player’s map with new information. To make this burden lighter, I’ve developed several programs to automate the most tedious parts of the procedure. And today, documentation of the current generation of exploration programs.

There are two, one a command-line program and the other a graphical interface. Each is similar in use to the other: the user selects which player to consider, and which unit to use as an explorer, and enters how many “movement points” that unit has, and then guides the unit around the map until either the movement points run out or the user decides to stop.

To start either application, pass “-x” or “–explore” (without the quotes, of course) as a command-line option; an additional “-g” or “–gui” (which is the default, and so can be omitted) will produce the graphical application, while a “-c” or “–cli” will invoke the command-line application. (If both are specified, whichever is last on the command line will take precedence.) The other way to get at the command-line version is to specify “-c” or “–cli” as the sole option (other than any necessary filenames, etc.), in which case the “app chooser” will present a menu of all the command-line interfaces available. (As of this writing, and on my laptop, exploration is number 6, but I wouldn’t trust that not to change from computer to computer or at least OS to OS, or as apps are added or removed.)

Both the graphical and the command-line applications require at least one argument, the main or “master” map file, and as many player or “subordinate” maps as the user chooses. All of these maps will be updated with the selected unit’s movement (so, again, I strongly recommend only running any of my apps on map files kept under version control, just in case I’ve missed a data-destroying bug), and “subordinate” maps will have the things the explorer sees added to them. If there aren’t enough file names passed on the command line to the graphical version, it will prompt the user to select the master map; the command line version will simply print a brief usage message and exit. Note also that a bug, which I uncovered and fixed while preparing this post, causes all currently released versions of the suite of “helper apps” to crash if no subordinate maps are specified; an easy workaround, if only one map file is available, is to create a copy of it or a hard link to it and use that as a second filename on the command line.

From there on the applications’ usage is superficially different, so I’ll begin with the command-line version. It will prompt the user to choose a player, from a list of the players that all the loaded maps know about. If there is only one such player, the app will choose him or her automatically. Then the app will prompt the user to choose one of that player’s units, from a list of all of his or her units in the master map. (At any such prompt, entering a negative number or a number greater than the largest choice should take the user back to the previous prompt or quietly exit the application entirely.) The user is then prompted for the number of movement points the unit has—I have a table I look this up in based on the unit’s “speed per round,” and while I could add that calculation to the program, leaving it as-is offers flexibility for things like partial turns.

From there, the user is repeatedly prompted for which direction the unit should go next. Each direction (of the eight cardinal directions) is indicated by a digit, as are “Stay here” and “Quit.”

If it’s possible for the unit to move in the selected direction, the unit moves, the cost of doing so is calculated and deducted from the running total of movement points remaining, and “tile fixtures” on the new tile that the unit notices are selected and added to the “subordinate” maps. Mountains, rivers, hills, forests, and the player’s own fortresses are always noticed, and to those is added one fixture selected at random from the remaining fixtures except for unexposed ground, which is never noticed. If the unit was told to “stay here,” the app asks if the user wants to swear any villages on the tile to the current player’s service—which costs 5 movement points and currently ignores previous commitments.

When the unit’s movement points are exhausted, or the user has selected “Quit” instead of a direction, all the maps are written back out to disk.

first screen of interfaceThe graphical application works similarly. At first, it presents the user with a list of players and a list (initially empty) of that player’s units. Once a player has been selected, the player’s units appear in the list. The user selects one of them, enters the unit’s movement point total in the text box in the lower right, and presses the “Start exploring!” button.

That replaces the lists with an array representing the tile the explorer is currently on and the eight tiles surrounding it. Each tile is represented by a “visual tile” and a list of fixtures to its right and left. The “visual tile” is visually divided in half diagonally; its upper or left half shows the tile on the main or “master” map, and its lower or right half shows the tile on the first “subordinate” map. The left list shows the fixtures on the tile in the main map, and the right list shows the fixtures the first “subordinate” map has on the tile.

expl_2After every move, in addition to updating the text at the top of the window to indicate the explorer’s current position, the program automatically selects fixtures in any of the left lists (or perhaps any of the lists), using the same algorithm as the command-line program uses to determine what an explorer has seen: all the terrain, and one other fixture at random. Then, when the user clicks on one of the tiles (the “visual tile”), the explorer moves to that tile and the selected fixtures are copied to the “subordinate” maps. This roundabout procedure allows the user to change the selection, if something came up but wouldn’t realistically be seen, or didn’t and would always be seen. “Moving” to the same tile, as with the command-line program, allows the unit to see more and shifts the allegiance of any villages on the tile.

Like the command-line program, this graphical application keeps a running total of remaining movement points, in the upper right corner. Unlike the command-line program, however, it does nothing when the counter reaches zero—notably, the user must save the maps using the menu, because it is not done automatically. And unlike the command-line program, the graphical application permits the user to switch to following a different explorer: clicking the “Select a different explorer” button in the upper left corner brings the user back to the first screen, showing the list of players and the list of units.

All that remains to tell, I think, is the menu. It contains commands for loading a different “main” map or additional “secondary” maps, saving the current “main” map under its original filename or a new one, and saving all the maps under their original names. If the user wants a wider view of a map, the next two commands will open the main map and the first “secondary” map in the map viewer application. Following that are commands to close this window—which will leave any map viewer windows open—and to quit the program—which will close all windows launched from this one.

If you use this program and run into any problems, please report them either in the issue tracker or by contacting me directly.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s