KiddEd
Project Homepage: https://kidded.emulicious.net
Discord Server: https://discord.gg/DTVx5Da

This program is distributed under the attached license. See License.txt.

=======================
Required Runtimes
=======================
Java 6 or newer:
http://www.java.com

=======================
Release Notes
=======================
This version is an open beta. It's not complete yet and work is still in progress.
That also means you should expect bugs. In order to fix these bugs as soon as
possible I rely on bug reports. So whenever you encounter a bug please let me know.
If anything breaks don't get frustrated. Just save your changes as an ips file and
send it to me along with a description of the problem. I'll then try my best to fix
the issues and restore as much of your changes as possible.

=======================
Supported ROMs
=======================
KiddEd supports editing Alex Kidd in Miracle World [v1] (also known as Alex Kidd in Miracle World (V1.1)).

It does NOT support editing Alex Kidd in Miracle World [v0] (also known as Alex Kidd in Miracle World (V1.0)) and
the BIOS version of Alex Kidd in Miracle World.

=======================
Editors
=======================
1. Level Editor
2. Palette Editor
3. Tile Editor
4. Tileset Editor
5. Sprite Tileset Editor
6. Metatileset Editor
7. Sprite Editor
8. Box Content Editor
9. Game Settings
10. Level Settings
11. Name Table Editor
12. Title Screen Editor
13. Shop Editor
14. Janken Match Editor
15. Riddle Editor
16. Text Editor
17. Physics Editor
18. Sound Editor

-----------------------
1. Level Editor
-----------------------
The Level Editor allows you to manipulate the layout and the entities of a level.
You can either use the scrollbars, the arrowkeys or the mousewheel to navigate through the level.
Pressing the Home/Pos1 key on your keyboard will navigate to the screen Alex starts in.
The Level Editor starts in Entity Editing Mode indicated by the pushed button with Alex drawn on it on the toolbar.
The other mode provided by the Level Editor is the Layout Editing Mode. It can be accessed by pressing the button
with the star box on it on the toolbar.

1a) Entity Editing Mode
In Entity Editing Mode you can select an entity by clicking on it with the left mouse button.
The selected entity can be moved by dragging your cursor.
The selected entity can be deleted by either clicking on the button with the cloud of dust drawn on it or by pressing
the delete key or the backspace key on your keyboard.
Clicking on an Entity with the right mouse button will open a dialog that allows changing the properties of the selected
entity.
In that dialog you can also specify the priority of the selected entity. The priority comes into play when there are
too many entities loaded at the same time. The engine can only handle up to 10 entities at the same time.
So for example when there currently are 8 entities active and a new screen is loaded that has more than 2 entities,
then only the 2 entities with the highest priority are loaded and the remaining entities won't appear at all.
Additionally, there are special priorities (i.e. Top, Top A and Top B). There can be at most one entity active with
priority set to Top. When a new entity with priority set to Top is loaded it overwrites the previous entity
with priority set to Top.
The priorities Top A and Top B play together. There can be at most 2 entities active with their priorities set to
Top A or Top B. If either Top A or Top B priority is free, a new entity with priority Top A is loaded into that free slot.
If both Top A and Top B are already occupied by active entities then always Top B will be overwritten with new entities
that have their priority set to Top A or Top B.
At the right of the window you will find a list of entities. You can drag an entity from this list and drop it
onto the screen to insert it at the specified position.
The game doesn't allow entities on the screen Alex starts in.

1b) Layout Editing Mode
In Layout Editing Mode you can "draw" the layout using your left mouse button. The metatile to be drawn can be selected
from the Metatileset found at the right of the window. Holding the ALT key on your keyboard while clicking on a metatile
in the level will function like a pipette: The clicked metatile will be selected as the metatile to be drawn.
When holding down the CTRL key you can edit the hidden tiles that will be spawned by the 4B trigger. By default it removes
hidden tiles. If you want to add hidden tiles you need to press the SHIFT key as well.

-----------------------
2. Palette Editor
-----------------------
The Palette Editor allows you to manipulate the palettes used in the game.
Clicking on one of the colors will open a Color Chooser. The Color Chooser provides all colors
that are available on the SEGA Mastersystem. To replace the selected color by a new color simply
click on the desired color in the Color Chooser.
The Palette Editor also allows extracting a palette from an image. This can be done by copying an image to the clipboard
and pasting it as a palette.

-----------------------
3. Tile Editor
-----------------------
The Tile Editor allows editing all the tiles found in the game.
In the game tiles and palettes are sperated. That means that the same tile could be drawn using different palettes.
So you should make sure that your tiles look correct in all palettes the game might use for drawing your tile.
You can select multiple tiles by holding the CTRL key on your keyboard while clicking on the tiles you want to select.
You can draw pixels using the left mouse button. You can select the color to be drawn from the palette at the bottom of the window.
Holding the ALT key on your keyboard while clicking on a pixel will function like a pipette:
The color of the selected pixel will be selected from the palette.
To move all pixels into one direction you can press the arrow keys on your keyboard while holding the CTRL key.
For background tiles you can select between Palette 0 and Palette 1. This selection does only change the palette used to
show/draw the tile. The actual palette to be used for this tile must be selected in the metatile/nametable the tile is used in.

-----------------------
4. Tileset Editor
-----------------------
The Tileset Editor allows editing the tilesets for the levels.
Due to the limited amount of video memory available on the SEGA Mastersystem the game organizes tiles as sets.
These sets can be edited in the Tileset Editor. Each level has 2 tilesets. A level tileset for the background and
a sprite tileset for the entities. The level tileset consists of a main tileset and additional tilesets;
the sprite tileset consists of multiple smaller sprite tilesets.

-----------------------
5. Sprite Tileset Editor
-----------------------
The Sprite Tileset Editor allows editing the small sprite tilesets that make up a sprite tileset for a level.
Using the drop down box you can select the sprite tileset to edit.
The panel right below of it is used to specify where the sprite tileset should be placed within a level's sprite tileset.
A sprite tileset consists of up to 3 sequences of tiles. A sequence of tiles can either be a regular sequence of tiles,
a sequence of mirrored tiles or a sequence of invisible tiles. Invisible tiles can be used for creating invisible
sprites.

-----------------------
6. Metatileset Editor
-----------------------
The Metatileset Editor allows editing the metatiles used to form the layout of a level.
At the left of the window you can see the metatileset. Each metatile in this set is made of 4 tiles.
At the right you can see the details of the selected metatile. At the top you will find the metatile scaled up.
In this scaled up metatile you can select the single tiles that make up the metatile by clicking on it with the left mouse button.
At first all 4 tiles are selected. In this case the shown properties reflect the properties of all 4 tiles of this metatile.
Otherwise the shown properties reflect the properties of the selected tile of this metatile. At the bottom you will find the
selected tileset. If one of the tiles of a metatile is selected you can replace it by one of the tiles from the tileset by
clicking on the desired tile.
Clicking on a metatile with the right mouse button will open the tiles of this metatile in the Tile Editor. (Only works
for a few metatiles so far!)

-----------------------
7. Sprite Editor
-----------------------
The Sprite Editor allows editing all sprites of the game.
Most sprites are made of multiple tiles. In this editor the arrangement of these tiles within a sprite can be changed.
This can be done by dragging a tile around with the left mouse button. The white cross in the middle of the screen
indicates the origin of the sprite.
At the right of the window you will find a list of frames that make up the animation of the selected sprite.
Clicking on one of these frames with the left mouse button selects the clicked frame allowing its editing.
Clicking on one of these frames with the right mouse button opens the tiles of the sprite in the Tile Editor.
You can also select a hitbox for the selected sprite. A hitbox is used for collision detection. A collision is detected
whenever two or more hitboxes overlap. You can make the hitbox of the current sprite visible by enabling the corresponding
toggle button in the toolbar. It will show up as a green box. A hitbox is denoted as a 4-tuple: [x, y, w, h]
The values have the following meanings:
x : the x-coordinate relative to the sprite's origin (the white cross)
y : the y-coordinate relative to the sprite's origin (the white cross)
w : the width of the hitbox
h : the height of the hitbox
Hitboxes can be edited in the Hitbox Editor. The Hitbox Editor can be accessed from the Sprite Editor's Edit menu.
There you can select a hitbox and change its values.
The Hitbox Editor is just a draft and will be redesigned in a future release.

-----------------------
8. Box Content Editor
-----------------------
The Box Content Editor allows changing the contents of the boxes with a question mark on them.
The game uses an index to decide what item to create when a box with a question mark on it is broken.
Whenever one of these boxes is broken the indexed item is created and the index is increased by 1.
When a level starts this index is set to the level's box index.
The Box Content Editor indicates the level's box index by a red border around the corresponding box content.
This index can be set by clicking on the desired box content.

-----------------------
9. Game Settings
-----------------------
In Game Settings you can set initial game values like the amount of lives, the amount of money and the score to start with.
There you can also set the level to start in.

-----------------------
10. Level Settings
-----------------------
In Level Settings you can setup whether to update the water color (cycle through white-cyan-magenta), what tiles to animate,
what music to play, what shop to use and what metatileset to use for the level layout.
It also allows converting the level layout to either vertical layout, horizontal layout, horizontal reverse layout, L shape layout, river layout or jar layout.
The vertical layout is used in the last level of the game. The game will scroll downwards.
The horizontal layout is used in many levels. For example in the 2nd level. The game will scroll to the right.
The horizontal reverse layout is used in level 0D (the 13th level). The game will scroll to the left.
The L shape layout is used in the first level. The game will scroll downwards first then to the right.
The river layout is used in levels 05 and 09. The layout has up to 16 screens on top of the water and 4 screens of water. When the vehicle of Alex is destroyed he will fall into the water.
The jar layout is used in the 3rd level. The game scrolls to the right but you can also swim through a jar to reach another screen.

-----------------------
11. Name Table Editor
-----------------------
The Name Table Editor allows changing name tables and works in a very similar way to the Metatileset Editor (see 5. Metatileset Editor).
Name tables are arrangements of tiles that make up an image like for example the map and the shop.
The title screen is made up of multiple name tables that appear one by one.

-----------------------
12. Title Screen Editor
-----------------------
The Title Screen Editor allows changing the title screen.
The Title Screen Editor starts in Entity Editing Mode indicated by the pushed button with Alex drawn on it in the toolbar.
The other mode provided by the Title Screen Editor is the Layout Editing Mode. It can be accessed by pressing the button
with the star box on it on the toolbar.

1a) Entity Editing Mode
In Entity Editing Mode you can select an entity by clicking on it with the left mouse button.
The selected entity can be moved by dragging your cursor.
The selected entity can be deleted by either clicking on the button with the red cross drawn on it or by pressing
the delete key or the backspace key on your keyboard.

1b) Layout Editing Mode
In Layout Editing Mode you can select a nametable by clicking on it with the left mouse button.
The selected nametable can be moved by dragging your cursor.
Clicking on a nametable with the right mouse button will open the nametable in the Name Table Editor.

-----------------------
13. Shop Editor
-----------------------
The Shop Editor allows changing the items being sold in the shops and provides an Item Editor to change the price of each item.
Clicking on an item in the shop with the left mouse button will select it. You can also select an item using the
arrowkeys left and right on the keyboard. The selected item can be changed using the arrowkeys up and down on the keyboard.
The Item Editor can be accessed from the Edit menu. There you can change the prices of the items.

-----------------------
14. Janken Match Editor
-----------------------
The Janken Match Editor allows changing the decisions made by Janken and his henchmen and their greeting messages.
You can select a decision either by clicking on it with the left mouse button or using the arrowkeys left and right on your keyboard.
The selected decision can be changed using the arrowkeys up and down on your keyboard.
The game uses a global index to choose which decision to take from the table of decisions of the current opponent.
This index starts at 0 and is frequently increased in the countdown phase of a janken match. The change of this index can
be observed when the player owns the item telepathy ball. This index is never reset throughout the game - only when a
new game is started.

-----------------------
15. Riddle Editor
-----------------------
The Riddle Editor allows changing the sequence of symbols to trigger in order to spawn the crown in the last level of the game.
You can select one of the symbols either by clicking on it with the left mouse button or using the arrowkeys left and right on your keyboard.
The selected symbol can be changed using the arrowkeys up and down on your keyboard.

-----------------------
16. Text Editor
-----------------------
The Text Editor allows changing all of the text in the game.
You can use the arrowkeys on your keyboard to move the cursor and just type in the text as desired using your keyboard.
You can also move your cursor to a specific position by clicking on it using your left mouse button.
To delete the character on the cursor position you can press the delete key on your keyboard.
To delete the character before the cursor position and afterwards move the cursor to the left you can press the backspace key on your keyboard.
At the bottom of the editor you can find an editor that allows to edit textboxes freely.
It uses control sequences to move the cursor filling the path it travels.
Control sequences start with a backslash '\' followed by the direction into which to move the cursor.
The direction can be one of the following letters:
r - right
d - down
l - left
u - up
A control sequence is completed by a number right after the direction. This number specifies the amount of characters to travel.
Example: \r28 means travel to the right by 28 characters

-----------------------
17. Physics Editor
-----------------------
The Physics Editor allows changing the physics of Alex, his vehicles, enemies and missiles.
Acceleration is applied as long as a button is pressed. When the button is released Deceleration is applied.
The Acceleration will stop accelerating as soon as the velocity has reached Max Velocity.
Opposite Acceleration is the acceleration in the opposite direction. This is for example when Left is pressed while Alex is still walking to the right.
In the View menu of the Physics Editor you can choose what units should be used for the values of the physics.
The units can either be based on subpixels (spx) with 256 spx = px or on full pixels.

-----------------------
18. Sound Editor
-----------------------
The Sound Editor allows playing, exporting and changing all sounds of the game.
You can export sounds in PSGlib format by selecting a sound from the drop down box and pressing the "Export Sound" button.
To change sounds you will first need to replace the Sound Engine by selecting "PSGlib Sound Engine" from the drop down box and pressing the "Apply" button.
After that you can select the sound you want to replace and press the "Import Sound" button to choose a file to import.
KiddEd supports the following file formats:
.psg which can be created using PSGlib (https://github.com/sverx/PSGlib)
.vgm which can be created using emulators or trackers (you can find a collection of VGM files on http://www.smspower.org/Music/VGMs)
By pressing on the "Restore Sound" button you can replace a sound by the original sound.
You can also remove sounds by pressing the "Remove Sound" button. The sound slot will remain but the sound will be silenced.
Furthermore, for sound effects you can set a priority. This priority is considered when a sound effect is triggered while another sound effect is playing.
In this case, the new sound effect will only play if its priority is equal or higher to the priority of the sound effect that is currently playing.
The new sound effect will then cancel the current sound effect and start playing instead.
For music you can setup if the music should loop (this can only be setup when using the PSGlib Sound Engine).