Yohoho Tools

Yohoho Tools is the Puzzle Pirates scene editor (also known as the Island Editor). It is used for various contests such as Beat the Champs (Island Design). There are currently no plans to update the software as it is a low priority.

It is not directly tied into the game, so it cannot be used to alter Yohoho! Puzzle Pirates.



Installation
Download the official editor for your platform (Windows, Mac or Linux):


 * Windows: http://download.threerings.net/yotools/tools-install.exe
 * Mac: http://download.threerings.net/yotools/tools-install.dmg
 * Linux: http://download.threerings.net/yotools/tools-install.bin

If you find you're having difficulties getting it to run, especially if you're not running Windows, check the links below.

Windows patching
With the latest versions of Yohoho Tools, it is unlikely that you will need to patch it. However, if you find your editor does not have the most recent objects (such as the snow pirate, Easter eggs (2008), and so on), then you can download this file. (You'll probably want to right-click, save As, but it doesn't really matter). Save it somewhere you can easily find it again. Note that the editor is receiving more frequent updates these days, so patching will likely not be required. Use this file if you want to update your tiles off the Ice client.

System Requirements for the patcher

 * 1) Both the most recent version of YPP (the game) and the "newer" version (the one that is silver) of the tools must both be installed in their default installation directories.  The older version of the tools (the one with the mostly blue interface) will not read the newly parsed file properly.
 * 2) Windows XP. It may work with Windows 2000. It may not work with anything older.
 * 3) Drive letters Y and Z must be available. If they are not, you will need to tweak the script accordingly. This is more for readability and ability to adjust locations of the tools and the game more than anything else.

Operation
To run the patcher, you can either double-click it, or open a command prompt and run it that way (which will allow you to peruse the logs, should something fail). You will be asked if you want to skip copying the files. Answer N if you are not getting all the most recent tiles from the game (which is almost always the case).

The rest of the script should operate normally, and you should not see any errors. If you do, please copy and paste the error to this forum thread.

Alternate patch method
If you absolutely cannot get the official download to work (again, under Windows), then you may download Emerson's pre-built, patched editor, which can be downloaded from here (26MB). Bear in mind that this is rarely updated, so even after you install that one, you will still need to patch by the method mentioned above.

To install Emerson's version, after it is downloaded, double-click it, and make sure to extract to C:\. This will cause the self-extractor to place the files in the default installation location of the editor. If you extract anywhere else, the paths will be broken, and the editor will not work.

Typical problem with alternate patch
The most common problem with the alternate patch is the inability for the desktop shortcuts to locate Java, due to the fact that not everyone is running the same version. The fix is relatively easy, but can be intimidating to casual users.

Right-click on your Puzzle Pirates game icon, and select properties. Copy the entire entry from the Target text box, which should look something like this:


 * Windows XP: "C:\Program Files\Java\jre1.6.0_20\bin\javaw.exe" -jar getdown-dop.jar ." (including the period)
 * Windows Vista & 7: "C:\Windows\System32\javaw.exe -jar getdown-dop.jar ." (including the period).

Paste the relevant one into the Target text box for the Yohoho Tools shortcut, and the tools should then work.

Using Yohoho Tools
Yohoho Tools can be used to create exterior or interior scenes using the same graphics and rendering as the game client.

Controls
Yohoho Tools is mainly controlled with the mouse, though a few keyboard shortcuts exist.
 * Left button clicking places a tile of the selected type.
 * Left button clicking and dragging places a block of tiles (only available in the Base Layer.)
 * Right button clicking removes an object of the current layer.
 * Right button clicking and dragging removes a block of tiles of the current layer.
 * Middle wheel clicking brings up the rendering options menu. Be patient; this sometimes takes a few moments.
 * Middle wheel scrolling scrolls through the different instances of the selected tile type.

Keyboard shortcuts include ctrl-N for "New," ctrl-O for "Open," ctrl-S for "Save," ctrl-Q for "Quit, " ctrl-D for "Make default base tile," ctrl-shift-C for "Display object commodity counts," and Ctrl-; for "Preferences."

Menu items
Menu items can be found under the "Actions" menu bar at the top of the interface.


 * Load (reload) test files
 * Make default base tile changes what the "empty" space renders as. For islands, the base tile must be water.
 * Update mini view will re-render your scene preview to create a minimap. Make your window smaller (skinnier) if you are getting black spots as it renders.
 * Undo undoes the most recent action.
 * Redo redoes the most recent undone action.
 * Display commodity object counts will give you a list of how many commodities you have placed. Herbs and minerals will only be counted if set to the right type and color.
 * Save overview map will save a rendering of your island in the install directory:
 * (Windows XP) C:\Program Files\Three Rings Design\Yohoho Tools\Snapshot.png
 * (Windows Vista or 7) C:\Users\ USERNAME \AppData\Roaming\Three Rings Design\Yohoho Tools\Snapshot.png
 * Or just do a search for "Yohoho".
 * If the screenshot doesn't take, try again or make your island smaller!


 * Save full scene is similar to the above menu item but instead will save a full rendering under the name fullscene.png.
 * Record Changes

Creating scenes
Yohoho Tools utilizes a two-layer system: a base layer and an object layer. To create a new scene, navigate to File, then New.

Base layer
The base layer is composed of all the ground tiles used to create the shape and textures on your island. Almost all base tiles can be walked on by players. Exceptions include water, lava, bog and fissures. The eight tiles adjacent to a single tile of any of these types are also un-walkable.

Object layer
The object layer contains objects that are used to populate the island, such as plants and buildings. Objects are obstructions&mdash;no matter what the size&mdash;and players cannot walk on them. Generally, objects disappear when another object (such as a building) is placed on top of them in game. However, some objects&mdash;including herbs, minerals, and cliffs&mdash;will not allow buildings to be placed on top of them.

For more complete information on the actual creating of an island, please check out the island design guide

Saving yYour work
To successfully save your island, you will need to have accomplished the following:
 * Assign a name in the scene name box
 * Choose a scene type (for most island design tasks, this will be "outdoor")
 * Place a dock arrow and name it "port".

Converting a scene from the client
Puzzle Pirates scene files are stored in the scenes\Ocean.puzzlepirates.com\ directory of the Puzzle Pirates folder.


 * On Windows XP, this is usually C:\Program Files\Three Rings Design\Puzzle Pirates\
 * On Windows Vista or 7, it's usually C:\Users\ USERNAME \AppData\Roaming\Three Rings Design\Puzzle Pirates

You can find the correct scene file for an island by searching in the scene directory for the file containing the text name of the island you are looking for, like "wrasse" or "cnossos". Finding scene files for rooms of buildings or vessels is more difficult; you can search for the room name, like "main hold" or "attic", but there are likely to be many of these. Another way to find scenes is to open the ocean's scene folder and delete most of the scene cache, like all the files with numbers over 1000. Then visit the scene in game. The most recent new scene you visited will be the most recent file in the directory.

The scene files are frequently out of date, you can force Puzzle Pirates to update the scene file by deleting it and then going to the corresponding scene in game.

Once you've found the scene file(s) you wish to use, you will need to have them in XML format. The scenetoxml batch converter used to work for this purpose, but the file format has changed, and scenetoxml will not be updated to read the new format. Please read on for information on SceneHaul.

SceneHaul
SceneHaul is another scene to XML converter capable of reading the "new" scenes. It can be downloaded from the author's site.

It is written in Java and will search the cache folders for scenes and convert all of them. To run it needs to be put into the installation folder of Puzzle Pirates. Run it from the command line with


 * java -jar SceneHaul.jar

A window will open and show the progress of conversion. After conversion you will find a new folder (directory) scenes_xml in the program folder. The files in this subfolder are XML files suitable for direct use with Yohoho Tools.

History
Yohoho Tools is now regularly being updated as additions to the game are made; you should no longer require the use of a patcher, unless you are on the bleeding edge of island design.

New fix
A new fix to the getdown.txt problem is stated on Margara's post here