Sonic the Hedgehog (8-bit)

This is the Sonic Community Hacking Guide for Sonic the Hedgehog. The Guide is based on notes by David Declerck.

ROM Map

Here is a small ROM Map. It lists the general sections of the Sonic 1 GG ROM.

Offset	Description
$00000 - $10000	Main Game Code, musics, sounds...
$10000 - $14D00	32x32 Mappings
$14D00 - $15200	Unknown
$15200 - $15600	Blinking Items Art (Box, etc...)
$15600 - $1564A	Level Headers Pointers
$1564A - $15B34	Level Headers
$15B34 - $16200	Sprite Layout
$16200 - $16738	Unknown
$16738 - $17430	Misc Mappings
$17430 - $1F600	Level Layout
$1F600 - $20000	Sega Screen Art / Mappings
$20000 - $23400	Sonic Art / Mappings
$23400 - $23450	Palettes Pointers
$23450 - $23C00	Palettes
$23C00 - $25500	'Sega' sound
$25500 - $30000	Art : Title Screen / Map / Levels / Stats / Sprites
$30000 - $40000	Art : Sega Screen / Map / Levels
$3DA28 - $40000	Contains sprite art and/or sprite mappings

32x32 Mappings

The floor layout for each level is comprised of a 32x32 tiles. Each of these 32x32 tiles are composed of 16 smaller 8x8 tiles. From the begining of the data, each set of 16 bytes contains the mappings for a single 32x32 tile.

Here is a 32x32 tile:

And the corresponding data are:

00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F

Mappings Offset	Description
$10000 - $10BB0	Green Hill (187 tiles)
$10BB0 - $11510	Bridge (150 tiles)
$11510 - $11D10	Jungle (128 tiles)
$11D10 - $12A10	Labyrinth (208 tiles)
$12A10 - $135B0	Scrap Brain (186 tiles)
$135B0 - $14330	Sky Base 1-2 (216 tiles)
$14330 - $149B0	Sky Base 3 (104 tiles)
$149B0 - $14D00	Bonus Stage (53 tiles)

Level Headers / Level Headers Pointers

Each level has a header. This header contains several pieces of data, such as starting position, music location, etc. Each level header is 37 bytes long and is referenced by a pointer.

Level Headers Pointers

A level header pointer is comprised of two bytes. The data for the pointer is stored in little endian format. The value stored by this pointer specifies the number of bytes away a level header is from 15600.

Level Header Pointers are located at: $15600 - $1564A

Example: The two first bytes are 4A 00. So, at $15600 + $004A, we will find the level header for the first level (Green Hill 1).

Level Headers

Each level header use 37 bytes. Here is the format (partial):

SP ?? ?? ?? ?? ?? ?? LW LH ?? ?? ?? ??

SX SY FL FL FS FS ML ML LA LA ?? SA SA

IP ?? CC CP SL SL ?? ?? ?? ?? MU

• SP (Solidity Pointer): Indicates what solidity data to use
• LH,LW (Level Height, Level Width): Level dimensions
• SX,SY (Start X, Start Y): Player starting position
• FL (Floor Location): How many bytes away from 14000 the floor is located (Little Endian)
• FS (Floor Size): Floor data size, in bytes (Little Endian)
• ML (Mappings Location): How many bytes away from 10000 the mappings for this level are located (Little Endian)
• LA (Level Art): How many bytes away from 30002 the level art is located (Little Endian)
• SA (Sprite Art): How many bytes away from ????? is the sprite art located (Little Endian)
• IP (Initial Palette): Indicates the number of the initial palette pointer to use, in the pointer order of appearance (so, indicates the palette)
• CC (Color Cycles): Indicates the number of color cycles for the level palette (see 8. Level Palettes)
• CP (Cyclic Palette): Indicates the number of the cyclic palette pointer to use, in the pointer order of appearance (so, indicates the palette)
• SL (Sprites Location): How many bytes away from 15580 is the sprite layout located (Little Endian)
• MU (Music):
  • 00-05: Level Musics
  • 06: Title Music
  • 08: Invincibility
  • 09: Level Complete
  • 0A: Dead
  • 0B/OC/OD: Boss
  • 0E: Credits

Level Headers are located at $1564A - $15B34

Sprite Layout

Sprites are special parts of a level. They can move, attack, give you rings, and do a lot of other things, even if they are not visible.

The data for each sprite uses 3 bytes. Here is the format:

OO XX YY

XX and YY are the object's coordinates. OO is one of the object listed below (they are from the SMS hacking guide, not sure thay are the same):

ID	Description
00	Empty (no object)
01	Super Ring monitor
02	Power Sneakers monitor
03	One-Up monitor
04	Shield monitor
05	Invincibility monitor
06	Chaos Emerald
07	End sign
08	Badnik "Crabmeat" (GH)
09	Wooden platform - Swinging (GH)
0B	Wooden platform (GH)
0C	Wooden platform - Falls when touched (GH)
0E	Badnik "Buzz Bomber" (GH/B)
0F	Wooden platform - Sliding left-right (GH)
10	Badnik "Moto Bug" (GH)
11	Badnik "Newtron" (GH)
12	Robotnik - Green Hill Boss (GH)
16	Flame Thrower (SB)
17	Door - Opens from left only (SB)
18	Door - Opens from right only (SB)
19	Door - Two ways (SB)
1A	Electric sphere (SB)
1B	Badnik "Ball Hog" (SB)
1C	Unknown - Ball from the "Ball Hog" ?
1D	Switch (SB, L, others ?)
1F	Badnik "Caterkiller" (SB)
21	Bumper - Sliding left-right (Bonus Stage ?)
22	Robotnik - Scarp Brain Boss (SB)
23	Free animal - Rabbit
24	Free animal - Bird
25	Animal Cell
26	Badnik "Chopper" (J, B)
27	Vertical Step - Falling from a waterfall (J)
28	Horizontal Step - Falling from a waterfall (J)
29	Floating Step - Sonic can travel with it (J)
2D	Badnik "Yadrin" (B)
32	Badnik "Bomb" (SKYB)
35	Badnik "Unidus" (SKYB)
37	Rotating cannon (SKYB)
38	Flying platform (SKYB)
39	Spiked wall slowly moving right (SKYB)
3B	Flying platform moving up-down (SKYB)
3C	Badnik "Jaws" (L)
3D	Rotating spiked ball (L)
3E	Spear, shifting up-down (L)
3F	Fire ball thrower (L)
44	Badnik "Burrobot" (L)
45	Platform, move up when touched (L)
46	Unknown - Seems to load some tiles
48	Robotnik - Bridge Boss (SB)
49	Robotnik - Labyrinth Boss (L)
4A	Robotnik - Jungle Boss (J) ?
4B	Zone that makes you fall (like in GH2)
4C	Flipper (Bonus Stage)
4D	Reset!
4E	Balance (B)
4F	Reset!
50	Flower (GH)
51	Box - Starpost
52	Box - Continue
53	Final animation in GH, when Sonic falls on Robotnik (then, goes to the next level)
54	Emeralds animation (on the map), when Sonic has them all (and goes to the next level)
55	Makes Sonic blink for a short time

It seems that no more sprites are defined.

Use the Level Headers to determine where are the sprites located at.

The compression format

Some data in the ROM is compressed using a rather weird but easy to understand format. This compression format is used to compress levels and some mappings (see section 7).

The compression format is based on a simple principle : if several successive bytes are identical, space can be saved by specifying how many times that byte is repeated.

The algorithm for compressing data is as follows :

-> While two successive bytes are different

-> Bytes are stored without any compression

-> If two or more successive bytes are the same

-> The byte repeated is written twice

-> The number of times the byte is repeated, minus 1, is calculated. The result is written as a third byte.

An explanation about this 'minus 1':

During decompression, when the game find two identical bytes, it writes the first one, and then it writes the second one X times, where X is the value of the third byte.

Example:

06 7C 32 2E 2E 01 D1 -> 06 7C 32 2E 2E D1

6B 3F 3F 02 51 2D C0 -> 6B 3F 3F 3F 51 2D C0

05 07 5A 5A 03 08 B2 -> 05 07 5A 5A 5A 5A 08 B2

As you can see, this format wastes one byte of space if a byte is only repeated twice. If a byte is repeated three times, there is no size difference. Only when a byte is repeated four or more times is there a savings in space usage.

Floor Layout

The floor layout is composed of multiple 32x32 tiles. Each byte indicates the number of the tile to which to use. However, the data is compressed, so you will have to decompress it first (see 5. The compression format). Be careful when compressing and decompressing a level, because it's easy to make it corrupt.

Floor layouts are located at: 17430 - 1F600 You'll have to use the pointers (Level Headers), in order to determine their starting address.

Misc Mappings

This section contains the mappings for some screens. It looks like the 32x32 Mappings, except that the 8x8 tiles are written to the screen, so there is more than 16 tiles. Another thing is that they are compressed (see 5. The compression format).

Mappings Offset	Description
$16738 - $16865	Title Screen
$16962 - $163F6	Map 1 Background
$163F6 - $16AFD	Map 1 Foreground

Level Palettes / Level Palettes Pointers

Level Palettes Pointers

This is an easy section, but reading the Level Headers section may help you a bit. Well, you probably noticed that levels generally have the same palettes for the three acts (the exception is Sky Base). If you use MEKA, you can see that a palette is composed of 32 colors. We can divide this palette into two 16 colors sub-palettes (the first one for colors 1-16, the second one for colors 17-32). When the GG loads a level, it loads the initial palette, which contains 16 colors (colors are applied to the second sub-palette). Then, while you are playing, you can see that there are color cycles. In fact, the GG switch between several palettes, so you think that there is a cycle. These palettes contains only 16 colors, and are applied on the first sub-palette only. All these palettes are all referenced by a pointer, which is 2 bytes long, and little endian. There are 8 pointers (16 bytes, little endian). They point to the level color cycles. The 16 next pointers are still unknown. The 8 next are blank pointers. Finally, The 8 next pointers point to the level initial palette. Pointers represent how many bytes away from 23400 are the palettes located at.

Palettes Pointers are located at : 24000 - 24350

Initial level palettes pointers:

Offset	Description
$23440	Green Hill
$23442	Bridge
$23444	Jungle
$23446	Labyrinth
$23448	Scrap Brain
$2344A	Sky Base 1/2A
$2344C	Sky Base 2B/3
$2344E	Special Stage

Level palettes color cycle pointers:

Offset	Description
$23400	Green Hill
$23402	Bridge
$23404	Jungle
$23406	Labyrinth
$23408	Scrap Brain
$2340A	Sky Base 1/2A
$2340C	Sky Base 2B/3
$2340E	Special Stage

Level Palettes

Now that you know everything about palettes pointers, you can start the palettes. There is just one thing you must remember : initial palettes always contain an half-palette (16 colors). Color cycles can contain a variable quantity of half-palettes (16 colors applied to the first sub-palette). This variable quantity corresponds to the CC parameter in the level header. OK, now, let's start.

The GG uses 9-bit colors, so, each color use two bytes (the first nibble of the second byte is 0, and values for a nibble are set 2 by 2). This color can be defined like that : R(0-7), G(0-7), B(0-7). So, there are only 8 possible values for each primary color. Here are the RGB correspondence : 0=1=0, 2=3=36, 4=5=72, 6=7=109, 8=9=145, A=B=182, C=D=218, E=F=255. So, you can have a maximum of 512 colors.

The format for the two bytes is : GR 0B

Blinking Items Art

In the game, there are some blinking items. The most common are the box items. You can easily edit them. Each of these items is 16x16, but you must understand that it is composed of four 8x8 tiles. The tiles are displayed from up to down and from left to right. The format is the same as the art in savestates (32 bytes for each 8x8 tile, 128 bytes for the item). For more information, refer to the S1 SMS Savestates Hacking Guide.

Blinking items are located at : 15200 - 15600

Here are the items you can edit :

ID	Description
1	Super Rings
2	Power Sneakers
3	One-Up
4	Shield
5	Invincible
6	Chaos Emerald
7	Starpost
8	Continue

Level Art

This is a quite difficult section, because the level art is compressed in a very strange way. The compression format itself is not so difficult to apply, but learning it is not a piece of cake. First, I'll describe each part of the level art, then I'll give more details.

The level art starts at : 32ED5

The level art is composed of 8x8 tiles, which are used by the 32x32 mappings. These 8x8 tiles are composed of 8 lines of art data. In other terms, the compression format relies on the fact that these lines can be used by several different tiles. So, these lines will be written to the art data only once. During decompression, the game will use two methods to write the lines to the tile. One is bit-based, but doesn't allow to choose what line of art data to write to the tile; the second one is byte-based, and it allows to choose the line of art data to write to the tile. The game use both methods. It is very important that you understand this paragraph, so read it again.

From what I said, you can guess that there will be 3 sections for each level. But, there is also an 8 bytes header at the beginning (for each level too). The second section is what I call "Line Pre-load" (the most complex section, containing bit-based compressed data), the third one is "Line Selection" (containing the byte-based compressed data), and the last one is "Art Data".

The header contains infos on all the data, but I haven't figured out how it works. I know that the fith byte has something to do with colors.

The Art Data section simply contains the lines of art data. Each line is 8 pixels wide, and uses 4 bytes. The format is described in the S1 SMS Savestates Hacking Guide. Note that there won't be two identical lines of art data here (it's evident if you followed what I said).

Now, the most complex section, the Line Pre-load. It's 256 bytes (one byte for each tile). A 1 byte number can be converted to a 8-bit number. Yeah, 8-bit, and there are 8 lines in a tile. So, each bit will be associated with a line of the tile. The rightmost bit will be associated to the topmost line of the tile. So, the byte will be read from right to left. Note that before starting to load the art, the GG puts a pointer at the begining of the Art Data. While reading the byte, each time the GG meets a 0, it will write the pointed line of art data to the tile, at the position indicated by the position of the 0, and move the pointer to the next line of art data (don't forget that 1 line of art data = 4 bytes). The process repeats until all the bytes were read. As for now, we have 256 partial tiles.

The last section is the Line Selection. As you know, we have partial tiles. We need to put something in the blank lines. For each tile, there is a certain quantity of lines that were not defined. We will call that quantity L. To calculate L, simply count the number of 1's there is in the corresponding byte in the Line Pre-Load section. Well, now you can start reading the data in Line Selection. This section contains line numbers. You must read L line numbers for each tile (remember that L depends on the tile). Each line number indicates a line of art data to write to the tile. These lines must be written were no lines were defined. To determine where to write the lines in the tile, use the positions of the 1's in the corresponding byte in the Line Pre-Load section. The last thing you must know is the format for each line number. This is a bit special. For line numbers 00 to EF (0 to 239), there is only one byte, indicating the line number. However, for tiles after EF, there are two bytes. The first one starts with an F, so the actual line number is the two bytes number minus F0 00. Ex : F3 A2 is for art line number 3A2. Note that you can also write line numbers 00 to EF using two bytes numbers, but this is a waste of space (that's why they are stored with one byte !).

Well, that was hard to explain. And it is hard to understand, yeah. I have another method, I'll give you it soon.

Offset	Description
$32ED5 - $32EDD	Header for Green Hill Art
$32EDD - $32FDD	Line Pre-Load for Green Hill
$32FDD - $3364E	Line Selection for Green Hill
$3364E - $344AE	Green Hill Art Data