INSTRUCTIONS FOR USING PWZLINK_editor

1.  GENERAL
The pwzlink.dateEditor will allow you to edit the map data file (pwzlink.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 format of the map data file.  If you wish to edit the AE map, spending some time with this document is a good place to start.  

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 mad data editing programs (PWHEXE_editor, PWZONE_editor, and PWZLINK_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 pwzlink) 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 datas file you intent to edit and place it 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 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 pwzlink.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 pwzlink.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 pwzlink.dat data that is currently in RAM and write it to the pwzlink.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 pwzlink.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 pwzlink.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 you 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 pwzlink.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 PWZLINK DATA grid (slots) and Scrolling controls
After a file is loaded and ready for editing you will see a data grid consisting of 8 rows by 6 columns.  Each row represents one link record (slot) in the pwzlink file.  A stock file will have 100 slots (of 15 bytes each) for these records and you can double the number of slots by using the options menu. The grid shows 8 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 link record, or slot, contains specific data that the AE program uses to route TFs from on-map to off-map ports and from off-map ports to other off-map ports.
3.3.1  Slot# Column.  The slot number column shows you where you are in the file.
3.3.2  From ID#.  The From 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 From ID# is reserved in the pwzlink.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 correct the value will turn red, giving you a visible indication that this data has been editied.
3.3.3  To ID#.  This identifies the ending point for a link.  It works similarly to the From ID# column.
3.3.4  Holding Box X,Y.  Each entry zone and off-map port has one or more holding boxes associated with it.  These are defined in the pwhexe.dat file.  A holding box is NOT a link end point but instead identifies the hexagon where the AE program will display TFs that are in transit between link endpoints.  The input box will accept any valid X,Y location within the confines of the hexagon grid (X=0-231, Y=0-204).
3.3.5  Distance.  This column contains the distance between the From and To ID#s.  This is required for off-map to off-map ID#s and is in hexes.  If the link has an entry zone as one end of the link, the distance will be calculated by the AE program using the virtual X,Y location defined for that off-map port in the pwzone.dat file.  In the case of the entry zone to off-map port link slot this value must be FFFF (hexadecimal).  This is shown as NA (FFFF) and you may enter either NA or FFFF or NA (FFFF) to get this results.  The edit box will also accept decimal numerical values from 1-65534.
3.3.6  Effectivity Date.  This column shows the date when the program will allow TFs to use the link.  In the stock game this is used to block the Suez Canal routes until May 14, 1943 (430514).  If the value is 000000 then the link is good from the game start date.  If you wish to have the route work from game start date then you may enter At Start or 000000.  Otherwise the editor will accept dates in the format yymmdd.
3.3.7  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 pwzlink.dat file.

3.5  SORT button.
The stock file is organized in numerical order, sorted first by From ID# and then by To 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 pwzlink.dat_editor program does not provide complete control of the values that are possible within the pwzlink.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


