Troubleshooting Custom Level Issues in Sonic Generations/Sonic Unleashed

This page covers possible troubleshooting steps for custom levels in Sonic Generations and Sonic Unleashed.

Visual Issues

Common

Black Textures

Textures must have power-of-two resolutions (e.g. 512x512, 1024x1024, 2048x2048, etc). Arbitrary resolutions like 507x631 are not supported when using compressed textures.

Randomly Switching Textures

The material doesn't have any textures assigned. The game expects at least a diffuse texture to be present for nearly every shader.

Missing Transparency On Textures

You might need @LYR(trans) or @LYR(punch) tags on your material names. See the terrain importing guide for more info. Your texture might be compressed using BC1/DXT1, which doesn't support alpha channels, you should use BC3/DXT5 instead.

Missing Terrain Models

StageGuidePath.path.xml leftover from another level can cause wonky terrain streaming or not render some of your terrain models, as it wouldn't follow the path of your stage. To disable stage guide path, you can simply remove the .path.xml file or set g_UseGuidePath in Terrain.prm.xml to false.

Missing Direct Light

If you add a new direct light, update Terrain.stg.xml (or Stage.stg.xml in Sonic Unleashed) with the name of the light:

<Light>
  <DataName>MyDirectLight</DataName>
</Light>

Missing Sky Model

If you made a new sky model, update Terrain.stg.xml (or Stage.stg.xml in Sonic Unleashed) with the name of the sky model:

<Sky>
  <Model>MySkyModel</Model>
</Sky>

Make sure the sky model's materials use sky shaders like Sky_d.

Enemies From Other Stages Not Appearing

Some enemies are only loaded in specific stages. You can fix that by editing EnemyArchiveTree.xml inside #Application.ar.00. In this example, ghz_cmn entry was modified to include data from EnemyEFighter, allowing egg fighters to be used in both ghz100 and ghz200:

<DefAppend>
  <Name>ghz_cmn</Name>
  <Archive>EnemyCommon</Archive>
  <Archive>EnemyBeeton</Archive>
  <Archive>EnemyBatabata</Archive>
  <Archive>EnemyGanigani</Archive>
  <Archive>EnemyMotora</Archive>
  <Archive>EnemyEFighter</Archive>
</DefAppend>

The same method applies to Sonic Unleashed.

---

Sonic Unleashed

Missing Terrain Models

Terrain.prm.xml likely requires memory sizes to be higher. To fix this, edit g_LimitSize under DynamicLoad and Terrain-Model to values like 100000000bytes or 250000000bytes. Make sure to use sensible values as absurd values like 999999999999 are not going to work correctly. If editing the memory sizes does not work, you can try changing g_EnableFrustumCulling and g_EnableOcclusionCulling to false as a last resort. Note that disabling these two options might cause a performance hit in-game!

File Replacements Not Working

The title update and DLC override files in the base game archives by including them in a work folder. These files are going to always take priority over your modded files. This is a common problem with Terrain.prm.xml and.set.xml files. To override them, include the modified files in your mod in a work folder using the same file structure.

Invisible Materials

This happens when a material points to a shader that doesn't exist. To see all available shaders, unpack shader.ar in the base game directory and check for .shader-list files.

Low Quality or Missing GI Textures

Terrain.prm.xml likely requires memory sizes to be higher. To fix this, edit g_LimitSize under DynamicLoad and GI-Texture to values such as 100000000bytes or 250000000bytes. Make sure to use sensible values as absurd values like 999999999 are not going to work correctly. When DLC is enabled, the game looks inside the Additional folder to load HD GI, the parameter for it is named g_Xbox360LimitSizeWithAdditional, which you also should try to increase.

---

Sonic Generations

Rainbow Flashing Textures

A rainbow flashing texture is displayed when a texture assigned to a material is missing. Ensure you included the texture in the archive and didn't make a typo in the material. Texture names are case-sensitive.

Missing Terrain Models

Terrain.prm.xml likely requires memory sizes to be higher. To fix this, edit g_TerrainModelLimitSizeDefault and g_TerrainModelLimitSizeWin32 under DynamicLoad and Terrain-Model to values such as 100mb or 250mb. Make sure to use sensible values as absurd values like 999999999 are not going to work correctly.

Red Materials

This happens when a material points to a shader that doesn't exist. To see all available shaders, unpack shader_r_add.ar.00 inside bb3.cpk and check for .shader-list files.

Low Quality or Missing GI Textures

Terrain.prm.xml likely requires memory sizes to be higher. To fix this, edit g_GITextureLimitSizeDefault and g_GITextureLimitSizeWin32 under DynamicLoad and GI-Texture to values such as 100mb or 250mb. Make sure to use sensible values as absurd values like 999999999 are not going to work correctly.

Crashes or Infinite Loading

Common

Missing Material Files

Unlike newer games, missing materials can crash Generations/Unleashed. For Sonic Unleashed, only having the .material file isn't enough, you also need the matching .texset and .texture files.

Periods in File Names

File names with extra periods break stuff. For example, Material.000.material gets read as .000.material, and the game won't recognize it properly.

Instance Names Starting with "ins"

Instances starting with ins are treated differently, and require specialized material shaders. Using any other shader causes a crash. Ensure that none of the instances in your stage start with this word.

Missing "gi-texture.gi-texture-group-info" File

Run GI Atlas Converter on Pre-Render mode to have this file created automatically.

Missing "light-list.light-list" File

Copy paste .light and .light-list files from another stage, or add a direct light to your level in the 3D software you use. Latest Hedgehog Converter can import direct lights, so ensure your tools are up to date. Use HedgeGI for advanced light editing.

Mismatching PFD/PFI Files

PFD files are loaded through PFI files. If the Stage.pfi/Stage-Add.pfi files don't match with the Stage.pfd/Stage-Add.pfd files in the stage, this causes a crash. Unpack the PFD files, and repack them back with HedgeArcPack using -T=pfd command-line option to generate matching PFI files.

Light Field File Too Large

Your game might crash randomly when booting your level if the level's light field (.lft) file is too large. Try increasing the minimum cell radius in HedgeGI to reduce the light field's file size.

---

Sonic Unleashed

Incorrect Material Format

Unleashed uses a different material version (V1) compared to Generations (V3), and if you try to load a material from Generations in Unleashed, it'll crash. Check the version in a hex editor (7th byte), or look for .texset/.texture, those usually mean it's V1.

---

Sonic Generations

Unloaded Sonic Animations

The game doesn't load certain Sonic animations to save memory if the gimmick in question is never used. For example, diving animations stored in SonicDiving.ar.00 are only loaded in Chemical Plant, Speed Highway and Planet Wisp. If diving is used in any other stage, the game is going to crash due to unloaded animations. This behavior can be configured by editing ArchiveTree.xml inside #Application.ar.00. In this example, SonicDiving entry was edited to load in the ghz200 stage slot:

<Node>
  <Name>SonicDiving</Name>
  <Archive>SonicDiving</Archive>
  <Order>0</Order>
  <DefAppend>SonicDiving</DefAppend>
  <Node>
    <Name>bne</Name>
    <Archive>bne</Archive>
    <Order>0</Order>
  </Node>
  <Node>
    <Name>cpz200</Name>
    <Archive>cpz200</Archive>
    <Order>0</Order>
  </Node>
  <Node>
    <Name>pla200</Name>
    <Archive>pla200</Archive>
    <Order>0</Order>
  </Node>
  <Node>
    <Name>sph200</Name>
    <Archive>sph200</Archive>
    <Order>0</Order>
  </Node>
  <Node>
    <Name>ghz200</Name>
    <Archive>ghz200</Archive>
    <Order>0</Order>
  </Node>  
</Node>