The game is provided with a Level Editor. If you are using non-windows executables, you can still run the level editor as such:

java -cp "Monkey Shines_v#.#.#.jar" org.erikaredmark.monkeyshines.editor.LevelEditor

However, the level editor is only one part of making a world. Granted, it's quite important, but as the original game level editor documentation stated as well, the editor is like the canvas you draw your world to... but you still need a palette. What are the graphics going to be? Will custom sounds be used? Custom Music?

The 'Palette': Getting your graphics and sounds together

This section details the Resource Pack. A resource pack is basically just a .zip file. Contained within are specifically named files of graphics (.png types with RGB color tables and alpha transparency) and .ogg files for sounds and music. It is suggested that you take an existing resource pack and modify it for two reasons:

1. It would be bloody annoying to re-create every single file required (there are a lot) and have to keep looking up the names of the files to make sure you are designing it properly.
2. A LOT of graphics and sounds are re-used from world to world. You are unlikely to change what an explosion looks like (but feel free to) and most sounds are probably going to be re-used as is. Modifying an existing pack ensures that you already have a valid pack, making it easier to modify exactly what you want to and no more.

The Default Resource Pack

It is highly suggested that you look at Resource Packs for a breakdown of what the resource pack is, what it contains, and the properties of each graphic. The default resource pack is basically a resource pack provided by the level editor that is a subset of the 'Spooked' level with some changes such as placeholder graphics where one should replace with their own.

Designing Graphics

This is the part that the Level Editor can can not help you with. Designing graphics is tough, whether pixel art or 3D models animated and rendered to a 2D sequence of images. If you want to make your own graphics instead of re-using existing ones, here are some ideas:

• GIMP: This is an open source graphics editor similar to Photoshop. It is intended for 2D design. This is useful for tiles and hazards, where the 20x20 pixels don't afford too much detail.

• Blender: This is an open source 3D modeling and animation program. Whilst it is possible to design Sprites by hand in a 2D program, the multiple frames of animation required can be tedious to do properly. From my understanding, most if not all of the Sprites in the original game were designed in a 3D program (not Blender, it wasn't available back then) and animated, then 8 frames of animation were rendered from the program, and then put together in a sprite sheet (you can use GIMP for that). If you go this route, remember 3D has a much steeper learning curve than 2D. Additionally, the final sprite sheets will be .pngs with an alpha transparency... so the renderer should provide rasterised images with Alpha transparency, not just some background colour.

If that seems intimidating, it's because designing nice, artistic graphics is very difficult. However, don't overlook how important reusing existing graphics are. You can mix and match sprites, tiles, etc... from multiple worlds into one. You can take existing graphics and modify them slightly instead of starting from a blank canvas. For example, you could take the sideways skull from Spooked and pass it through a GIMP filter and make it blue.

Of course, if you happen to be a graphics designer, the above really doesn't apply to you; in the end, whatever tools you use, as long as they produce the right format expected by the game, will work fine for generating graphics.

The Level Editor: Building your world

After assembling your resource pack (or picking one to re-use), this is your next step. The Level Editor allows you to build new worlds and edit existing ones. When loading up the editor, you will initially be presented with a white screen and an empty window. From here, you can either create a new level, or load an existing one.

It is at this point, when creating a new level, that you can select a checkbox that asks if you want to use the default resource pack. Doing so allows you to quickly get started designing the level (the resource pack is copied to the new folder for the world so you can always modify it). Otherwise, select the resource pack .zip file you want to use (which will ALSO be copied into the new world folder).

Saving:

Go to File->Save to save your world. Worlds are always saved to their .world file in the respective folder. I mention this first because save early, save often, don't lose your work. And make backup copies too. Just to be safe.

The Editor Overview

First, you have to make a new world, or load an existing .world file. When you do, you get the main level editor screen:

https://github.com/ErikaRedmark/redmark_wiki_images/blob/master/monkey_shines/level_editor/main_editor.png

In a default setup, the left side of the screen contains the palette. This is where you select your brush. Your brush is either placing something in the world like tiles and sprites, editing something with special properties in the world (currently only sprites), or deleting things from the world. At any one time, you are editing a single screen of the world. By default, the world loads at screen 1000. To change the current level you are editing, go to Screens->Go To Screen... and find or enter the number of the screen you wish to edit (more information on screens later). At the bottom is the 'Templates' palette, which is a bit more complex and will be discussed much later.

Level Structure

The first thing to understand is how a world is structured. A Monkey Shines world is composed of several levels, with the starting level being 1000. Levels are numbered according to their position. A level that is directly above 1000 is 1100, so a +100 change. A level that is directly below 1000 is 900, a -100 change. For horizontal movement, going to the left is a -1, so left of 1000 is 999. Likewise, right of 1000 would be a +1 for 1001

Here is the example, along with a few more level numbers to show the pattern:

          1100
            |
    999 - 1000 - 1001 - 1002 - 1003
            |                    |
           900 - 901            903
            |
           800

There are a few things to note here. The first is that this numbering scheme means that if you go too far horizontally, you may run into the levels above... for example, if 1003 went to 1004 to 1005 and upwards, it could clash with levels you wish to be to the left of 1100, not to the right of 1003. This is unlikely to happen as that would be a rather large level, but be aware that at extremes, the numbering system will start to get a little funky.

Keeping this in mind, this will allow you to set up your levels in your custom world the way you want to. As long as there is someway for Bonzo to jump through either the top, left, right, or bottom side of a level, he can transport to the adjacent level. If there is no adjacent level, Bonzo becomes Pacman, essentially appearing on the opposite side of the same level. This typically should not occur in real gameplay. For example, in the original game, doing this would white screen and crash the game, so no original levels have this quirk. This pacman behaviour was coded simply so something other than crashing could happen on screen transference.

https://github.com/ErikaRedmark/redmark_wiki_images/blob/master/monkey_shines/level_editor/goto_screen.png

You can use 'GoTo Level...' to both select existing levels or build new ones. If a level hasn't been created yet, the phrase 'New' will appear in place of the thumbnail.

Building your World

Designing the world is as simple as creating a level (1000 always exists) and editing it using the supplied palette on the left. From bottom to top (left to right), the tabs are

1. Sprites: This palette always contains an icon with a pointer finger and a bee signifying 'edit existing sprites'. The rest of the palette shows all the sprites available for the world. https://github.com/ErikaRedmark/redmark_wiki_images/blob/master/monkey_shines/level_editor/sprite_placement.png
2. Solids: All the solid blocks for the world. Bonzo cannot pass these tiles in any way.
3. Thrus: All the 'thru' blocks. Bonzo can jump through them, even walk through them, but they block downwards movement. In other words, Bonzo can stand on these, but they don't otherwise obstruct his movement.
4. Scenes: All the scenery. Scenery is intended for making a level look nice and has no effect on the gameplay directly. However, scenery that looks like solids or thrus can be used for hidden passages or tricking the player.
5. Hazards: Stuff that kills Bonzo on contact, with exception of harmless hazards. In a new world, this is initialised to all the graphics available for hazards in the world BUT the properties of each type of Hazard default to exploding bombs. See the later Hazards section for details on how to define these properties.
6. Conveyers: These move Bonzo faster in one direction, and slower in the other, when he is standing on them, and even after he jumps off, carrying his momentum (until he lands on a non-conveyer surface again). Conceptually, they act like thrus in all other regards.
7. Collapsibles: These start breaking apart when Bonzo stands on them, until they are gone. Conceptually, they act like thru tiles when present, and when destroyed they act like scenery.
8. Goodies: These are the fun things Bonzo grabs for points and special effects. Goodies can be skinned differently for each world, but all worlds have the same types of goodies. Note there is a majour difference from the original game here: Goodies MAY be placed on tiles; they themselves are not considered a tile. The only tile that you should really not put a goodie on is a solid tile, because, barring glitches, Bonzo cannot ever grab a goodie on a solid tile.
9. Erasers: There are three erasers: the one with the cut through the solid tile erases tile objects, cut through the bee is the eraser for sprites of any kind, and finally the cut through the apple erases goodies (since goodies and tiles can occupy the same space, a separate eraser is provided for each)

Most of these are pretty easy to use. Two require a bit more explanation: Hazards and Sprites.

Defining Hazards

Each hazard graphic for a world represents one 'type' of hazard. All hazards of that type (that graphic) will exhibit the same properties in the game. By default, all hazards are defined as exploding, causing a burn death. To modify this, go to Hazards->Edit Hazards...

https://github.com/ErikaRedmark/redmark_wiki_images/blob/master/monkey_shines/level_editor/hazards_editor.PNG

This screen shows, on the left, a graphic of each hazard defined in the level. Next to those graphics are icons that give information about the hazard. In order, the icons are:

1. The death type. This can be one of five images:

   1. A silhouette of Bonzo against embers and lava. This means Bonzo will be burned by the hazard.
   2. A lightning bolt. Bonzo will be electrocuted by this hazard.
   3. A bee stinger. Bonzo will act as if was killed by a bee (large bump on his head) by the hazard.
   4. A skull and crossbones. This simply means a standard death animation as if he was hit by a sprite.
   5. A Peace symbol. This hazard is harmless and will not affect Bonzo in any way.

2. Whether it explodes. This is simple: Either the icon is there (indicating the hazard explodes) or it isn't. This does stack with the harmless hazards, so they can still explode just deal no damage. Hazards that explode do have a slight gameplay effect: If Bonzo has a shield, the hazard explodes but Bonzo is unaffected. Even if the shield goes away, the hazard is still gone and can't hurt him anymore until the screen is reset (when he moves off the current level to another one)

To modify a hazard, click on the one you with to modify, and on the right side an editor will appear. From here, you can indicate the death type, whether the hazard explodes, or a special checkbox indicating a hazard should be harmless. Changes are automatically applied when the dialog is closed.

Sprites

Sprites are the most complicated component to add to a world. A sprite is essentially an animating whatever that bounces around the level in some fashion. When adding a new sprite, the dialog that appears can be intimidating. First, a high level discussion of what Sprites are and their properties before delving into the sprite editor dialog.

A Sprite lives inside of a rectangle. Each sprite defines three main properties in terms of movement:

1. Where it starts (a point)
2. Where it lives (a rectangle)
3. How fast it moves (a velocity)

A sprite will start at some location in the level. If it has any velocity, it will start moving in the given direction, switching directions if it hits the edge of it's living rectangle. All locations are specified in pixels, not tiles. As a result, sprites can be partway between other tiles.

The Sprite Editor

https://github.com/ErikaRedmark/redmark_wiki_images/blob/master/monkey_shines/level_editor/sprite_editor.png

When editing an existing sprite, or adding a new sprite, a sprite editor dialog will appear. We'll go through each field one at a time. It isn't as intimidating as it looks, and in many cases, some fields will not be relevant. This documentation assumes knowledge of the Cartesian Coordinate System when I talk about x and y positions. The primary difference between this game and a standard coordinate system is that the 0,0 point is the top-left of the playable area, but going down has increasing y levels.

+ x  0  1  2  3  4  5
y +------------------
0 |  
1 |  
2 |
3 |
4 |
5 |

1. Top-Left(X) and (Y): Location of the top-left part of the rectangle that the sprite will live in. Basically, the sprite can go as high as y and as far left as x before having to bonce back.
2. Width and Height: How wide and high the rectangle will be. Together with Top-Left, this defines the entire rectangle.
3. Start (X) and Start (Y): The x and y location that a sprite starts at.
4. Velocity (X) and (Y): How fast and in what direction the sprite will initially be moving. Whilst direction will change in the course of the game, the speed will remain constant.

Before moving on, some important notes on movement:

1. If a sprite defines NO velocity in either direction (basically both zero), then the Top-Left(X) and (Y), and the width and height, are all irrelevant. It won't be moving so it needs not a defined rectangle to move within.
2. If a sprite defines one velocity but not the other, than the axis perpendicular to the axis of the defined velocity is irrelevant. For example, if x velocity (left and right) is defined, then Top-Left(X) and Width must be defined to give the horizontal bounds of the movement. However, Top-Left(Y) and Height are irrelevant. Since the sprite will not be moving up and down, it doesn't matter what these values are (they could even be zero) as the sprite will never need to be bounded by up-down since it will never move like that. This applies to defining only y velocity as well (although in that case, it would be Top-Left(X) and width that would become irrelevant).
3. If a sprite has a defined bounding box and a non-zero velocity in at least one axis, but it's starting location is outside of the bounding box, it will unconditionally move towards the bounding box (even if the initial velocity is defined for the opposite direction. As with point 2, if only one of the velocities is defined, it will move towards, and then be bounded by, the bounding box coordinates for only that axis.
4. [Technical] The bounding box refers to the entire body of the sprite, not just the top-left pixel of the sprite. Basically, if a rectangle is defined as 100,100 with a width and height of 40, the sprite cannot move, as sprites themselves are 40x40. Smaller sizes will also constrain movement.

Beyond movement, we get the sprite properties, which are simpler to understand. Here are the rest of the options in the Sprite Editor dialog.

1. Sprite Type: This is the first selection box (right under the velocities fields). It determines how the Sprite should behave. Most sprites are instant kill. In general, only Bees are health drainers (this was done so as not to surprise players) but any sprite can be a health drainer technically. The other two types are Bonus Door and Exit Door, which will be explained later, but the general gist is that Exit Doors appear after all red keys are collected and end the level. Bonus Doors appear after all Blue Keys are collected and either transport Bonzo to the bonus room or back to where he entered the bonus room (depending on what door he entered: more details on that later). The final type is unique to the port and was not in the original: A sprite can be harmless. There were some glitches that could be exploited in the original to do this trick. A harmless sprite, as it's name entails, cannot hurt Bonzo.

2. Id: This basically says which graphic to use. There will be as many ids as there are sprite graphics for your world. A little animation will show you which sprite graphic you are using.

From Top to Bottom, the four selection boxes to the right of Id are:

1. Animation Type: All sprites have 8 frames of animation, numbered 0-7. Increasing Frames means that when a sprite hits frame 7, it goes down to frame 0 and then goes back up to frame 7, back and forth. Basically, it goes between frames 0-1-2-3-4-5-6-7-6-5-4-3-2-1-0-1-2-3... etc. Cycling Frames indicates that a sprite animation jumps back to frame 0 from frame 7, which goes like 0-1-2-3-4-5-6-7-0-1-2-3-4-5-6-7-0-1... etc.

2. Animation Speed: A sprite can transition between frames normally (Normal Animation) or at a reduced rate (Slow Animation).

3. Forced Direction: This is rarely relevant and should normally be left alone. This basically means that if a sprite has two directions defined (a sprite sheet with two rows) it will only use one direction or the other, regardless of what direction it is moving. This is typically used for sprites that need to face one direction and their velocities would otherwise never cause them to hit a bounding box and reverse (for example, two bees, one facing left and another facing right, but moving up and down guarding a platform). Check the 'Forced Direction' checkbox to use this feature, then select whether to use Right/Up (first row) or Left/Down (second row) for the sprite. This field is irrelevant for sprites that only define one row of animation.

4. Two Sets Type: This is only enabled if the sprite has two rows of animation defined. The first row of animation can either be the sprite moving right or moving up, and the second row is either the sprite moving left or moving down. This determines which of two possibilities to take, which controls when the sprite change animation rows (whether it be because of switching direction on the horizontal axis, or switching direction on the vertical axis. Two Sets Horizontal is the default and causes animation row switching for bouncing off the left and right bounds, and Two Sets Vertical causes animation row switching for bounding off the top and bottom bounds. [Trivia: Whilst the original game provided capability for two sets vertical, no original levels ever used that feature.]

Press 'Okay' to save changes.

Offscreen Sprites

It is okay to define a sprite that can move offscreen. Sprite can either pop into or out of (or both) a level from any side by being defined past the boundaries of the level (negative numbers for left/top, and values greater than 640 for the right side and greater than 400 for the bottom). Obviously, these sprites can't be clicked to be edited. To edit them, go to Sprites->Edit Offscreen Sprites... .A selection dialog may appear if there are multiple sprites offscreen. Select one and start editing.

https://github.com/ErikaRedmark/redmark_wiki_images/blob/master/monkey_shines/level_editor/edit_offscreen_sprites.png

Sprite Selector

If clicking a location or editing offscreen sprites resolves multiple sprites to choose from, a sprite selector dialog will appear. The dialog shows the image of all the relevant sprites, as well as their x/y starting locations (which is the most likely thing to be different about them). Note that when editing sprites, they maintain their order in the dialog. So, if there are 4 identical sprites and you select the third one in the dialog, then edit it, close, and select again and get the same dialog, the third one will refer to the same sprite. This can help when editing nearly identical sprites.

Setting an Exit Point

Every world must have at least one exit door somewhere (a Sprite defined as being an Exit Door). The exit sprite is never drawn or interactive until all red keys have been collected in the world. When Bonzo grabs the last red key, the bonus timer starts. It ends, along with the level and scoring, when he touches the sprite designated as the Exit Door. A couple notes:

1. A level may have multiple exit doors, even on the same screen. They all behave the same. Once all red keys are collected, they all become active.
2. A level with no exit doors is unbeatable. Don't do that.

The Bonus Level

Creating a bonus level entails three things:

1. Creating at least one blue key in the world.
2. Specifying the id of the bonus level in Special->Set Bonus Screen...
3. Creating sprites of type 'Bonus Door' to allow Bonzo to transport to the bonus screen and back.

Bonus doors have a similar property to exit doors; they are all invisible until the last blue key is collected. At that point, all Bonus doors become active. What they do when Bonzo touches them depends on the circumstances. If Bonzo has not yet gone through a bonus door, then touching one will transport him to the bonus screen (at the defined starting location, see 'Starting Location Placement' for more information). Once he has transported to the bonus screen, touching a bonus door will now transport him back to the screen which contained the bonus door that he touched originally (also at the defined starting location).

Essentially, Bonzo has two states, in the bonus level, and not in the bonus level. Going through a bonus door swaps those states and transports Bonzo either to the bonus level, or to the level with the door he originally went through. If the bonus level connects to the main level... this can cause weird situations, so it is probably a good idea to not have the two sections of the world connect.

Some Notes:

1. A level is not limited to just 2 bonus doors (the bonus level entrance and exit). There can be any number of doors, and they are subject to the above rules. Any door in the main world will transport Bonzo to the bonus level. Any door in the bonus level will return Bonzo back to the same Bonus door he originally used to get in.
2. If a bonus level is provided, it is probably a good idea, for gameplay reasons, to have a way out. This means at least one bonus door to get in, and one bonus door to get out.
3. If somehow the bonus level specified in Special->Set Bonus Screen... refers to a non-existent level (it was deleted or it was never set from the default) touching a bonus door will do nothing. This is better than a crash but is probably not useful in any way.

Starting Location Placement

For each level, Bonzo has a 'starting location'. This defaults to 0,0 (top left) and can be modified with a special brush from Special->Place Bonzo. Every level has a 'starting location', and this is relevant for different reasons. In order of importance:

1. Level 1000: Gameplay always starts here, so the starting location defined here is essentially the true starting location for the world.
2. Bonus Level and Levels with Bonus Doors: If a level is defined as a bonus level, then Bonzo always transports to that level at the specified starting location. Likewise, when returning from the bonus level to the level that contained the bonus door he originally entered, he will be placed at the starting location.
3. Respawn: The Respawn rules are a bit complex and may require modification. At a basic level, when Bonzo dies he must respawn somewhere, preferably somewhere safe. The game backtracks through levels and locations he was to find a place to respawn him, typically based on where he was. In cases where this algorithm fails, the last resort is to place him at a starting location on either the screen he died on or a past screen.

Final Touchups for Level Editing

There are a few more assorted functions for editing levels.

Background

https://github.com/ErikaRedmark/redmark_wiki_images/blob/master/monkey_shines/level_editor/background_selector.png Go to Screens->Change Background... to modify the background used for that level

Copy/Paste

https://github.com/ErikaRedmark/redmark_wiki_images/blob/master/monkey_shines/level_editor/copy_screen.png A level can be copied, wholesale, to another location. This can help when re-arranging large parts of the world without having to recreate the levels from scratch at different locations. Go to Screens->Copy Screen To... and select the source level (defaults to the current level) and the destination level to copy to. If the destination already exists, a dialog will ask you if you are sure before continuing. Copying over an existing level basically will delete the original, so be careful.

Reset Screen

Resets the screen as if Bonzo just entered the screen. When editing, Sprite movements and hazard animations (along with other animations) can become out-of-sync. Adding sprites to a level whilst other sprites are moving will create a false picture of that the screen will look at when initially loaded. Use this typically after editing sprites to get an idea how their movements synchronise.

Show Coordinates

Press the 'c' key whilst working in the main level editor canvas to show/hide the coordinate display at the lower left corner. This display mainly intended to make it easier to line things up between level screens. Instead of having to count tiles, you can just bring up the coordinates and see what y or x level some horizontal or vertical construction ends so you can continue it in the next screen.

Author, Author

A level can have an author information embedded into it. Go to Special->Author... and type whatever information you want to embed in the level about yourself (intended mostly for your name).

Templates

https://github.com/ErikaRedmark/redmark_wiki_images/blob/master/monkey_shines/level_editor/template_empty.png

Templates are a completely new concept that was not in the original level editor, and may be a bit complicated to use at first. The intention is to make editing levels easier when dealing with multi-blocks. For example, look at the trees in 'In The Swing' or even the left-right side blocks in 'In The Drink' that make up the majority of the levels. These are tiles that are designed to go together. They don't always, but in most cases they do. Templates allow you to define a set of tiles to be drawn together, at once, that can then be selected as a brush and painted whole-cloth onto a level.

Templates are saved separately from the world, as they are not part of the actual game, but rather meta-data for the level editor. They are intended only to help design levels quicker.

Each world has it's own template entry. When creating templates, a file will be created in the same folder as the Level Editor. It is important to not move or delete this file (or move the level editor to another folder on the computer) to keep the templates you define for your worlds.

The Template palette has two primary sections: The left side which is a list of all the templates you have defined, and the right side for creating new templates and editing existing ones.

To create a new template:

1. Check the button underneath the mini tilemap editor for the word 'Save'. If it says 'Overwrite' then click the 'New' button for a new template.
2. Use the standard palette you would normally use for editing the level, but instead draw into that mini tilemap editor. You cannot draw Goodies or define Sprites here.
3. To change the size of the tilemap, use the arrows on all sides. The arrows either expand in that direction, or contract in that direction.
4. Click 'Save' under the tilemap to create a new template.
5. Click 'Save Templates' in the bottom of the palette to write the changes to the preferences file.

To edit an existing template:

1. Click 'Edit' on the bottom of the palette.
2. Click on the template you wish to edit.
3. The mini-tilemap should be initialised to that template and can be modified. The button will change from 'Save' to 'Overwrite'
4. Make modifications and click 'Overwrite'
   1. At any time you can click 'Edit' and a new template, or 'New', to destroy changes you are making.
5. Click 'Save Templates' to write out changes.

To draw a template:

1. Ensure that none of the buttons at the bottom are 'stuck' (Edit and Remove) otherwise clicking a template will have the wrong effect.
2. Click the template you want to draw to the level.
3. Draw the template to the level as you would draw any other tile. Template drawing starts at the top-left of the template.

https://github.com/ErikaRedmark/redmark_wiki_images/blob/master/monkey_shines/level_editor/template_usage.png

To delete a template:

1. Click 'Remove'.
2. Click the template to delete.
3. Click 'Save Templates to write out changes.

When creating a new template, keep in mind: the size of the tilemap editor is not always the size a template will be created as. Extra space on the top and left of your actual tiles is part of the template, but extra space to the right and bottom is clipped when the template is saved. For example, lets pretend we have a template that is just two tiles, a left and right side of some solid tile. | | is an empty space, |X| is a tile:

|x|x| |
| | | |
| | | |

The tilemap is 3x3, but the template created is 2x1. The extra rows and cols are removed because they are not needed. Contrast this with:

| | | |
| |x|x|
| | | |

The tile map is 3x3, and the template created will be 3x2. The extra row at the top is preserved, as is the extra column to the left. The only thing clipped is the bottom.

Point is: Start your template at the top-left unless extra space is intended.

Final Editor Words

Save early and often, and keep backups of your work.