Sonic the Hedgehog 3 & Knuckles ROMulan Package

Sonic the Hedgehog 3 & Knuckles ROMulan Package

The files contained herein are for use with ROMulan and SonED2, to provide a means of editing the levels of "Sonic the Hedgehog 3 & Knuckles".

Please visit the official forum for discussion on mods made using this package, to submit additions to the scripts, or to report any errors in the official distribution.

Setup and Basic Usage

File Listing

Game Notes

Tile Paging and Shared Level Data
Animated Tiles and Palettes
Crossing Paths and Plane Priority
Spin Tunnels
Level Boundaries
Fixed and Dynamic Water Heights
Dynamic Level Changes
Boss Arenas
Level TitleCard Names

Special Options

Level Music Playlist
Level Boundaries
Cheat Codes
- Vine and Pulley
- Titlescreen

Setup and Basic Usage

This script set is "non-destructive". This means that the input game files will never need to be restored, as the Injection process never modifies them. Thus, all changes are applied to a clean copy of the game, and saved to a different file. The only time any of the initial steps will need to be repeated is if the separated data files have become corrupt, in which case, the Split will need to be performed again.

One-Time Setup Steps

Unpack all files from this archive into their own folder. The full path name of this folder must not contain any spaces
Place in the same folder copies of "Sonic the Hedgehog 3" and "Sonic & Knuckles" (not "Sonic 3 & Knuckles"), and give them the filenames "s3.bin" and "sk.bin", respectively
Run the included Batch File "3ksplit.txt" using ROMulan or SonED2's built-in ROMulan functionality to retrieve the game's data

Every Time Level Editing Steps

Using SonED2's "Open Project" option in the "File" menu, navigate to the "Projects" folder included with this fileset and open any of the included Project Files to edit its corresponding level

Make any changes using SonED2 as described in its own documentation

Use SonED2's "Save Project" option by selecting it in the "File" menu or pressing F3 to save the changes to their respective files (This is important as the edited data is SonED2-internal; ROMulan expects to find all necessary data in the files listed by the injector script)

Be aware that this script set does not currently support editing Tilesets. See the "Game Notes" section for more information.

Other Modifications

With the proper knowledge of the game, other changes can be made by modifying the two Batch Files and/or the Injector File "inmain.txt" as described by the ROMulan documentation. For relevant information, see the "Game Notes" section.
Some game settings are already available for modification in the Injector File "3kinopts.txt". See the "Special Options" section for details.

Every Time Finalization Steps

Run the included Batch File "3kinject.txt" using ROMulan or SonED2's built-in ROMulan functionality to inject the changes into the game
The file "inject.bin" will have been created and placed in the same folder as the "3kinject.txt" script. The process is now complete

File Listing

This section provides a complete listing of the folders and files included with this package, each with a brief description. Note that other files and folders will also appear in this folder after "split.txt" has been run, which belong to the data that was extracted from the game.

/_dlls - DLLs used by "derecmp.exe" for data compression and decompression

Enigma.dll	-	DLL used by "derecmp.exe", containing functions for compressing and decompressing data with the "Enigma" format
Kosinski.dll	-	DLL used by "derecmp.exe", containing functions for compressing and decompressing data with the "Kosinski" format
Nemesis.dll	-	DLL used by "derecmp.exe", containing functions for compressing and decompressing data with the "Nemesis" format

/incomplete - ROMulan files with incomplete support for additional data

3kintil.txt	-	An Injector File that deals with Tilesets. It is incomplete in that there are many more Tileset location references within the game that it does not correct, and thus, many places where the game will crash because the old data pointers will have been made invalid
ksplitp.txt	-	A Batch File for extracting several of the special Palettes that aren't loaded by the standard Palette Load List

/Project - This is the primary folder containing Object Listing Files and a full set of SonED2 Standard Level Project Files for "Sonic 3 & Knuckles", based on the data created by "3split.txt" and "ksplit.txt", both of which are run by "3ksplit.txt"

/objdef - Object Listing Files and supporting graphics files that define the Objects used in "Sonic 3 & Knuckles" for SonED2's Object Editor

s3obj.lst	-	Object Listing File, which defines Object descriptions, setting data, and in-editor graphic displays for Objects used in "Sonic 3"
s3obj1.pcx	-	Graphic file containing some of the global Object graphics for "Sonic 3"
s3obj2.pcx	-	Graphic file containing some of the Object graphics for Angel Island Zone
s3obj6.pcx	-	Graphic file containing some of the Object graphics for Launch Base Zone
skobj.lst	-	Object Listing File, which defines Object descriptions, setting data, and in-editor graphic displays for Objects used in "Sonic & Knuckles"
skobj1.pcx	-	Graphic file containing some of the global Object graphics for "Sonic & Knuckles"
skobj2.pcx	-	Graphic file containing some of the global Object graphics for Mushroom Hill Zone
ssobj.lst	-	Sonic 1 Special Stage Object Listing File, which defines Map "Object" descriptions and in-editor graphic displays for the Slots Bonus Stage
ssobj1.pcx	-	Graphic file containing the Sonic 1 Special Stage Map "Object" graphics for the Slots Bonus Stage

AIZ1.sep	-	Angel Island Zone Act 1
AIZ2.sep	-	Angel Island Zone Act 2
AIZ2Ship.sep	-	Angel Island Zone Act 2 (Ship Bombing Sequence)
AIZIntro.sep	-	Angel Island Zone Act 1 (Intro Sequence)
ALZ.sep	-	Azure Lake Zone
BPZ.sep	-	Balloon Park Zone
CGZ.sep	-	Chrome Gadget Zone
CNZ1.sep	-	Carnival Night Zone Act 1
CNZ2.sep	-	Carnival Night Zone Act 2
DDZ.sep	-	The Doomsday Zone
DEZ1.sep	-	Death Egg Zone Act 1
DEZ2.sep	-	Death Egg Zone Act 2
DEZBoss.sep	-	Death Egg Zone "Final Boss"
DPZ.sep	-	Desert Palace Zone
EMZ.sep	-	Endless Mine Zone
FBZ1.sep	-	Flying Battery Zone Act 1
FBZ2.sep	-	Flying Battery Zone Act 2
Gumball.sep	-	Gumball Bonus Stage
HCZ1.sep	-	Hydrocity Zone Act 1
HCZ2.sep	-	Hydrocity Zone Act 2
HPZ.sep	-	Hidden Palace Zone
HPMini.sep	-	Hidden Palace Zone (Emerald Shrine)
ICZ1.sep	-	Ice Cap Zone Act 1
ICZ2.sep	-	Ice Cap Zone Act 2
LBZ1.sep	-	Launch Base Zone Act 1
LBZ2.sep	-	Launch Base Zone Act 2
LBZ2DEZ.sep	-	Launch Base Zone Act 2 (Death Egg Launch)
LRZ1.sep	-	Lava Reef Zone Act 1
LRZ2.sep	-	Lava Reef Zone Act 2
LRZBoss.sep	-	Lava Reef Zone Boss Area
MGZ1.sep	-	Marble Garden Zone Act 1
MGZ2.sep	-	Marble Garden Zone Act 2
MGZ2Quak.sep	-	Marble Garden Zone Act 2 (Earthquake Section)
MHZ1.sep	-	Mushroom Hill Zone Act 1
MHZ2.sep	-	Mushroom Hill Zone Act 2
MHZ2FBZ.sep	-	Mushroom Hill Zone Act 2 (Flying Battery Sequence)
Pachinko.sep	-	Pachinko Bonus Stage
Slots.sep	-	Slots Bonus Stage (Background)
SlotsMap.sep	-	Slots Bonus Stage (S1 Rotating Special Stage Map)
SOZ1.sep	-	Sandopolis Zone Act 1
SOZ2.sep	-	Sandopolis Zone Act 2
SSZ1.sep	-	Sky Sanctuary Zone (Sonic/Tails)
SSZ1DEZ.sep	-	Sky Sanctuary Zone (Sonic/Tails Death Egg Launch)
SSZ2.sep	-	Sky Sanctuary Zone (Knuckles)

3kinject.txt	-	This is the "Batch File" that is used to perform input data conversions and initiate Injection for "Sonic 3 & Knuckles"


3kinmain.txt	-	This is the "Injector File" that contains the information for placing the modified data back into the game file for "Sonic 3 & Knuckles"


3kinmrg.txt	-	This is the "Injector File" that combines "Sonic 3" and "Sonic & Knuckles" to form "Sonic 3 & Knuckles", and modifies the header so that emulators will recognize the SRAM support


3kinopt.txt	-	This is the "Injector File" that contains various modifiable options for "Sonic 3 & Knuckles"


3ksplit.txt	-	This is the "Batch File" that calls on both "3split.txt" and "ksplit.txt" to perform a complete "Sonic 3 & Knuckles" split


3split.txt	-	This is the "Batch File" that is used to split data from the "Sonic 3" game file and perform output data conversions


derecmp.exe	-	This program is used for decompressing and recompressing "Sonic & Knuckles" and "Blue Spheres" Special Stage Layout Data


fixheadr.exe	-	This program is used to correct the size and checksum header information after Injection


ksplit.txt	-	This is the "Batch File" that is used to split data from the "Sonic & Knuckles" game file and perform output data conversions

Game Notes

Tile Paging and Shared Level Data

Animated Tiles and Palettes

Loops, Crossing Paths, and Plane Priority

Spin Tunnels

Level Boundaries

For the most part, Level Boundaries (the area within which the screen is allowed to scroll across the level during gameplay) are not dynamically altered in this game, meaning that the initial (and persistent) settings can be modified.

Notable exceptions include-

Angel Island Zone	-	"YEnd" is changed several times throughout the level, depending on X location and the current player character.


Carnival Night Zone Act 2	-	The "YStart" value stored in the table is lower to prevent Tails or Knuckles from ascending the elevator shaft. "YStart" is moved to the top of the level upon exiting that area.


Mushroom Hill Zone Act 1	-	The "XStart" location is set by level events both to cut off the earlier section of the level in Sonic and Knuckles alone, and to prevent Sonic/Tails from entering Knuckles' starting area by walking off the cliff hidden to the left.

Other settings for each level can be changed by modifying the "

Level Size Array

3kinopts.txt

Fixed and Dynamic Water Heights

Dynamic Level Changes

incomplete

3kintil.txt - An Injector File that deals with Tilesets. It is incomplete in that there are many more Tileset location references within the game that it does not correct, and thus, many places where the game will crash because the old data pointers will have been made invalid
ksplitp.txt - A Batch File for extracting several of the special Palettes that aren't loaded by the standard Palette Load List

Boss Arenas

Level TitleCard Names

Special Options

Level Music Playlist

3kinopts.txt

Level Boundaries

Level Size Array

3kinopts.txt

WORD	XStart, XEnd, YStart, YEnd

XStart	-	The leftmost world position that the screen is allowed to scroll to within the level


XEnd	-	The rightmost world position that the screen is allowed to scroll to within the level


YStart	-	The uppermost world position that the screen is allowed to scroll to within the level


YEnd	-	The lowermost world position that the screen is allowed to scroll to within the level

Level Y Looping

YLoop

YStart

Cheat Codes

Vine and Pulley

Cheat Codes

3kinopts.txt

Input State Bits

, Code_End

Input_Invalid

These codes may not excede 9 buttonpresses, due to the way they are accessed by the program code.

Titlescreen

S3K Titlescreen Cheat Code

3kinopts.txt

This code may contain as many buttonpresses as desired.