How to edit levels by interactively adding objects

You may remember the "debug mode" cheat codes from the original Sonic 1, 2, and 3 on the Genesis, which let you move around the levels and place objects. With the help of some external hacking tools, it is possible to get something similar in Sonic Adventure 2. You can even save your changes, making the new objects a permanent part of the level until you undo it! This guide will show you how.

Getting started

In order to follow this guide, you're going to need to download a few things. Don't worry; all of the required programs are open source, in case you're worried about malware.

The first thing you need to download is Cheat Engine 6.4. You need that version even though it's not the latest. I would post the link to the website, but I posted it on SPUF once and got permabanned for linking to "exploit sites". (Probably because CE can also be used to cheat in multiplayer games.) Keep in mind it is not an "exploit site" as in a site that is harmful to your computer; CE is not a virus or anything. But it is a requirement for this tutorial, and it should be pretty easy to find it using Google. One thing to be aware of though: the installer for Cheat Engine includes OpenCandy, which asks you if you want to install a "sponsored" program like a toolbar or something. Make sure you uncheck this when you install Cheat Engine.

Second, you'll need to download my Sonic Adventure 2 cheat table. That can be found at https://github.com/flarn2006/SA2CheatTable/archive/master.zip . When you installed Cheat Engine, it should have created a "My Cheat Tables" folder in your Documents folder. Just unzip the archive into there.

The last one is optional, and is only needed if you want to permanently add new objects to the level without also getting rid of all the original objects. It's a small command-line tool called SETMerge, which can be found at https://github.com/flarn2006/SETMerge/releases . Put SETMerge.exe somewhere in your executable search path (PATH environment variable.) If you don't know what that means, putting it in C:\Windows\System32 will work.

By the way, I recommend you use a gamepad for this. It's really what the game, as well as the editing interface, was designed for, and I haven't tested it without one.

Starting the editor

Now you're ready to load the game. Load Sonic Adventure 2, and start a level. I'm going to use City Escape. Once the level loads (actually you can do it before the level loads as well, as long as the game is running) run Cheat Engine. See the button in the upper-left corner that looks like a computer, and has a blinking green and red border? Click that button. In the list that appears, look for "sonic2app.exe". It should be towards the bottom of the list. Then click OK.

If you have everything in the right path, a window will appear asking if you want to load the associated cheat table. Click Yes. Another window will likely appear asking if you want to run a Lua script. Say yes to this too. Now a "Tools" window should appear with some buttons on it. There's a bunch of different features in the cheat table, but you'll want to click the "Object Editing" button. The next window that appears may look complicated, but the parts you need will be explained. Finally, click on the "Live Edit Mode" button. This is what enables the in-game editing interface.

Anyway, switch back to the game and you should see "- LIVE EDIT MODE -" in the upper-left corner.

Live Edit Mode

Live Edit Mode is designed to make it easy to manipulate objects in-game without having to switch windows or mess with coordinates and angles. Think of it like the Genesis games' debug mode. Take a minute to get used to the controls. First, press DOWN on the D-pad. A bunch of text should appear on the screen, and a cyan cursor will appear where Sonic is currently standing. See the image below (note that the cursor has been moved in the image):


Now move the right analog stick on the controller. This moves the cursor horizontally. Using the left and right triggers moves it vertically. As you move the cursor, you may notice a blue box moving around to different objects in the level. This marks the current selection. The screen will also show information about the currently-selected object, such as its internal name and coordinates.

Press DOWN again. As the on-screen prompts indicate, this will confirm your selection. The selection box will turn green. Now hold down LEFT on the D-pad. The selection box will be yellow now. Try moving the right analog stick and using the triggers, just as you did before with the cursor. This time, the object will move! Release LEFT, and hold down UP. This time, the selection box will turn magenta. Try pressing the triggers. Depending on what object you selected, you should be able to rotate it. Moving the right analog stick will rotate the object on the other axes, but keep in mind this will crash the game with some objects (though I've only seen it happen with the one labeled as "ROADOBJ"), as in those cases the rotation variables store information other than rotation. If you want to try this, look for a spring and select that.

Finally, holding down RIGHT can be used to perform object-specific actions, but for most objects it won't do anything. Some examples are setting the destination of rockets or changing the size of collision objects. In these cases, extra information will be shown while holding RIGHT to explain what the controls do.

Placing objects

Remember that Object Editing window? Click the "Place Objects..." button in that window. This will open another window with more options. Notice the two buttons that say "Level Objects" and "Common Objects". See that tall white box on the left? That's the list of objects that can be placed. Clicking "Level Objects" will fill the list with objects from the current level, pulled from the game's memory, using their internal names. The "Common Objects" button will instead load a list of objects that should work in every level, using more friendly names. If you double-click on an object in that list, it will give you information on what the different parameters do, if any help is available.

There are also three groups of three text fields, each containing one red, one green, and one blue. These correspond to X, Y, and Z respectively. The "Offset from Player" group controls where the object will be spawned relative to the player. This isn't very important when you're using Live Edit Mode though. The Rotation section controls the rotation of the object. The values are in hexadecimal, measured in BAMS[en.wikipedia.org]. Basically, 0 is 0°, 2000 is 45°, 4000 is 90°, and so on until FFFF (about 359.99°) after which it wraps around to 0. Generally you won't need to enter values directly here, unless you need something aligned perfectly to an axis, or if the rotation values are used for something other than rotation. Finally, the "Scale" section controls the object's scale values. Keep in mind that for most objects this doesn't actually control the size of the object, but are instead used for various other parameters for objects, such as the power-up contained in an item box.

One more thing you should be aware of is the "Collision OFF" button. Clicking this will disable collision with most objects, so you walk right through rings without picking them up, and springs without bouncing on them, and so on.

Now select an object from the list and enable the cursor (remember, press DOWN.) Move the cursor somewhere and press LEFT. An instance of that object will appear where you placed the cursor. This should seem very familiar to anyone who has played with the debug mode I mentioned before!

Note: You can ignore the "Enable Object Placement" button. That's left over from before it was done automatically.

Saving, and the object list

So let's say you've placed some stuff and want to save it for later. Well you can! Look at the bottom of the "Object Placement" window (the one where you choose which object to place) for a button labeled "Show Spawned Objects". Click this button. This window will appear:



This window lists all the objects you have placed, and also provides the means for saving and loading object lists. In addition, you can double-click an item in the list to set it as the selected object. Here's a list of everything in that window and what it does:

• Delete All - Removes every spawned object from the game.
  
• Full Update - Performs a complete refresh of the list. Useful if something gets out of sync, like if you change stages and the list doesn't get automatically cleared.
  
• Load from File... - Loads a list of objects from a file and places them in-game.
  
• Save to File... - Saves all objects in the list to a file.
  
• Load saved objects relative to player position - Indicates that the file being loaded (or saved) contains (or should contain) positions relative to the current location of the player. Useful for if you want to save a "collection" of objects, but don't want it associated with a specific stage or location.
  
• Rotate to player (grayed = not individually) - A three-state check box. When it's checked, the saved objects will also be rotated, as a set, according to the player's orientation. When it's grayed (looks like a square in the box, unless you're using the classic theme) the same thing will happen, only the objects won't be rotated individually.

When saving a list, there are two formats you can choose from. Comma-separated values (*.csv) is the default format. This format can be loaded back into the game directly using Cheat Engine. Native SET format (*.bin) is the format recognized by the game, and is the same format in which the levels' objects are stored in the game's files. These cannot be loaded into the game using Cheat Engine (at least not yet) but you need to save in this format if you want to make the new objects a permanent part of the game. The next section of this guide will explain how this is done.

Intro to SET files

The next section will explain how to actually save the additional objects to the game's files, as an actual part of the level that gets loaded normally. This is what you need that SETMerge program for, so if you didn't download it before, the link is in the first section. Don't forget to put it in your search path.

First, however, a short explanation on what SET files are. Each level has a set (no pun intended) of files with names starting with "SET". The file names are in the format "SET####_suffix.bin". The #### is the internal number of the stage it corresponds to. (Keep in mind that this is not necessarily the same as the order in which the stages come in the game.) The suffixes are as follows:

U	Unsubstantive (decoration objects, loaded together with _S)
S	Substantive (gameplay objects, loaded together with _U)
HD_U	Hard mode, unsubstantive
HD_S	Hard mode, substantive
2P_U	2-player, unsubstantive
2P_S	2-player, substantive

Where are these files located? Right-click Sonic Adventure 2 in Steam and click Properties. Go to the Local Files tab, and click Browse Local Files. This will open the game's installation directory. From there, go to "resource", and "gd_PC". This is where the majority of the game's data is stored, including the SET files. The actual structure of these files' contents are beyond the scope of this guide, but if you're interested, it's explained pretty well on Sonic Retro[info.sonicretro.org].

What each file stores is a list of every object in a given stage. As mentioned in the table above, the _U and _S files basically store different types of objects. However, they are not treated differently in any known way, so it doesn't matter which one you add to.

Adding your changes to the game's files

As you may have guessed, what SETMerge does is take two (or more) SET files, and combine them into a single file with every original file's object entries. So the process goes something like this: place some objects, save the object list as "native SET format", and append the exported file to the appropriate SET file using SETMerge.

Now first, you're going to need to export a list of spawned objects to a SET file. I described how to do this previously; make sure you save as .bin! I'm going to assume you already have a set of objects you want to add. From here on, this saved file will be referred to as the "exported SET file."

Next, open the gd_PC folder, which contains the SET files. If you don't know where this is, see the previous section. Find the specific SET file you want to replace. Unless you're interested in editing the 2-player or hard mode version of a level, ignore the 2P or HD SET files. As for _S or _U, it shouldn't matter which one you append to. Of course, you also need to make sure it has the correct number. As mentioned before, this goes by the internal number for the stage, which isn't listed anywhere in-game. Here's a list of all the levels by internal number.[info.sonicretro.org]

Once you've identified the correct SET file (hereon referred to as the "original SET file", save a copy somewhere. You can always undo all changes by verifying your game files in Steam, but that takes a long time and overwrites any other changes you may have made to the game's files and want to keep. Now open a command prompt. The syntax for the command is as follows:

setmerge -f "path to original SET file" "path to exported SET file" "path to original SET file"

After this, you're done! Restart the game (actually, you only need to exit back to stage select and load the level again) and admire your changes!

Technical information (for those interested)

Note: This section is entirely optional, and is intended only for people who are curious how this tool works. None of the information in this section is necessary in order to follow this guide.

You might be wondering how exactly the editing interface works, especially if you've used Cheat Engine before. If you know Lua, you can look at the scripts yourself (in the "sa2lua" folder, or on Github[github.com]), but I'll put a brief explanation here.

When you load the cheat table, a Lua script runs. This has the immediately-visible effect of opening the Tools window. However, this script also loads some code into memory (from the "hook.bin" file, which was created from "hook.asm") and modifies the code of the game (in memory, the EXE is not changed) to execute this code every frame. This code checks a region of memory allocated by the script for instructions to call internal functions in the game's code.

The Lua script also monitors the internal tables that keep track of the in-game objects currently loaded. This data is used to, for instance, find the closest object to the cursor. Now not all of the tables are actually used for objects that appear in the level. Some of them are only entries saying to run specific code every frame. One function of the Lua code is to monitor these tables for the presence of a specific entry of this type, which doesn't normally exist in the game. If it doesn't find it, it loads the code for it (from "linedraw.bin") if it isn't loaded already, and adds the entry to the list using the same function that's normally used for placing objects.

As you may have guessed from the filename, this entry's function is to monitor another section of memory for line drawing specifications. These strings of bytes basically mean "draw a (color) line from (start coordinates) to (end coordinates)." It then goes through the list and calls a function in the game to draw lines there. (This is the same function that draws Tails and Eggman's laser sight, or the streaks that appear behind Sonic and Shadow when they're running at top speed.)

When Live Edit Mode is turned on, the Lua code is constantly monitoring the area of the game's memory where the current controller state is stored. When it detects you're holding a direction button, or the cursor is active, it sets a flag that the game uses internally when the player controls should be disabled. This is so you can use the editing interface without the character moving at the same time. It also places line drawing instructions in memory to tell the code mentioned before to draw the cursor and object markers on the screen. As for the text display, that's simply done using Cheat Engine's built-in Direct3D hooking feature.

So yeah, none of this is a leftover debugging feature or anything. (Well, except for the noclip feature, but if that wasn't there, it would be really easy to use the existing object-moving interface to do the same thing.) All of it is implemented in Lua, with the exception of the low-level parts that call functions in the game's code.

[I love women who headbutt]

Download link for cheat engine 6.4 https://cheatengine.org/downloads.php

Latest version of C.E does not work properly with the editor (i.e no cursor)

[I love women who headbutt]

Hey OKAMICANINE16, the editor version 6.4 is real and does work (latter versioons stopped working). I for one am very grateful to Flarn for making this tool, and one day ill continue my project using it :) These mission edits were done using Flarns editor and seteditor https://www.youtube.com/watch?v=Eh_w4XJPVik

[Xavum]

Cool. A fake editor that doesn't fucking work. I get the UI but no cursor or anything. What the hell?

[Zaxento The Greedy]

I'd love to see the Map too :D

[I love women who headbutt]

Hey Biffaloe III. I have manually removed the closing doors from Iron Gates. It was a long process and I needed a couple of tools not mentioned in this guide.

Now you could play through Iron Gates with any character. This is part of making all of the stages playable with Knuckles--an ongoing project. To do this I have needed to remove other items too, such as the vine-ropes in White Jungle / Green Forest, certain "sliders", doors and so on.

If it is desired I could share a version of Iron Gates where the closing doors are not present, ready for you to further edit or play.

[I love women who headbutt]

Hey Choclce. I am using Cheat Engine version 6.4 and this does still work (however some things I cannot do, like turn cyclinder collision objects onto their side, something I thought could be done before).

[Chocice75]

I tried the cheat table, but I only got errors.
Please fix this.

[Chocice75]

Does the cheat table still work?

[scarecrow]

When I select sonic adventure 2 in cheat engine the script doesen't work,I think the game had an update and it doesen't work anymore

[PuzzylPiece]

How about the text?
I saw it in SA2 Repainted