[Tool] ToEE Path Mapper Tool 1.0

ToEE Path Mapper v1.0
===================

I have written this ToEE Path Mapper tool to allow CO8 modders to easily and quickly create new paths for party travel on the worldmap. Along with Spellslingers worldmapper tool and wonderful dll hackery to allow new locations to be added to the ToEE worldmap, this should mean an end to the infernal instant travel method of adding new game areas to our favorite game. I also hope that this tool will prove useful for doing the worldmap paths for the KotB mod too.

The genesis of this tool came about last week when Allyx posted his painstakingly hand-drawn image of some existing paths in the game. All credit to him for even attempting to climb that massive mountain of work, but I felt I couldn't stand by and let him stare at MS Paint until his eyes were dribbling out of their sockets. Therefore I decided to code a tool to make the task a bit easier and quicker. I have written it in Java because that's what I currently use at work every day so I'm pretty familiar with it, although not so much with GUI programming hence the user interface is rather basic. There's also very little in the way of error checking and handling, but although it may not be professional standard code, it gets the job done!


Installation & Running:

1) If you don't already have Java installed, or it's an older version, download and install a Java Runtime Environment, version 5 or greater. You'll need to visit this page: http://www.java.com/en/download/windows_xpi.jsp to get it.

2) Download the Path Mapper JAR file using this link: http://files.co8.org/tools/PathMapper.jar saving it into a folder of your choice. (JAR stands for Java ARchive by the way)

3) Copy the worldmap_ui_paths.bin file that you intend to edit into the same folder as the JAR file. You can extract the current ToEE one from the JAR file by opening the JAR using WinZip, or you get it from the <ToEE_install>/data/art/interface/worldmap_ui/ folder. The tool has no concept of loading files (to save development time) so it will only operate on the worldmap_ui_paths.bin file that it finds in the current directory.

4) You can now start the Path Mapper by firing up a command prompt, changing to the directory containing the .jar & .bin files and typing "java -jar PathMapper.jar" to run the tool. (you will have to specify the location of java if it's not on your path) This method does have the slight advantage that you can see any error output from the tool if something does go wrong, although there's precious little error handling really.

Alternatively, double clicking on the JAR file should also start the mapper tool - it does for Allyx. (This should work for most people - it doesn't for me due to the plethora of JRE's and JDK's I have installed over the years)


Usage:

The basic premise of the Path Mapper tool is to display the worldmap from the game and overlay the existing paths. See the screenshot below for an example with all the current game paths displayed. You can then draw new paths onto the map by pointing and clicking the left mouse button to set a coordinate. Straight lines are drawn between each coordinate placed, so you can put them far apart for straight roads, and close together for corners. Although the tool will convert the straight lines to steps for ToEE, you need to draw smooth curves yourself using very short lines. Clicking the right mouse button will remove the last coordinate set.

There is no way to edit an existing path from the game, or one that has been previously committed (and converted to steps internally). You will need to draw the complete path again. A good technique is to draw several paths from the same location to several destinations one after the other. Commit a path and then just right click to delete the bit you don't need for the next destination, and draw the remaining path. Repeat as necessary.

The controls along the top toolbar perform the following functions, left to right:

Zoom - This drop down selects the level of zoom from 1:1, 1:2, 1:3 and 1:4 - coordinate to pixel ratio.

Offset Adjustments X & Y - These two controls allow the offset of the coordinate origin (the top left corner of the drawing pane) to be adjusted relative to the worldmap displayed. Basically this makes absolutely no difference to the path coordinates, just to the position of the map graphic displayed under the paths. I've put in some default values that seem to get the existing paths aligned to the graphical paths on the ToEE worldmap.

Path Display Selector - This drop down allows existing paths (either committed or loaded from the .bin file) to be displayed or removed from the drawing pane. Selecting a path number displays a path, and selecting the same path number again will remove it from the display. There are also entries to display or remove all the paths. It's a little unconventional, but it saved time.

Path Colour Selector - This button pops up a colour chooser which allows a different colour to be chosen for displaying the paths in the map. The default is always the green that I feel looks best, and if you cancel then the paths will be displayed using a range of colours. (this looks truely horrible, but I thought it may help distinguish paths)

Reset Path - This button resets the currently drawn path, effectively deleting it. It does not affect any of the paths shown in the path selector that have been committed or loaded - only the one currently drawn.

Commit Path - This button pops up a dialog box which allows the currently drawn path to be committed to either an existing path number or a new path number. It only changes the internal paths data structure.

Save Changes - This button saves the paths stored in the internal paths data structure to the worldmap_ui_paths.bin file in the format used by the game.


Lastly, to change the worldmap displayed behind the paths, for editing KotB paths for instance, place a jpeg of the map, named "WorldMap.jpg" in the same directory as the JAR file and it will be used instead of the standard ToEE one I've put into the JAR file.

Hope you find it useful - Hazelnut.