MC2S Utility Site

News - Help - Downloads - Mercator's Civilization 2 Site

CivSprite Readme

CivSwap by Mercator

Last Changed: 2 April 2005

Introduction

CivSwap is a program that can keep track of the turn of an ongoing Civilization II game by monitoring the game's autosave. More importantly, it can then launch a specified program or batch file on set turns. Such a batch file can then be used, for example, to swap a scenario's events or graphics.

File swapping has been used before in Civilization II scenarios, but until now, the scenario player had to interrupt his game to run a batch file. CivSwap automates this process, leaving the scenario player nothing to do but reload the latest (auto)save.

This documentation is strictly meant for scenario makers who want to use the CivSwap functionality. In other words, do not include this readme with your scenarios! CivSwap is supposed to make things easier for the players, not harder by making them read lengthy technical discussions. However, I will give some pointers as to what you, the scenario maker, can mention in your scenario's documentation to explain the players what they need to do to make it work. I will conclude this readme with an elaborate example.

To be complete, here's a list of all the files included in this package:

CivSwap.exe
The swapping program, to be included with your scenarios.
readme.html
This readme, the CivSwap documentation.
example\Choice.com
A file commonly needed to make batch files work correctly on Windows XP.
example\Delevent.exe
Program to delete events from savegames, this would have come with Civilization II already, but just to be sure.
example\Setup.bat
Setup batch file for the Imperium Romanum CivSwap example.

Thanks for using CivSwap!

Overview

As I said before, CivSwap makes things easier for the scenario player. This does not mean it also gets any easier for the scenario maker. If you already have trouble enough making batch files, you will probably want to get in touch with your local Civilization II batch-file guru (i.e. the Apolyton forums).

Basics

I have already described most of what CivSwap can do, but not yet how it does it or what you need to do to make it work. Let me get right to it.

CivSwap is basically a sentient program that runs in the background while you're playing a scenario. When it's running, it continuously checks the scenario game turn by reading the latest autosave. If the game turn matches with one in the CivSwap INI file, the specified program is run.

This means two things. First of all, CivSwap must be run everytime the scenario is played. If CivSwap isn't running, it can't do any checking. Secondly, the Civilization II autosave feature must be turned on. Without autosaves, CivSwap doesn't have anything to check. Both of these are mostly scenario player issues, so I will address them in my notes on the scenario documentation.

At least two files are needed to make CivSwap work. To be precise, those are CivSwap.exe and CivSwap.ini. Both of these must be located in the scenario folder. So that means you will need to include them with your scenario. Other than these two files, you will also need a batch file or possibly a Windows scripting file, or whatever else you fancy.

CivSwap only keeps track of game turns and doesn't actually do any swapping in itself. It can, however, run programs that do. Furthermore, CivSwap is not limited to use with batch files, nor is it limited to just swapping files. It will basically work with anything you can type in at a command prompt, whether that be DOS or the Windows Run... item in the start menu. For the sake of simplicity I will limit myself to file-swapping batch files.

Settings

At the root of CivSwap's functionality is the CivSwap INI file. It consists of a single section named [Turns] with a list of turns and their commands to run. Let me give an example to make this more clear. This is what a typical CivSwap INI file might look like:

[Turns]
15=swap.bat 15
39=swap.bat 39 $AUTOSAVE
74=swap.bat 74 $AUTOSAVE

The structure should be quite clear. The turn number is followed by an equals sign and then the command that will be executed. So, at the beginning of the human player's turn 15, the hypothetical swap.bat batch file will be run with one command-line argument, and so on.

The second thing to note is the $AUTOSAVE at the end of the last two lines. This is is a CivSwap variable and will be replaced by the name of the autosave file. This allows you to make changes to the savegame. For instance, if you swap events files, the old events have to be cleared from the savegame using Delevent. To automate that in a batch file, you need the name of the savegame. The $AUTOSAVE variable gives this name to you.

That is all there is to know about CivSwap and its INI file. Everything else is taken care of in the (batch) files you specified in the turn commands. I will discuss batch files in further detail when I come to the Imperium Romanum example.

Finally, note that you can change the name of the CivSwap executable, if you wish to do so. But if you do, the name of the INI file must change accordingly. The name CivSwap will still be used within the program, though, particularly as the window title.

Documentation

Not all of you may be equally comfortable trying to explain a utility like this to the players of your scenario. Even if you are, I'll help you out a little. Not only for your benefit, of course, but also my own. I'd rather not have scenario makers and players constantly knocking on my door to ask me questions about this. So I expect you to be able to help along the players of your scenario, at least until you've exhausted my suggestions.

And just in case you forgot. I would highly appreciate my name being mentioned in your scenario credits. If you're really thankful, you could include a link to my website as well (either http://civ2.mercator.fastmail.fm/ or http://civ2.mercator.fastmail.fm/mapedit/ will do). I'd rather not have my e-mail address mentioned.

Scenario Readme

The description of the use of CivSwap will be most critical in your readme. That's where the players will be looking first. I'll give a nice example quote you could put straight in your readme. It may not be entirely applicable or suitable, but you can adjust it as you see fit:

This scenario has multiple events and uses CivSwap to automate the file switching process. To make this work there are two things you must do: (1) Start the CivSwap program in this scenario's folder before every time you play this scenario. A tiny window will appear in the top right-hand corner of your screen. (2) Turn on the Civ2 autosave feature. CivSwap will monitor the autosave while you are playing to check when the file switching needs to happen. When the time comes, all you have to do is load a new savegame as specified in the text pop-up.

In case you have problems running CivSwap and get any errors, you are likely missing the Visual Basic 6.0 SP5 run-time files. They are available at both the Microsoft website (http://www.microsoft.com/downloads/details.aspx?FamilyID=bf9a24f9-b5c5-48f4-8edd-cdf2d29a79d5&DisplayLang=en) and Mercator's Civilization2 Utility Site (http://civ2.mercator.fastmail.fm/mapedit/).

If you think that lengthy Microsoft link is a little too cumbersome, you can use this link instead: http://www.microsoft.com/downloads/ and search using the keyword "vbrun60sp5". Note that the text pop-up I mentioned in my little quote refers to a text event in the events file. That's something you have to add yourself. CivSwap doesn't give any kind of message.

Scenario Introduction Text

There's nothing particularly exciting to mention here. But it would be wise to remind the players once more to start CivSwap and turn on autosaving. Not to mention they had better read the scenario's documentation.

Text Events

This is the last place that needs a mention of the effects of CivSwap, very much like what you would need to add if you were using the old-fashioned way of file-swapping. This is the place where the advantage of CivSwap finally kicks in. Add a nice little text event at the turn of swapping with the instructions to load whichever savegame it is they need to load, depending on what you're actually letting CivSwap do in the INI file. That savegame would either be the autosave or, much better, a copy of that autosave with a specific, unique name and the events deleted (if applicable). But that's a batch file matter.

Troubleshooting

In my little scenario readme excerpt I limited myself to mentioning the Visual Basic run-time files, because those are the files most likely causing any problems. However, the problems don't quite stop at that. I'll give a little rundown of any other problems people might be facing with CivSwap. These issues should be very rare, but I'm just preparing you for the odd scenario player who does encounter them. If, and only if, none of these suggestions work, you can feel free to pass the problem to me:

An Example: Imperium Romanum

To give you an idea what can be done with CivSwap and batch files, I've prepared an example based on Bernd Brosing's excellent scenario Imperium Romanum. Specifically, it's written for the English language version 2.2. I don't know if it works with any other versions. You can find it at the following locations:

Funnily enough, BeBro's own Civilization II scenario site, doesn't seem to have the latest version.

To add the CivSwap functionality to Imperium Romanum, copy both CivSwap.exe and SETUP.BAT (from the CivSwap example folder) to the scenario folder. Run this setup and follow the instructions. You will not need the original setup batch files that came with the scenario.

Now, to see what this batch file does, open SETUP.BAT in NotePad. I will go through it step by step, though not explaining every single line. Most of my notes will be pointers for batch file usage, but some will be more specific about the interaction with CivSwap. Here we go...

Step by Step

@ECHO OFF

This line turns off the command-line output for the rest of the batch file. Without this line, you would actually see all the batch file code as it is being run. Handy when you're debugging perhaps, but not a pretty sight for normal use. The echo is really only turned off after this line though. The @ at the beginning suppresses the echo of this one first line as well.

NOTE: DOS commands are case-insensitive. ECHO or echo, it's all the same.

if "%1"=="rome"      goto Rome

This line consists of two commands: if and goto. The result should be quite self-explanatory. If the comparison holds true, batch file execution will jump to the Rome batch file label. Labels are lines marked with a colon. You'll find the :Rome line further down this batch file. On the other hand, if the condition is not met, execution simply continues with the next line.

Secondly, the %1 is a variable that refers to the first command-line argument. Similarly, %0 is the full path to the batch file itself, while %2 through %9 refer to the second through ninth command-line arguments. So, if this batch file was called with rome as its first argument, we'll skip straight to the Rome label. You'll find out later what that's all about.

NOTE: You can get help on most DOS commands by using the /? command-line switch. Typing in if /? at the DOS prompt, for instance, will give you an explanation of what if does.

cls

Clears the command screen.

echo.
echo IMPERIUM ROMANUM V 2.2

These two lines nicely demonstrate the other use of the echo command. It simply prints out whatever comes after it. To print an empty line on the screen you must use echo., however. If you left out the dot, it would actually turn command-line output back on (what we just turned off in the very first line of the batch file).

choice /c:123456 Please choose an option

First of all, Windows XP seems to have some problems with the choice command. If you use this command, you'd better include choice.com with your scenario. I've included that file with CivSwap. You can find some more information about the frivolities of choice.com on the Apolyton Civ2 Creation forum.

What choice does is simply display the Please choose an option bit and wait for user input. This input can be any of the keys mentioned in the /c: command-line switch: 1, 2, 3, 4, 5 and 6, in this case. As a result, choice returns an error level value, which can be tested with an if statement. This error level is a number corresponding to which key was pressed. For the first key mentioned in the switch it's level 1, the second key level 2 etc. In this case the error level happens to be the same as the actual key, but that need not be the case.

if errorlevel 6 goto done

This if statement, and the ones following it, test the result of the choice the user just made. They must be listed in decreasing order, because if errorlevel will be true if the error level is equal to or greater than the given number. The rest works similar to the if statements earlier on. If the condition is met, execution continues at the line labeled :done.

:Pedia_FW
echo.
echo Installing FW pedia...
copy PEDIAFW.ger pedia.txt
goto main

Here we see the first real action. The line label, and the echo and goto statements should be familiar by now. The copy command simply copies one file. In this case, it makes a copy of PEDIAFW.ger called pedia.txt.

As you will undoubtedly have noticed, we have now completely dealt with the first setup menu item. Or rather, the first two items, seeing as the MGE pedia installation works almost exactly the same. Have another look at the lines of the batch file we've been through to see how the batch file execution progresses.

:Rome_install
echo.
echo Romans, scenario start

copy EventsR1.ger events.txt
copy RulesR1.ger rules.txt
copy Units1.bmp units.bmp

echo [Turns] > CivSwap.ini
echo 114=%0 rome 114 $AUTOSAVE >> CivSwap.ini
echo 240=%0 rome 240 $AUTOSAVE >> CivSwap.ini
echo 359=%0 rome 359 $AUTOSAVE >> CivSwap.ini

goto done

Only the last four echo statements now contain something we haven't seen before. Earlier on in the description of CivSwap I mentioned how it needs both the executable and an INI file. Yet this example did not include any INI file. That's because I'm creating the INI file in this batch file. This will not usually be necessary, but Imperium Romanum has different events for the different civilizations and different turns to swap them. So each civilization would have needed its own CivSwap.ini.

There are three things to remember here: the inner workings of the INI file, the %0 variable, and the three if statements at the very start of this batch file.

The new things to note are the > and >>. Both of these are used to let DOS print the output to a file, rather than to the command screen. The difference between the two is that > will truncate an existing file (clearing its contents), while >> will append the output at the end of the file. Here's what the resulting CivSwap.ini will look like (%0 is replaced by the full path to this batch file, but I shortened it down to just the file name for brevity):

[Turns]
114=SETUP.BAT rome 114 $AUTOSAVE
240=SETUP.BAT rome 240 $AUTOSAVE
359=SETUP.BAT rome 359 $AUTOSAVE

So there you have it. This very batch file is not only used for the initial setup, but the CivSwap INI file also uses it to automate the file-swapping. To be able to tell what things need to be done, I have used command-line arguments. If you now look back at the if statements at the start, you'll see that when the Romans are being played, we jump straight to the file-swapping necessary for the Romans and skip past the setup menu.

:Rome
if "%2"=="114" goto Rome_272BC
if "%2"=="240" goto Rome_146BC
if "%2"=="359" goto Rome__27BC
goto done

You should see what this does now. After having checked which civilization is being played, it now checks the second command-line argument, as given by the CivSwap.ini, to see what year it is.

Also make sure you don't miss the final goto done. Without it, the batch file would continue at the following :Rome_272BC label when none of the if statements matched.

:Rome_272BC
echo.
echo Romans, 272BC
copy EventsR2.ger events.txt
copy RulesR2.ger rules.txt
copy Units2.bmp units.bmp
DELEVENT %3
copy %3 ca_b272.sav
goto done

Again, most of this is nothing new, just displaying some text and copying some files. The DELEVENT is a little Civilization II program that deletes the events from a savegame. Without it, new events can not be loaded. The %3 obviously refers to the third command-line arguments, as mentioned in the CivSwap.ini, and is the name of the autosave.

The last copy command requires some extra explanation. This line is not strictly necessary, but rather just a precaution. CivSwap may take a few seconds to do all the swapping. So if I'd just instruct the player to reload the autosave, there's a small chance the player is too quick, reloading the autosave before the old events have been deleted. To be sure, it's best to create a new file. That way the player will be sure to be loading the right savegame. The new file will only appear when all the swapping and events deleting has been completed.

:done

Just a label to mark the end of the batch file, used by goto statements to skip to the end. Coincidentally, you've also reached the end of this readme. I hope I've been helpful. Go create!

News - Help - Downloads - Mercator's Civilization 2 Site