Troubleshooting Custom Level Issues in Sonic Generations/Sonic Unleashed: Difference between revisions

Latest revision as of 11:27, 3 May 2025

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>

@@ Line 1: / Line 1: @@
-== Common Issues ==
+This page covers possible troubleshooting steps for custom levels in '''Sonic Generations''' and '''Sonic Unleashed.'''
-=== Black Textures ===
+== Visual Issues ==
-Textures must have power of two resolutions. For example, 512x512, 1024x1024, 2048x4096, etc. An arbitrary resolution like 600x600 is not supported by the game when using compressed textures.
-=== Rainbow Flashing Textures ===
+=== Common ===
-The game shows a rainbow flashing texture if the texture assigned to a material is missing. Ensure you included the texture in the AR and didn't make a typo in the material.
-=== Randomly Switching Textures ===
+==== Black Textures ====
-The material might not have any textures assigned at all. You need to at least assign one diffuse texture, otherwise the game is going to use the texture of whatever was rendered last.
+Textures must have power-of-two resolutions ''(e.g. 512x512, 1024x1024, 2048x2048, etc)''. Arbitrary resolutions like 507x631 are not supported when using compressed textures.
-=== Missing Transparency On 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.
-* You might need <code>@LYR(trans)</code> or <code>@LYR(punch)</code> tags on your material names. See terrain importing guide for more information.
+==== Missing Transparency On Textures ====
-* Your texture might be compressed using <code>BC1</code>/<code>DXT1</code> format. This format does not support alpha channels. For transparent textures, use the <code>BC3</code>/<code>DXT5</code> compression format instead.
+You might need <code>@LYR(trans)</code> or <code>@LYR(punch)</code> tags on your material names. See the [[How To Import Custom Terrain in Sonic Generations/Sonic Unleashed|terrain importing guide]] for more info. Your texture might be compressed using <code>BC1</code>/<code>DXT1</code>, which doesn't support alpha channels, you should use <code>BC3</code>/<code>DXT5</code> instead.
-=== Missing Terrain Models ===
+==== Missing Terrain Models ====
+<code>StageGuidePath.path.xml</code> 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 <code>.path.xml</code> file or set <code>g_UseGuidePath</code> in <code>Terrain.prm.xml</code> to <code>false</code>.
-* <code>Terrain.prm.xml</code> file might require higher memory sizes. Look for the <code>g_TerrainModelLimitSizeDefault</code> and <code>g_TerrainModelLimitSizeWin32</code> parameters, and increase them. If your stage requires more memory than what is defined in this file, some of your models might not render.
+==== Missing Direct Light ====
-** Do not increase these values too much! The values are represented in MB, and inputting insane values like 99999999 won't allow the game to parse the value correctly. Start small like 100 or 250 MB.
-* There is a limit of 8192 instances in the game. If you are trying to render more instances, the game is going to hit this limit and stop rendering.
-* Material files might be missing. There is a chance it might not crash and display nothing instead.
-* You might have a <code>visibility-tree.vt</code> file leftover from another level in your files. This file controls occlusion culling, and it needs to be created specifically for the level it's used in. Remove this file to solve potential pop-in problems.
-** Similarly, if you are porting a level from Sonic Unleashed to Sonic Generations or vice versa, you might experience issues if your set object cameras don't exactly match with the original game. If they do, you can safely keep this file.
-=== Red Materials ===
+If you add a new direct light, update <code>Terrain.stg.xml</code> (or <code>Stage.stg.xml</code> in Sonic Unleashed) with the name of the light:<syntaxhighlight lang="xml">
-The game fallbacks to displaying a red emissive material if the shader assigned to a material does not exist. If you want to see every available shader in the game, unpack <code>shader_r_add.ar.00</code> located inside <code>bb3.cpk</code>, and look for files with <code>.shader-list</code> extension.
-=== Low Quality or Missing GI Textures ===
-<code>Terrain.prm.xml</code> file might require higher memory sizes. Look for the <code>g_GITextureLimitSizeDefault</code> and <code>g_GITextureLimitSizeWin32</code> parameters, and increase them.
-Do not increase these values too much! The values are represented in MB, and inputting insane values like 99999999 won't allow the game to parse the value correctly. Start small like 100 or 250 MB.
-=== Missing Direct Light ===
-If you add a new direct light with a different name, you need to edit <code>Terrain.stg.xml</code> to make the stage use it. For example:<syntaxhighlight lang="xml">
 <Light>
    <DataName>MyDirectLight</DataName>
@@ Line 39: / Line 25: @@
 </syntaxhighlight>
-=== Missing Sky Model ===
+==== Missing Sky Model ====
-If you add a new sky model with a different name, you need to edit <code>Terrain.stg.xml</code> to make the stage use it. For example:<syntaxhighlight lang="xml">
+If you made a new sky model, update <code>Terrain.stg.xml</code> (or <code>Stage.stg.xml</code> in Sonic Unleashed) with the name of the sky model:<syntaxhighlight lang="xml">
 <Sky>
    <Model>MySkyModel</Model>
 </Sky>
-</syntaxhighlight>Ensure that the materials of the sky model also use sky shaders such as <code>Sky_d</code>.
+</syntaxhighlight>Make sure the sky model's materials use sky shaders like <code>Sky_d</code>.
-=== Enemies From Other Stages Not Appearing ===
+==== Enemies From Other Stages Not Appearing ====
-Certain enemies are loaded manually in stages to save memory. If an enemy does not appear in your stage, you can fix it by editing <code>EnemyArchiveTree.xml</code> inside <code>#Application.ar.00</code>. In this example, <code>ghz_cmn</code> entry was modified to include data from <code>EnemyEFighter</code>, which allows egg fighters to be used in both <code>ghz100</code> and <code>ghz200</code>:<syntaxhighlight lang="xml">
+Some enemies are only loaded in specific stages. You can fix that by editing <code>EnemyArchiveTree.xml</code> inside <code>#Application.ar.00</code>. In this example, <code>ghz_cmn</code> entry was modified to include data from <code>EnemyEFighter</code>, allowing egg fighters to be used in both <code>ghz100</code> and <code>ghz200</code>:<syntaxhighlight lang="xml">
 <DefAppend>
    <Name>ghz_cmn</Name>
@@ Line 57: / Line 45: @@
    <Archive>EnemyEFighter</Archive>
 </DefAppend>
-</syntaxhighlight>
+</syntaxhighlight>The same method applies to Sonic Unleashed.
+<hr>
+=== Sonic Unleashed ===
+==== Missing Terrain Models ====
+<code>Terrain.prm.xml</code> likely requires memory sizes to be higher. To fix this, edit <code>g_LimitSize</code> under <code>DynamicLoad</code> and <code>Terrain-Model</code> to values like '''100000000'''<small>bytes</small> or '''250000000'''<small>bytes</small>. 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 <code>g_EnableFrustumCulling</code> and <code>g_EnableOcclusionCulling</code> to <code>false</code> 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 <code>work</code> folder. These files are going to always take priority over your modded files. This is a common problem with <code>Terrain.prm.xml</code> and<code>.set.xml</code> files. To override them, include the modified files in your mod in a <code>work</code> 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 <code>shader.ar</code> in the base game directory and check for <code>.shader-list</code> files.
+==== Low Quality or Missing GI Textures ====
+<code>Terrain.prm.xml</code> likely requires memory sizes to be higher. To fix this, edit <code>g_LimitSize</code> under <code>DynamicLoad</code> and <code>GI-Texture</code> to values such as '''100000000'''<small>bytes</small> or '''250000000'''<small>bytes</small>. 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 <code>Additional</code> folder to load HD GI, the parameter for it is named <code>g_Xbox360LimitSizeWithAdditional</code>, which you also should try to increase.
+<hr>
+=== 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 ====
+<code>Terrain.prm.xml</code> likely requires memory sizes to be higher. To fix this, edit <code>g_TerrainModelLimitSizeDefault</code> and <code>g_TerrainModelLimitSizeWin32</code> under <code>DynamicLoad</code> and <code>Terrain-Model</code> to values such as '''100'''<small>mb</small> or '''250'''<small>mb</small>. 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 <code>shader_r_add.ar.00</code> inside <code>bb3.cpk</code> and check for <code>.shader-list</code> files.
+==== Low Quality or Missing GI Textures ====
+<code>Terrain.prm.xml</code> likely requires memory sizes to be higher. To fix this, edit <code>g_GITextureLimitSizeDefault</code> and <code>g_GITextureLimitSizeWin32</code> under <code>DynamicLoad</code> and <code>GI-Texture</code> to values such as '''100'''<small>mb</small> or '''250'''<small>mb</small>. Make sure to use sensible values as absurd values like '''999999999''' are not going to work correctly.
+== Crashes or Infinite Loading ==
-== Common Crash Reasons ==
+=== Common ===
-=== Missing Material Files ===
+==== Missing Material Files ====
-Unlike later games, missing materials can cause a crash in Sonic Generations and Sonic Unleashed.
+Unlike newer games, missing materials can crash Generations/Unleashed. For Sonic Unleashed, only having the <code>.material</code> file isn't enough, you also need the matching <code>.texset</code> and <code>.texture</code> files.
-=== Periods in File Names ===
+==== Periods in File Names ====
-Having periods in your file names can confuse the game and cause crashes. For example, having a material named <code>Material.000.material</code> would make the game think the file has a <code>.000.material</code> extension, and not recognize it as a material file.
+File names with extra periods break stuff. For example, <code>Material.000.material</code> gets read as <code>.000.material</code>, and the game won't recognize it properly.
-=== Instance Names Starting with "ins" ===
+==== Instance Names Starting with "ins" ====
 Instances starting with <code>ins</code> 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 ===
+==== Missing "gi-texture.gi-texture-group-info" File ====
-Run GI Atlas Converter on Pre-Render mode to have this file created automatically.
+Run [[GI Atlas Converter]] on Pre-Render mode to have this file created automatically.
-=== Missing "light-list.light-list" File ===
+==== Missing "light-list.light-list" File ====
-Copy paste <code>.light</code> and <code>.light-list</code> 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.
+Copy paste <code>.light</code> and <code>.light-list</code> 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 ===
+==== Mismatching PFD/PFI Files ====
-PFD files are loaded through PFI files. If the <code>Stage.pfi</code>/<code>Stage-Add.pfi</code> files don't match with the <code>Stage.pfd</code>/<code>Stage-Add.pfd</code> files in the stage, this causes a crash. Unpack the PFD files, and repack them back with HedgeArcPack using <code>-T=pfd</code> command-line option to generate matching PFI files.
+PFD files are loaded through PFI files. If the <code>Stage.pfi</code>/<code>Stage-Add.pfi</code> files don't match with the <code>Stage.pfd</code>/<code>Stage-Add.pfd</code> files in the stage, this causes a crash. Unpack the PFD files, and repack them back with [[HedgeArcPack]] using <code>-T=pfd</code> 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.
+<hr>
+=== 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 <code>.texset</code>/<code>.texture</code>, those usually mean it's V1.
+<hr>
+=== Sonic Generations ===
+==== Unloaded Sonic Animations ====
-=== 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 <code>SonicDiving.ar.00</code> 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 <code>ArchiveTree.xml</code> inside <code>#Application.ar.00</code>. In this example, <code>SonicDiving</code> entry was edited to load in the <code>ghz200</code> stage slot:<syntaxhighlight lang="xml">
 <Node>
@@ Line 113: / Line 146: @@
 </Node>
 </syntaxhighlight>
-=== Lightfield File Too Large ===
-Your game might crash randomly when booting your level if the level's lightfield (.lft) file is too large. Try increasing the minimum cell radius in HedgeGI to reduce the lightfield's file size.