CPNBUILD UTILITY DOCUMENTATION CPNBUILD Version 1.2 - MS AoE Campaign Builder Utility Copyright (C) 1997 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} [.CPN] [ ...] [/v ] [/o ] [/s] Commands: /a Add/replace scenarios in /d Delete scenarios from /e Extract scenarios from /t Set scenario versions in /l List scenarios in /h Print a help screen Switches: /v Set scenario versions to , default is '1.10' /o Extract files to 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 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 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 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 arguments. They can also contain wildcards (e. g. ".scn"). If the "/a" command is given, the 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 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 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 or non-campaign files in . 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.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 Stoyan Ratchev. All rights reserved. Last updated on 23 Nov 1997.