INSTRUCTIONS FOR USING PWZONE_editor

1.  GENERAL
The pwzone.dat Editor will allow you to edit the map data file (pwzone.dat) associated with the game, War in the Pacific:Admiral's Edition (or AE for short).  Please see the About file for credits, acknowledgements, and disclaimers.  The editor is designed to be fairly simple tool to use but does require some understanding of the way that AE works in order to be used effectively.  The file, map_edit.pdf, distributed in this package contains the most recent understanding of the file formats of the map data files.  If you wish to edit the AE map, spending some time with this document is a good place to start.  Also, the AE manual has some very good writeups about TF movement and routing to/from off-map ports, which can help in understanding how to use these files for modding.  

2.  INSTALLATION
The editor is distributed in a zip file which uncompresses to a folder (map_data_editor).  The map_data_editor folder contains the three map data editing programs (PWHEXE_editor, PWZONE_editor, and PWZONE_editor) plus several reference and ancillary files, such as these instructions.  It is recommended that a separate installation of AE be created and that the map_data_editor folder can be placed anywhere in that installation (in the War in the Pacific:Admiral's Edition folder is convenient).  Using a separate installation is a good protection against corrupting your basic AE installation and any ongoing games.  It is also recommended that you backup the map data files (pwhexe.dat, pwzone.dat, and pwzone) in this working installation so that you can return to the baseline, original, files easily.  You also need to make a copy of the map data files you intent to edit and place them in the map_data_editor folder.  This is somewhat cumbersome but deliberate.  It would have been possible to use the Windows facilities for opening and saving files anywhere but the potential for confusion is great!  All map data files, modified or not, have the same file name.  It is up to the user (modder) to keep track of what he is doing, using the file modified dates (and other means) to maintain configuration control of his work.

3.  CONTROLS AND DISPLAYS
Upon starting the editor, you are presented with a main screen which has all of the controls and displays provided for working with the pwzone.dat file.  A brief description of how these work is as follows:

3.1  Pull-Down Menus.
There are three pull-down menus, File, Options, and Help.
3.1.1 File Menu.  The File menu provides two choices, Open and Save.  Open will look for a pwzone.dat file within the map_data_editor folder and load it into RAM, so that it may be edited.  If this is successfully done the File Status indicator will be set to green with a message of:  File Loaded.  Save will take the pwzone.dat data that is currently in RAM and write it to the pwzone.dat file in the map_data_editor folder.  Note that Save will perform a sort as described in 3.5 below before saving the file.
3.1.2  Options Menu.  The file size of pwzone.dat used in the current stock AE game is somewhat limiting if extensive modding is desired.  This option allows you to double the file size. Please note that expanded file sizes for the pwzone.dat file will only work with recent beta releases of the AE executable.  Attempts to use an expanded file with the stock program will cause AE to crash.
3.1.3  Help Menu.  This menu allows you to call up these instructions or the About information from within the program.  In addition, there is a separate reference document that shows the stock map values for certain data fields.  This file is also displayed when you edit those fields.  Since the file is a .txt file and is opened with notepad yo may use it to make notes for modifications you have made to the file. 

3.2 File Status Display.
The file status display lets you know when you have a pwzone.dat file loaded into RAM and thus can edit.  If no file is loaded, the indicator is red and when you load a file it will turn to green.  You cannot perform edit operations unless a file has been loaded.

3.3 The PWZONE DATA grid (slots) and Scrolling controls
After a file is loaded and ready for editing you will see a data grid consisting of 4 rows by 10 columns.  Each row represents one record (slot) in the pwzone file.  A stock file will have 40 slots (of 64 bytes each) for these records and you can double the number of slots by using the options menu. The grid shows 4 slots at a time and you can use the scrolling controls on the left of the grid to move up or down within the file to reach the desired slot(s) for editing.  A record, or slot, contains specific data defining either an entry zone or an off-map port.
3.3.1  Slot# Column.  The slot number column shows you where you are in the file.
3.3.2  ID#.  The ID# column shows the starting point for a link.  The ID# refers to an identifier defined in the pwhexe.dat and pwzone.dat files.  The ID# must be a value from 0-255.  ID numbers may refer to entry zones or off-map ports.  Note that the zero value (0) for the ID# is reserved in the pwzone.dat file for spare slots.  To change a value simply click in the box and type in the desired value and hit RETURN when satisfied.  If the value you entered is within the acceptable range the value will turn red, giving you a visible indication that this data has been editied.
3.3.3  Type Field.  A non-zero ID# must be either an entry zone or an off-map port.  You can select either here and hit RETURN to effect this change.  Note that in the stock file ID numbers 1-4 are used for entry zones and off-map ports are numbers starting at 101.
3.3.4  Text Field.  This is a 25 character field where you can enter a brief text description of the entry zone/off-map port.
3.3.5  Virtual X,Y field  This field only has meaning for off-map ports that can connect to entry zones.  For entry zones and off-map ports that cannot connect to entry zones this field  is set to 0,0.  The virtual X,Y location represents a virtual extension of the map grid to the X,Y location that the off-map port would occupy if the map grid were extended from the  pertinent entry zone.  So, negative values and large values are allowed.  No checking is done to assure that these values make sense, that must be the responsibility of the modder. 
3.3.6  Entry Zone Parameters (X,Y) Fields.  These four columns only have meaning for entry zones.  They define the bounds (Left/Right or Top/Bottom and two center locations that are used in routing TFs on/off map.  The X,Y values entered must be valid locations (X=0-231, Y=0-204).
3.3.7  Zone/Port X,Y Field.  This field has a dual purpose.  For Entry Zones it defines the center of the zone and for off-map ports it is simply the X,Y location on the map grid where the port is located.
3.3.8  Clear Slot buttons.  These buttons allow you to clear (all zeroes) a particular slot, thus making it a spare.

3.4  File Size Info Display
This box displays the size (number of bytes and slots) of the currently loaded pwzone.dat file.

3.5  SORT button.
The stock file is organized in numerical order, sorted first by ID#, except that the all zero (spare) slots are at the end.  Pressing this button will perform a sort to orgainize the slots in this fashion.

3.6 EXIT Button.
The EXIT button will end the program, after a reminder to save your work.  The window close control (top right corner of the main window) will similarly close the program, but without the reminder.

4.0  Binary File editing.  The pwzone.dat_editor program does not provide complete control of the values that are possible within the pwzone.dat file.  If you desire finer control over specific bytes then a binary file editor would be the tool of choice.  There are many such.  I have used the editor, HxD available at: 
http://mh-nexus.de/en/.  If you set horizontal display width to 16 bytes then each row will correspond to one of the slot locations.

5.0  Feedback.  Comments on the program are welcome.  The best way to get a comment to me is by PM at the Matrix forum.  PM to dwbradley.  Or just post in the AE mods forum.  Positive comments are of course welcome but so are negative ones as that is the best means to improve the program.

Last modified on 10/05/2011

Dave Bradley


