Strategic Primer Worker Management User’s Guide

Last week’s release of my suite of assistive programs for players and Judges of Strategic Primer included a new “worker management” application. This post is a basic “user’s guide” describing how to use this program, along the lines of the guide to the map viewer.

First, let’s go over installation again. The entire suite, including the new “worker management app,” the map viewer, and all the other programs, is packaged as one “app,” which you can download (in either a platform-neutral “JAR” or a bundled form specific to your platform—but see footnote 1 below) at the Bitbucket downloads page. Each file name begins with viewer and then includes the version number; you’ll almost always want the latest version, but to use the worker management program you’ll need a version greater than or equal to 0.4.2243. Put this file wherever you like (unpacking if necessary—see footnote 2); you can run it from anywhere.

The app chooser window including the worker management appBecause this is a “suite” packaged as a single program, when you run it you will see an “app chooser.” (You can bypass this by specifying command-line options; see footnote 3.) To open the worker management program, the topic of this documentation, click the “Unit Orders and Worker Management” button.

The file-chooser windowAt this point you’ll be prompted to select the map file to open. (You can bypass this, too, by specifying the file on the command line.) It’ll probably take a few moments to read the file and launch the “app,” so be patient.

The worker management app as it first appearsAfter those few moments, the worker management window will open. It’s divided into two probably-uneven columns. While the right side will most likely seem to dominate the window, let’s ignore it for now and come back to it later. Instead, we’ll start with the left column.

In the upper left corner of the window is a “tree” consisting of the units belonging to the “current player” in the map file and the “members” of those units. You won’t see any of the unit members at first; click the icon to the left of one of the units to “expand” it and reveal the unit members. For workers—which most unit members are likely to be—any Job levels are indicated in parentheses after the worker’s name.

The worker management app with a few units expandedThere are several things you can do here. First, you can drag and drop members from unit to unit. And second, if you right click on a unit, a worker, or another “member” for which this even makes sense, you can change its name or its “kind.” (In the case of workers, “kind” means race—human, elf, etc., human if not specified.)

Immediately below the “tree” of units is an “Add New Unit” button. Pressing this brings up a small window that prompts you for the unit’s name and “kind.” If you enter something in both of these fields and click “OK” (or press “Enter” while in one of the fields), the new unit will be added to the map file, and to the tree. This lets you organize the workers (and other “members”) into more units than before.

And below that button is a text area labeled “Orders for current selection”. If a unit is currently selected in the tree, the “orders” associated with it—which can be arbitrary text (except that angle brackets and ampersands are likely to trip up the program if you try to save the map file afterwards)—are displayed in this text area. You can edit them as you see fit. If you click “Revert,” the text will revert to the value currently stored with the unit; if you click “Apply”, the text currently in the area will be saved with the unit. (Note that if you don’t click “Apply”, changes won’t be saved, and will be lost when you select something else in the tree.)

Now is a good time to mention the right-hand column. At the top, it’s labeled “A report on everything except your units and fortresses, for reference”. And that label is accurate. In previous development update blog posts I’ve mentioned the “report generator,” which I’ve also used to create reports that I then sent to all the players in my campaign. This is almost exactly the same report. But it omits all fortresses (because at this point in the campaign there’s only one; by the time there are more I expect I’ll have made the tree include them too) and units (because they’re already displayed in the tree to the left) owned by “the current player,” the player whose units and workers are displayed in the tree.

This report includes everything else in the map file (i.e. everything else you the player know about): other players’ units and fortresses, independent cities and towns, minerals, orchards, meadows, animal sightings, villages, and so on. I decided to display this information because in creating orders for his or her units, a player would most likely want to refer to the report.

The last piece of the main interface is the button in the lower left corner. It’s labeled “Export a proto-strategy from units’ orders.” When you click this button, you’ll be prompted for a file to write to. When the process finishes—it should be very quick—the file will contain the beginnings of a “strategy,” consisting of the header (player name and turn number … provided the latter has been kept up to date), a placeholder for the “inventions” section of the strategy, and lastly the units and their orders. The units are organized into sections based on their “kind”—when I did the initial organization after adding support for workers to the data model underlying these programs, I put, for example, the farmers into separate units if they were working different farms, but labeled each one’s “kind” as “agriculture”. Each unit has its workers listed (you’ll want to word-wrap the list, preferably preserving the indentation, as my players have seen me do in the “results” documents I’ve sent them, because this program doesn’t do any such formatting yet), and then prints either the orders you’ve entered or (if you haven’t given any for that unit) the word “TODO” as a placeholder.

I call it a “proto-strategy” because it’s certainly not ready to submit in the form the program produces. (See also the “strategy checklist” I wrote last year.) But this program is intended to simplify the part of creating a strategy that I (in running the “AI players”) have found most tedious and time-consuming, and my players have also complained about.

Returning to this program, for completeness let’s look at the menu bar. There’s only one menu at this point, the “File” menu. There are five items in the menu. “Load” asks you to select another map file, and is supposed to open it in a new window like this one. (I say “is supposed to” because in writing this documentation I discovered it apparently doesn’t, a bug I will be sure to fix before the next release.) “Save” writes the map file out, including any changes you’ve made (moving workers between units, adding orders, and so on), to the file it was loaded from. (Because of the possibility of data loss—which I’ve done my best to prevent, but I’ve made mistakes in the past and can’t control everything—I don’t recommend using this unless the file is under a version control system.) “Save as” writes it to a different file, which it asks you to specify. “Close” closes this window, leaving any others that are open alone, but halting the program if no other windows are open and nothing is running (e.g. no “save” operation is still in process). And “Quit” stops the program entirely (killing any background tasks), closing all windows opened via “Load” in the same session as this window.

If you run into any problems, please report them either in the issue tracker or by contacting me directly. If you’d like to contribute to the development of this suite of programs, please get in touch. And if you’d like to join the campaign of Strategic Primer I’m currently running, please contact me; that would be most welcome news.

Footnote 1: If you’re running Windows, the file ending in .exe should work for you. If you have a Mac and know how to unpack a tarball, try downloading the one with the filename ending in .app.tbz2. (See footnote 2.) I have occasionally had problems with that (in earlier versions …) reported, so if you run into trouble—or on any other platform—use the file with the name ending in .jar instead.

Footnote 2: I’m not developing on a Mac, and a .app is a directory, so I have to put the “Mac app” version in a tarball to upload it to Bitbucket; you’ll have to extract it from the tarball to use it. If that’s beyond you, use the .jar instead. Also, I do provide a DMG, but since I’ve never had a report of that working and can’t test it myself, I don’t recommend trying it (except to help me test and improve it).

Footnote 3: The command-line option -g or --gui indicates that, of a pair of “apps” specified by another option, you want the graphical one; this is the default, and it negates the -c or --cli option that calls for a command-line program. The command-line app paired with this one is the report generator I mentioned above, and either (depending on whether --cli or --gui is active) is invoked using the -w or --worker option.


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 )

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.