SCHG How-to

Creating Levels in Sonic Heroes

From Sonic Retro

SCHG: Sonic Heroes
Main Article
Mechanic Editing
DOL Editing
EXE Editing
Music Pointers
Relocatable Editing (PC)
::::File Offsets
Model Editing
Model Format
Collision Format
Level Editing
Camera Editing
Indirect Editing
Level List
Object Editing
Object Porting
Visibility Editing
Particle Editing
Particle Editing
Sound Editing
Sound Editing
Music List
SCHG How-Tos
Custom Object Material Effect Tutorial
Level Editing Tutorial

(Original guide by igorseabra4)

This guide will show you how to create a custom level in Sonic Heroes.


First of all, you should come here and download pretty much everything in that page. It has every program this page mentions, except for HeroesONE, Magic.TXD, 3ds Max and HeroesCollisionEditor, all of which you should get as well. Make sure you are using the latest version of each tool, they get updated frequently.

In the PC version of Sonic Heroes, level models are multiple .BSP files located inside .ONE archives, which are located in the dvdroot folder. We'll be using HeroesOBJ2BSP to convert .OBJ files (with a .MTL material library) exported from 3ds Max (you can try using other model editors, but I can't guarantee it'll work) into .BSPs. Then we'll use HeroesONE to put the .BSPs inside a .ONE archive and replace one of the originals. Then, we'll add the textures to the level's .TXD texture archive file with Magic.TXD and edit visibility data in the level's _blk.bin file with Heroes Visibility Editor. After that, we'll create a collision model and convert it to a .CL readable by Heroes using HeroesCL2OBJ or HeroesCollisionEditor.

If this is your first time creating a level for this game, it's a good idea to first extract and take a look at the original levels, to see stuff like their size, shape, how they're laid out, what types of textures are in each .BSP etc. Use either HeroesBSP2OBJ or to rip the original .BSP models after extracting them from the original .ONE archives, Magic.TXD to rip the textures and HeroesCL2OBJ to rip the collision models. You can also play a bit with Heroes Layout Editor, add a few random objects or teleport around the stage for a bit. Make sure to read the entire tutorial and as much of these wiki pages as you can, so you know what you're doing and you're not just throwing models at a wall to see what renders.

Since the console versions of Sonic Heroes use the same file types for most files and do accept .BSPs from the PC version, you can create custom levels for the PC or any of them, as long as you remember to save the .TXD in the correct version (Magic.TXD allows you to choose either PC, GameCube or PlayStation2). There's only start/ending position and spline editors for the PC EXE though.

Level Models

For more information, see Model Format.


First of all, you should choose a stage to replace. Choose based on the theme of the stage you plan to make and objects you want to use, as some only work in a few level slots. Also, pinball table/BINGO mode only works on levels which originally had them. The .ONE files for the levels are named, where LL is the level number (some start with stg instead of s). For a complete list of level numbers, see the File Names and Data level list.

If this is your first time creating a level for this game, first you should open one of the original .ONEs with HeroesONE and take a look at how the .BSPs inside it are named:

SLL_MM_NN.BSP (or STG instead of S, accordingly with the .ONE name)

LL is the level number, MM is the material setting identifier and NN is the chunk number.

Levels in Sonic Heroes are divided into multiple NN chunks. Each chunk has a number and can have a large number of BSPs set for it. All files with the same NN number make up the same chunk. For the game to know which chunk to display at a given time, the camera must be inside boundaries set in the *_blk.bin file, which we'll discuss soon; if the BSP has no number (SLL_MM.BSP) it'll be rendered all the time.

The files also have different MM material settings. They will set how the model is rendered. For a complete list of what you can use, see Material Flags. These are some of them:

  • ON - Normal
  • ONS - Normal, shadow casting
  • ONW - Normal, no culling
  • ONWS - Normal, no culling, shadow casting
  • DN - Skybox
  • PN - Normal, alpha testing
  • PNS - Normal, alpha testing, shadow casting
  • PNW - Normal, alpha testing, no culling
  • PNWS - Normal, alpha testing, shadow casting, no culling
  • DA - Skybox, Alpha material
  • AFN - Alpha material
  • AFNS - Alpha material, shadow casting
  • K - Additive alpha
  • KW - Additive alpha, no culling

BSP Importing

In 3ds Max, you should split your models into groups so that each group will be converted into one .BSP file. So separate floors from walls and materials which use alpha from ones which don't. When splitting meshes, make each material its own object (so the number of materials and objects is 1:1; if you're too lazy to do that by hand, in 3ds Max just group everything into one mesh and use this tool to split it). There's a maximum of 65535 vertices and triangles per .BSP, but each one shouldn't be even close to that (as HeroesOBJ2BSP will add extra vertices to fix UV coordinates). Split the level into chunks; each resulting .BSP shouldn't be much bigger than around 500 kb or the game will crash.

Export your .OBJs from 3ds Max (remember to use Y axis = up) and drag them into HeroesOBJ2BSP (or just double-click the program to convert every .OBJ in the folder). Remember your .OBJ must use dots (.), not commas (,) as floating point separators in case you're from a country which uses that. And don't drag the .MTL into the program, it'll load that automatically.

It'll spit out a .BSP with the same name of your .OBJ. Name it according to the explanation above. Create an empty file in HeroesONE and add all your .BSPs to it. Save and replace the original file. If your level has a _h file (such as, replace that as well.


For more information, see Visibility Editing.

Each chunk is rendered if the camera is inside the visibility boundaries defined in the _blk.bin file. We'll use Heroes Visibility Editor to edit it. The file is named sLL_blk.bin or stgLL_blk.bin. Open the file in the editor and set the minimum and maximum coordinates you want the model to be visible at; for more precise values, create a box in 3ds Max and make sure it encompasses the entire chunk, or the entire area you want your chunk to be visible in. Then, export the box to a .OBJ, open it in a text editor and get the values from there. You should test your model ingame now, or wait to do so after adding the textures.


We'll be using Magic.TXD for the textures.

HeroesOBJ2BSP will try getting the texture names from the files specified in the .OBJ's referenced .MTL file. If you exported your model with the default 3ds Max settings, it should do this with no problem. If it fails to, it will use the material names (set by usemtl in the .OBJ file) as texture names. It will warn you if it does so.

The TXD files for level textures are located in dvdroot/textures. You'll probably figure out by now the name of your level's. Open it in Magic.TXD. Use Edit->Add or the Insert shortcut key or just drag your images into the list to add them to the file. Save and make sure the version of the TXD is correct (it should be Sonic Heroes PC, or GameCube or PlayStation 2 if you're editing those versions). Don't delete the original textures from the file unless you're sure of what you're doing (some levels will crash without certain textures). Remember this file contains textures for both level and object models. If you extracted the textures from the game already you obviously don't need to add them a second time. You should test your model now and it should render correctly.

Level Collision

For more information, see Collision Format.

First, you must create a collision model. You should start from your level's original model, but get rid of details such as plants that are not supposed to be touchable. You can also add invisible geometry to your collision model. Replace stairs with ramps. Make sure the model is as simple as possible. Split it into multiple meshes, as this division will be kept in the file. This model has a maximum size of 65535 vertices and/or triangles. Export it as .OBJ and convert it to .CL using HeroesOBJ2CL or HeroesCollisionGenerator. Once converted, replace the file in the dvdroot\collisions folder (it's named s(tg)

If you test your model and notice collision is buggy in some parts (such as floor clipping), it's probably because some of your meshes have too many triangles. Try simplifying the mesh, and if you absolutely can't, split it into 2 or more.

Using HeroesOBJ2CL

Drag your .OBJ into HeroesOBJ2CL. It will ask you for a maximum depth level. To test, you should try something between 3-5, as you probably want to try the level right away and don't want the operation to take too long. Choosing lower levels will have the file generated very quickly, but the game will take more of your CPU when running and you might have framerate drops. You should go for higher levels (10 if you can) when releasing as they are more optimized and will run better, but they can take a long time to get ready (it increases exponentially by depth level). Type 0 for the level to be chosen automatically.

Collision Flags

When creating your collision model, you must name your meshes so each one of them represents a different part of the level. Currently, this is only supported by HeroesOBJ2CL as of Release 2. Append an underscore _ and one of the following letters to set the collision type for that mesh:

  • _w - Wall. You can't walk or run on top of it
  • _s - Stairs. Model should be a ramp, but will act as stairs
  • _i - Barrier. It's a wall that is only solid as long as you are touching the ground
  • _b - Bingo slide
  • _p - Pinball table

Note that the bingo and pinball types will only work in levels which originally had them. The difference between them is that you accelerate much faster and have more control on slides than tables.

If you want to set the flags manually, just add p, s, t or f (for the first, second, third and fourth bytes of the flags, respectively) followed by which bit you want to set for that flag to the name. You can combine multiple of them. For example, a mesh named mesh_p3t1f6 would have bit 3 set in the first flag, bit 1 set in the third flag, and bit 6 set in the fourth flag (resulting in the combination 04 00 01 20). This should be used for experimental purposes only, as the flags have not been well documented yet.

Using HeroesCollisionGenerator

HeroesCollisionGenerator is an alternative for OBJ2CL made by sewer56lol. It uses a faster algorithm, but doesn't generate any collision flags yet. It requires .NET Core 2.0 to run. You can get the source here.

Death Zones and Water

There are no tools to create those yet


For this, you'll need Heroes Layout Editor to edit layout data and Heroes SET ID Table Editor to change object availability for use on certain stages. Object layouts are contained in s**_p**.bin for each level and team. Once you open a layout file in the editor, it should be pretty straightforward; just place objects wherever you want. Please read the Object Editing and Object Porting pages for all the info on this.

Starting Positions, Ending Positions and Splines

For more information, see EXE Editing.

You'll need to use HeroesTweaker for all of those. This data is located in Tsonic_win.exe.

For starting and ending positions, the only thing that shouldn't be self-explanatory is the hold time; it's the time you spend running before you gain control of the characters. It only applies to a Running start mode. Get the coordinates from the object layout editor for convenience.

Splines are located in Tsonic_win.exe. There are 3 types of splines: autoloops, rails and ball paths. Ball paths are those tubes used in Casino Park and BINGO Highway (it's them in those Power Plant green spheres as well).

HeroesTweaker lets you edit splines for most levels (we have all single player levels, but not all bosses and 2P levels yet; if you find the pointer list to the splines of any level, add its offset and amount of pointers to SplinePointers.ini and to this wiki please). It can edit the spline type for each spline, as well as export and import an OBJ file with them (when importing, make sure the only thing in the OBJ file is the spline). The imported file must have the same amount of vertices as the original one. You can't add or remove splines or vertices. If you wanna add more vertices to a spline, you must hex edit Tsonic_win.exe and do that there (if you wanna add more points to a spline, you'll have to switch some pointers around, but you can import the spline in HeroesTweaker after that).

Note that if you want a very long rail or autoloop and your level doesn't include that, you can glue the end of a spline to the start of the next and it will act like it's the same one (the original game actually does this all the time).

Other Stuff

Lightning data in s**_light.bin files. We don't know their format yet, but we do know they contain multiple light data entries. They are applied to characters and objects only (it's not environmental lightning). The main entry is applied all the time, and each of the other entries is applied by trigger objects.

Music is located in looping ADX files in the bgm folder. If the music's not looped, it won't start again after ending.

We also have Indirect Editing and Particle Editing. In EXE Editing there's a lot of stuff we don't have programs to edit yet, too.

There's one thing we do not know anything about yet; those are cameras. For now, just replace the _cam.bin file with an empty one. Eventually we'll be able to edit them as well.