Porting Old Worlds

There are two ways of porting worlds: Manually, or with assistance of an automatic translator taking the original Monkey Shines world data

Translators

Basic Translator (Available since v0.3.0)

This is run from the main class org.erikaredmark.monkeyshines.editor.importlogic.BasicTranslator, for example:

java -cp "Monkey Shines_v0.3.0.jar" org.erikaredmark.monkeyshines.editor.importlogic.BasicTranslator

As its name implies, it is the most basic translator and requires a good amount of setup to use, although not nearly the effort that would be required to recreate each level screen manually. To use, you must create a source folder with the following data:

 world_name
 - |
 - +--------- lvl_1000.plvl [Plvl data for that level, taken from ResEdit]
 - |
 - +--------- lvl_1001.plvl
 - |
 - +----- <any number of lvl_#.plvl files for each level screen>
 - |
 - +--------- world_name.wrld [WrLd data, taken from ResEdit]
 - |
 - +--------- world_name.zip [Resource pack, MUST be manually created using other tools]

The lvl_### files are to be the binary data taken from ResEdit for the .plvl resource indicated by the number. The world_name.wrld is the same concept, but for the sole .WrLd resource. Finally, the .zip resource pack must be created from scratch using other tools. ResEdit can be used to extract graphics easily, but Sounds and Music in MADH format may require additional tools like PlayerPro to export into a better format (either directly to .ogg or to a format that allows another tool like Audacity to convert to .ogg)

Some things to keep in mind when making the resource pack:

1. Order is important! The tilesheets should contain the solids, thrus, scenes, etc... in the same order as they are in the original. This isn't too difficult to do and is probably the natural thing to do given how easy it it.
2. Order must be maintained for sprites as well. Make sure that sprite0, sprite1, sprite2... etc are all ordered in the same way they appear in ResEdit.
3. Order must be maintained for ppat patterns also. Make sure pattern0, pattern1, pattern2... etc are all ordered the same way they appear in ResEdit.
4. Original Monkey Shines levels did not have full screen backgrounds. It is **not ** required to add a placeholder.

Once the folder is ready, run the translator with the path to the source folder you created, for example:

java -cp "Monkey Shines_v0.3.0.jar" org.erikaredmark.monkeyshines.editor.importlogic.BasicTranslator relative/path/to/folder

If there are any issues, the console will log the error. Some errors are caused by the source folder being malformed. However, it is possible that issues can occur for perfectly valid worlds since not everything translates 100% properly given the differences between the engines. This would be a deficiency in the translator. In the event that occurs, contact me (Erika Redmark) or make a github issue.

Gotchas

1. Do not just paste the raw Hex values from ResEdit into a Simple Text document. The document may contain the Hex Stream, but it itself is not the actual binary data (it is text data for each character representing each digit of the hex stream). The raw binary data must be exported or copy-pasted into a file. If this isn't possible and only the Hex can be obtained, a linux program called xxd could assist in converting a hex stream into an actual file made up of that data.

Completely Manual

If you have the time, or the world is small enough that it is actually faster to do things manually than load up the translator, there are a few things you must still keep in mind. The resource pack still needs to be created, however the ordering of the sprites, patterns, tiles, etc... doesn't need to be the same (since you will manually be placing the right tiles in the editor anyway). However, there are some more gotchas that must be taken into account.

Sprites

The Edit-Sprite dialog in the original has different fields with different values. In the original, 0,0 was the UI. In this game, 0,0 is the top-left of the playable area, so since the UI is 80 pixels high there are some vertical fields that must be compensated.

The following table can be read as: "this field in the Java port is equal to ...'

Java Port	Original Game
Top-Left (x)	Left
Top-Left (y)	Top - 80
Width	Right - Left - 40
Height	Bottom - Top - 40
Start (x)	(Starting Location) Horizontal
Start (y)	(Starting Location) Vertical - 80
Velocity (x)	(Velocity) -Horizontal
Velocity (y)	(Velocity) -Vertical

Pay attention to the - sign for velocities. These are flipped in the port.