-
Notifications
You must be signed in to change notification settings - Fork 3
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.
All translators will translate level and world data, NOT graphics or sounds. Technically, this means translators handle Plvl and WrLd data, but none of the others like PICT, ppat, MADH, and clut(clut is not relevant anymore anyways). Hence, each world you wish to translate must have a resource pack manually created. See Resource Packs for more information. Here are some things to keep in mind when using a translator:
-
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 is.
-
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.
-
Order must be maintained for ppat patterns also. Make sure pattern0, pattern1, pattern2... etc are all ordered the same way they appear in ResEdit.
-
Original Monkey Shines levels did not have full screen backgrounds. It is not required to add a placeholder.
This takes a resource pack and resource fork and creates a world from the two. This can either be run headless (as in from command line) or from the Level Editor.
First, make sure you prepare a folder containing both the original resource fork of the Monkey Shines level and the resource pack with the graphics and sounds.
To actually obtain the resource fork, one can use an emulator (SheepShaver) and move the world file over from the emulator to the primary windows filesystem. The Resource Fork will be automatically extracted; check the .rsrc folder that appears in the destination. A file with the same name as the original will be there, and will represent the resource fork. The resource fork format is exactly the same there as it is internally in the Mac OS systems, so the file itself is a valid resource fork and can be examined by things like ResCafe or other tools. Specifically for translation, it means the editor can understand it.
For translating using the level editor:
- Go to File->Import... and select both the resource fork file and resource pack file.
- Click 'Import'
- If successful, the new world will be saved to the directory containing the resource pack, with the same name as the resource pack, but with the extension .world (that will also be the world name). The world will be loaded automatically as well into the editor.
- Tweak and test for any issues. Exit and Bonus doors sometimes are not set properly.
For translating using the command line (fill in the [''] with the path to the proper files
java -cp "[Monkey Shines jar path]" org.erikaredmark.monkeyshines.editor.importlogic.ResourceForkTranslator [path to resource fork] [path to resource pack]
As with the level editor, a .world file will be created in the resource pack folder. You can then load this level up in the level editor and make any needed modifications.
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)
Make sure you followed the advice for setting up the resource pack for a translator.
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.
-
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.
-
Some levels bonus door is set to ID 1, not ID 0. Not sure how the original game told the difference since there isn't anything in subkind to do so. If the first sprite is the exit door, one must go through the translated world in the editor and swap the bonus/exit doors manually.
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.
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.
-
Be sure to playtest the world. The port uses a black-box recreation of the original engine. Whilst this recreation is very close to the original, any jumps or other points that may have required very, very fine pixel-perfect precision may become impossible in the port. Restructure the level as needed.
-
Bonus levels are on screen -8000. Basically, due to a mistake in the early design of this port, the numbering for levels in a world when moving up/down is inverted. In order to preserve the logical layout of the world, inversion rules are applied (so level 900 in the original becomes 1100 in the port, for example). Since level 10000 was always the bonus level in the original, applying the inversion rules brings the bonus level to -8000 for the port. Nothing special about that number, just how the math worked out. If you are interested in the details, see the source code in the package
org.erikaredmark.monkeyshines.editor.importlogic.