
CPNBUILD UTILITY DOCUMENTATION

CPNBUILD Version 1.21 - MS AoE Campaign Builder Utility
Copyright (C) 1997-98 Stoyan Ratchev. All rights reserved.
Written by Stoyan Ratchev, sratchev@mail.techno-link.com
Posted to AoE Heaven, http://age.gamestats.com/age/
This program is freeware.
Please e-mail me for bug-reports, suggestions and comments.

Age of Empires a game by Microsoft & Ensemble Studios.
All trademarks are property of their respective owners.

------------------------------------------------------------------------
CONTENTS
------------------------------------------------------------------------

Introduction
Installation
Usage
Changes
Bugs & Limitations
Future Upgrades
Credits

------------------------------------------------------------------------
INTRODUCTION
------------------------------------------------------------------------

CPNBUILD is a command-line utility for building MS Age Of Empires 
campaign files (.CPN) from scenario files (.SCN). It supports such
actions as: adding/replacing scenarios in campaign files, deleting
scenarios from campaign files, extracting scenarios from campaign
files, listing scenarios contained in campaign files, and changing the
versions of scenarios in campaign files. CPNBUILD command-line
interface fully supports wildcards, which means that all actions can be
performed on multiple campaign and scenario files and will affect only
the files matching the specified wildcard arguments.

Why such an utility when the game has a built-in campaign editor?
I wrote the first version of CPNBUILD in October 97, when the final
release of the game was still unavailable and most AoE fans played
the trial version, which does not allow to load scenarios directly.
I studied out the .CPN files format and learned to build campaigns from
scenarios I have already downloaded from Internet. I found this to be a
hard job when done by hand, so I decided to write this little utility
to help me and other people to do it more easily. So if you are still
a trial version player, you need this utility if you want to play custom
scenarios.

Compared to the built-in campaign editor, CPNBUILD has a much larger
functionality. The campaign editor of the game requires that the scenario
files you want to include reside in the SCENARIO folder, otherwise they
can't be included or even listed. With the built-in campaign editor
the extraction of scenarios from campaigns is not possible. This is
especially frustrating if you play the final version and find a very
tough or buggy scenario amidst an otherwise interesting campaign - you
can't possibly win it and can't advance ahead! No, you can't even delete
it from the campaign, since its scenarios are of course not in the
SCENARIO folder! CPNBUILD provides a solution to this and similar problems
by giving you the opportunity to add, replace, extract, delete and list
scenarios to/from campaign files with a short command-line invocation.

Please note that this software is comes with ABSOLUTELY NO
WARRANTY of any kind, so use it at your own risk. 

Microsoft (MS) and Age of Empires (AoE) are trademarks of Microsoft
Corporation. All other trademarks are property of their respective owners.

------------------------------------------------------------------------
INSTALLATION
------------------------------------------------------------------------

It's very simple. The original package is a ZIP archive called
CPNBLD12.ZIP, which contains the following files:

CPNBUILD.EXE 		- executable
CPNBUILD.TXT		- the file you are currently reading
CPNDESCR.TXT		- description of campaign files format

After unzipping the archive, copy the executable to a location somewhere
in your PATH, so you can use it without specifying its full name. If you
don't know how to see your PATH, just copy it to your Windows installation
directory.

------------------------------------------------------------------------
USAGE
------------------------------------------------------------------------

The usage of CPNBUILD is:

Usage: CPNBUILD {/a | /d | /e | /t | /l | /h} <campaign_file>[.CPN]
                [<scenario_file> ...] [/v <version>] [/o <out_dir>] [/s]

Commands:
    /a  Add/replace scenarios in <campaign_file>
    /d  Delete scenarios from <campaign_file>
    /e  Extract scenarios from <campaign_file>
    /t  Set scenario versions in <campaign_file>
    /l  List scenarios in <campaign_file>
    /h  Print a help screen

Switches:
    /v  Set scenario versions to <version>, default is '1.10'
    /o  Extract files to <out_dir> folder, default is current folder
    /s  Silent mode

NOTE: If your files have long names with spaces, you should place them in "".

NOTE: In the older versions of CPNBUILD, the "Add/replace" command was
called "Build" command and the switch was "/c". It's still there and
works in the same manner as the "/a" switch. It is provided for
backward compatibility only.

All commands (except "/h") work on one or more campaign files which
must follow the command. This is the <campaign_file> argument. It must be a
valid file specification for the Windows 95 operating system and can
contain "wildcards". These are the characters "*" or "?", where "?"
stands for "any character" and "*" stands for "zero or more any characters".
If <campaign_file> is a filename (none wildcards) the .CPN extension can be
omitted, and the file is not required to exist if the "/a" command is
given - in this case a new campaign file with the specified name is created.
If <campaign_file> contains wildcards (e. g. "*.cpn") then it should be
possible for it to be expanded to one or more existing campaign files, even
if the "/a" command is given - in this case all commands work on all existing
campaign files matching the specified wildcard argument.

Besides the command and the campaign file(s), you can specify any number
of file specifications for the scenario files which the command should process.
These are the <scenario_file> arguments. They can also contain wildcards
(e. g. ".scn"). If the "/a" command is given, the <scenario_file> arguments
are assumed to be existing external files which should be included in the
specified campaign file(s). Otherwise, they are assumed to be "internal", i. e. 
contained within the specified campaign file(s) which should be deleted,
extracted or listed. If there are no <scenario_file> arguments given,
they assumed to be "*.*", i. e. all files in the current folder. Note than
when processing "internal" files you should specify the "scenario filenames"
and not the "scenario names" which you see when you open the campaign in the
game. Usually the scenario filename is derived from the scenario name by
simply adding the ".cpn" extension, but this is not a rule. If you don't know
the scenario filenames in your campaigns, use CPNBUILD with the "/l" command
to see them.

No matter the command, the campaign and scenario input files are not required
to reside in the AoE folders. The output files are created in the current
folder, unless otherwise specified in the <campaign_file> argument and
the "/o" switch. To use them with AoE, you must copy them by hand to the
CAMPAIGN folder (for .CPN files) or the SCENARIO folder (for .SCN files)
where the AoE was installed. After doing so, simply start the game and
enjoy.

Examples:

To add/replace  to the campaign file CAMPAIGN1.CPN all scenario files in the current
folder, type: 

  CPNBUILD /a campaign1 *.scn

The files are replaced if they are already contained in the campaign and added to the
end of the campaign otherwise. If the campaign doesn't exist, it will be created.

To extract all scenarios beginning with "T" from the campaign file CAMPAIGN1.CPN,
located in the current folder, type:

  CPNBUILD /e campaign1.cpn "T*.*"

To list all scenarios in the campaign files from the CAMPAIGN folder of the game
(assuming it's C:\GAMES\MSAOE\VAMPAIGN)

  CPNBUILD /l c:\games\msaoe\campaign\*.cpn

If the task is completed successfully, all actions are displayed on the
screen, unless the "/s" switch is given, and the output file(s) are created,
if any. If an error occurs, a message is displayed and the program execution
is stopped. Possible errors include failures to open, read from or write
to some of the files that were specified, wrong usage, or attempt to use non-
scenario files in <scenario_file> or non-campaign files in <campaign_file>.
The type of the files is determined from their extension, which must be
always ".cpn" for the campaign files and ".scn" for the scenario files.

When should you use the "/v" switch or the "/t" command to set the versions of
the scenarios? Well, the trial version refuses to load scenarios which
doesn't have its version number. The final version seems to cope with this,
but a problems due to inconsistent scenario versions maybe can be expected.
The beta version of AoE is numbered 1.09, the trial version of AoE is 1.10,
and the official (final) release is numbered 1.11. This means you cannot play
with the trial version scenarios made with the beta or the final versions,
even if they are included in a campaign. An attempt to do so results in the
message "This scenario does not work with the trial version". In fact, the
scenarios from the both versions are compatible, and I have successfully
played "1.09" and "1.11" scenarios with the trial version after explicitly
setting their version to 1.10.

By default CPNBUILD doesn't set the scenario versions. The older versions
of CPNBUILD were "trial oriented" and set the version of all files to 1.10
If you want to play campaigns with the trial version the "/v" switch is
required, for example:

  CPNBUILD /a campaign1 *.scn /v 1.10

or

  CPNBUILD /t campaign1 /v 1.10

------------------------------------------------------------------------
CHANGES
------------------------------------------------------------------------

Version 1.21 - Version 1.2

- Added small changes to handle RoR campaigns & scenarios
  (".cpx" and ".scx" files) correctly.

Version 1.1 - Version 1.2

- "Build" ("/c") command replaced with "Add/replace" ("/a") command.
- "Delete" ("/d") and "Change versions" ("/t") commands added.
- Added full wildcard support.
- Added "/o" switch for the output directory.
- Added "/s" switch for silent mode, default mode made "verbose".
- The "/k" switch made obsolete, by default the versions are not changed.
- Documentation updated.

Version 1.0 - Version 1.1

- "List" command added (/l switch).
- Added some new info to the documentation -- "Credits" section, the
  version of the official release, etc.
- Added a description of the campaign files format in the CPNDESCR.TXT
  file.

Version 0.1 - Version 1.0

- "Extract" command added (/e switch).
- "Keep versions" mode added (/k switch).
- /c switch is no longer optional - you must use either /e (extract) or
  /c (build), otherwise it's error.
- Fixed a bug in the command line parsing that allowed the building of empty
  campaigns.
- Documentation updated accordingly to the above changes.

------------------------------------------------------------------------
BUGS & LIMITATIONS
------------------------------------------------------------------------

There is one bug I found, at least with the trial version and on my
machine: the first time you try to use a new multi-scenario campaign it
loads only the last scenario. I don't know whether it is a CPNBUILD bug
or an AoE bug. To play all included scenarios, simply restart the game and 
try again. Or if you prefer you may use only single-scenario campaigns,
which are always OK.

------------------------------------------------------------------------
FUTURE UPGRADES
------------------------------------------------------------------------

I will try to keep up with the game and provide bug-fixes and future 
upgrades to anyone interested. They will be available on the 
AoE Heaven site at:

  http://age.gamestats.com/age/

This site contains also some scenarios already available on the Internet 
that you can try with the trial version of AoE and CPNBUILD. Their number 
is expected to grow, so check this great site regularly.

------------------------------------------------------------------------
CREDITS
------------------------------------------------------------------------

I would like to thank the following people for supporting and
encouraging my work:

Archangel Michael (webmaster@heavenweb.com) for web-mastering the
AoE Heaven site and giving me excelent support and feedback.

Leonaldo Brum (leo.brum@mail.telepac.pt) for encouraging me and first informing
me about the version number of the official release.

And of course Microsoft & Ensemble Studios for creating the greatest
RTS game of all times, Age of Empires!

************************************************************************
Copyright (C) 1997-98 Stoyan Ratchev. All rights reserved.
Last updated on 21 Oct 1998.

