How To Import Custom Terrain in Sonic Generations/Sonic Unleashed

Info

This guide uses the following tools:

You can use a different 3D software of your choice as long as you export to a format that Hedgehog Converter supports.

Part 1 (Creating Terrain in Blender)

First of all, you need terrain for your level. You can do the terrain yourself, or take already created terrain. If your level contains transparent materials you need to add a proper layer tag to it. For transparency, you have two available layers, and you should pick the one that's best suited for your use case in order to avoid issues.

Layers	Usage
punch	Used for materials which have binary transparency (one part is 100% opaque, another is 100% transparent). Useful for most kinds of textures, like leaves or grass
trans	Used for translucent materials, as in, materials which are not 100% opaque but also not 100% transparent (ex. windows)

In order to specify a layer for a material, use the @LYR prefix, with the layer name between parenthesis after it.

Example of a transparent material in Blender

You can then export your terrain from Blender into an Assimp compatible format (FBX, DAE, GLTF or OBJ work). When exporting FBX, make sure to set Apply Scalings to FBX Units Scale, otherwise your level is going to appear 100x larger in-game.

Part 2 (Importing the Level to the Game)

Download Hedgehog Converter and run bin/HedgehogConverter.exe. Fill in the following fields:

Game engine - The game you are converting for
Source 3D model files - Your terrain model files
Source textures directory - The directory containing the texture files for your terrain
Terrain output directory - The directory that will contain the converted terrain
Merge with existing files - Turn this off as we are creating a brand new stage

Make sure to create a folder inside the Packed directory, named according to your stage.

For example:

For Green Hill Act 2, use the folder name ghz200
For Windmill Isle Act 1 (Day), use the folder name ActD_MykonosAct1

You can refer to the Sonic Generations Stage IDs or Sonic Unleashed Stage IDs pages to find the ID of the stage you are going to replace.

It's recommended to first set up a mod and create these folders within it. If you've set up the folder structure correctly and browsed to it, the Terrain output directory should show something like the following examples:

Sonic Generations: D:\Steam\steamapps\common\Sonic Generations\mods\MyStageMod\disk\bb\Packed\ghz200
Sonic Unleashed: C:\Games\UnleashedRecomp\mods\MyStageMod\Packed\ActD_MykonosAct1

Make sure to also turn on the following options under Materials:

Generate materials
Copy and convert materials
Force tags from Source 3D models' material names as submesh layer

In the end, you should have something similar to this:

Next, click the Convert button and wait.

Warning

You should normally disable the Merge existing files option when creating a brand-new stage. However, if you're appending more terrain to a stage you've already created, make sure to enable this option, otherwise, you may permanently lose any changes you've previously made to your level. This action is irreversible, so proceed with caution!

Part 3 (Getting Missing Files)

Once the conversion is complete, you may need to add files that are missing from your stage. These are stored in the # archive, located next to the Packed folder.

For example:

For Green Hill Act 2, the archive will be named #ghz200.ar.00
For Windmill Isle Act 1 (Day), the archive will be named #ActD_MykonosAct1.ar.00

The # archive contains important data such as set data, stage settings, collision information, and more. Your level will not function correctly without it.

Sonic Generations

When creating a brand-new stage in Sonic Generations, Hedgehog Converter does not generate the # archive. To get started quickly, you can copy this archive from the base game. For example, if you are replacing Green Hill Act 2, you can copy the #ghz200.ar.00 and #ghz200.arl files from the disk/bb.cpk file (extracted using PackCpk) to your mod directory.

Sonic Unleashed

When creating a brand-new stage in Sonic Unleashed, Hedgehog Converter will create the # archive. That's because unlike Sonic Generations, Sonic Unleashed expects terrain-related files to be stored here. However, you can't just copy the # archive files from the base game into your mod, doing that will override your custom level and break it. Instead, you'll need to merge the base game files into your mod's # archive. You can use HedgeArcPack to unpack/pack the .ar.00 files.

You need to copy the following file types from the base game's archive:

.xml
.hkx

You can NOT copy the following, or your custom level will break completely:

.gil
.gi-texture-group-info
.light
.light-list
.terrain
.terrain-group
.tbst

Part 4 (SonicGLvl Basic Setup)

Next up, we need to do some very basic setup of your level's set data in SonicGLvl. Open the app, and open your stage's # archive from there. Once the level has been imported into SonicGLvl, press Ctrl+A and then Delete. This will delete all the objects that are present in your level's set data, which are the original objects from the stage we are replacing. Now, find "SonicSpawn" in the objects menu on the left, and place it anywhere you want. This will be where Sonic will spawn in your level. Also, be sure to set the "Active" property to "true" in the settings of the "SonicSpawn" object.

After that, go to File and press Save Stage Data.

Part 5 (Creating Skybox - Optional but Recommended)

Skyboxes are just regular .model files. Though not mandatory for the game to boot, they are recommended so that your level at least has a sky for you to look at. You can take these from the original levels or create one yourself.

Making one yourself

Export your skybox model from Blender into an Assimp compatible file format. Then, using Model Converter, drag and drop the model file onto the respective game's .bat file. This will generate the .model file, as well as material files. You will need to convert the textures of your skybox manually into the DDS format.

Grabbing one from a level

Sonic Generations

Go to the Packed folder in bb/bb2, and open the folder corresponding to the level you want the skybox from. Then, extract the .ar archive, and look for the sky's .model file. The name should have something to do with "sky". If you don't manage to find it, look at the stage's Terrain.stg.xml file, as it will mention the skybox's model name there. You will need the .model file, the textures (.dds files) and the materials of the sky model.

Using the Skybox files

After getting the necessary skybox model files, place them inside your stage's resources file:

Sonic Generations: Packed/stageID/stage.ar.00
Sonic Unleashed: StageID.ar.00

Then, open # file of your stage, and open the respective .stg.xml file:

Sonic Generations: Terrain.stg.xml
Sonic Unleashed: Stage.stg.xml

You'll need to create a Sky tag and write the name of the .model file of your skybox, without the extension. Below is an example of how you should write this. In this example, the skybox has a model file named MySkybox.model:

<Sky>
    <Model>MySkybox</Model>
<Sky>

If you boot your stage now, you'll notice that you will fall through the ground. This is because you only ported the terrain, and not the collision. To do this, follow the guide here.