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

Revision as of 17:59, 2 May 2025

Info

This page covers both Sonic Generations and Sonic Unleashed. Game-specific explanations will be indicated by the game name in parentheses. If no game is specified, the explanation applies to both games.

Common Issues

Black Textures

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

Rainbow Flashing Textures (Sonic Generations)

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.

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. Use BC3/DXT5 instead.

Missing Terrain Models

Terrain.prm.xml likely requires memory sizes to be higher.

Sonic Generations

Under DynamicLoad and Terrain-Model, increase the g_TerrainModelLimitSizeDefault and g_TerrainModelLimitSizeWin32 parameters to values like 100 or 250. The unit of the value is MB. Make sure to use sensible values as absurd values like 999999999 are not going to work correctly.

Sonic Unleashed

Under DynamicLoad and Terrain-Model, increase the g_LimitSize to values like 100000000 or 250000000. The unit of the value is byte. 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 (Sonic Unleashed)

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.

Red Materials (Sonic Generations)

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.

Invisible Materials (Sonic Unleashed)

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.

Sonic Generations

Under DynamicLoad and GI-Texture, increase the g_GITextureLimitSizeDefault and g_GITextureLimitSizeWin32 parameters to values like 100 or 250. The unit of the value is MB. Make sure to use sensible values as absurd values like 999999999 are not going to work correctly.

Sonic Unleashed

Under DynamicLoad and GI-Texture, increase the g_LimitSize to values like 100000000 or 250000000. The unit of the value is byte. Make sure to use sensible values as absurd values like 999999999999 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.

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.

Common Crash or Infinite Loading Reasons

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.

Incorrect Material Format (Sonic Unleashed)

Unleashed uses V1 materials while Generations uses V3. If you try to load a V3 material 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.

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.

Unloaded Sonic Animations (Sonic Generations)

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>

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.

@@ Line 1: / Line 1: @@
+{{Notice|type=info|content=This page covers both Sonic Generations and Sonic Unleashed. Game-specific explanations will be indicated by the game name in parentheses. If no game is specified, the explanation applies to both games.}}
 == Common Issues ==
 === Black Textures ===
-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.
+Textures must have power-of-two resolutions (like 512x512, 1024x1024, 2048x2048, etc). Arbitrary resolutions like 507x631 are not supported when using compressed textures.
-=== Rainbow Flashing Textures ===
+=== Rainbow Flashing Textures (Sonic Generations) ===
-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.
+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'''.
 === Randomly Switching 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.
+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 <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.
-* You might need <code>@LYR(trans)</code> or <code>@LYR(punch)</code> tags on your material names. See terrain importing guide for more information.
+Your texture might be compressed using <code>BC1</code>/<code>DXT1</code>, which doesn’t support alpha channels. Use <code>BC3</code>/<code>DXT5</code> instead.
-* 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.
 === Missing Terrain Models ===
+<code>Terrain.prm.xml</code> likely requires memory sizes to be higher.
+==== Sonic Generations ====
+Under <code>DynamicLoad</code> and <code>Terrain-Model</code>, increase the <code>g_TerrainModelLimitSizeDefault</code> and <code>g_TerrainModelLimitSizeWin32</code> parameters to values like 100 or 250. The unit of the value is MB. Make sure to use sensible values as absurd values like 999999999 are not going to work correctly.
+==== Sonic Unleashed ====
+Under <code>DynamicLoad</code> and <code>Terrain-Model</code>, increase the <code>g_LimitSize</code> to values like 100000000 or 250000000. The unit of the value is byte. 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 (Sonic Unleashed) ===
+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.
-* <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.
+=== Red Materials (Sonic Generations) ===
-** 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.
+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.
-* 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 ===
+=== Invisible Materials (Sonic Unleashed) ===
-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.
+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> file might require higher memory sizes. Look for the <code>g_GITextureLimitSizeDefault</code> and <code>g_GITextureLimitSizeWin32</code> parameters, and increase them.
+<code>Terrain.prm.xml</code> likely requires memory sizes to be higher.
-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.
+==== Sonic Generations ====
+Under <code>DynamicLoad</code> and <code>GI-Texture</code>, increase the <code>g_GITextureLimitSizeDefault</code> and <code>g_GITextureLimitSizeWin32</code> parameters to values like 100 or 250. The unit of the value is MB. Make sure to use sensible values as absurd values like 999999999 are not going to work correctly.
+==== Sonic Unleashed ====
+Under <code>DynamicLoad</code> and <code>GI-Texture</code>, increase the <code>g_LimitSize</code> to values like 100000000 or 250000000. The unit of the value is byte. Make sure to use sensible values as absurd values like 999999999999 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.
 === 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">
+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">
 <Light>
    <DataName>MyDirectLight</DataName>
@@ Line 40: / Line 58: @@
 === 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 ===
-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 75: @@
    <Archive>EnemyEFighter</Archive>
 </DefAppend>
-</syntaxhighlight>
+</syntaxhighlight>The same method applies to Sonic Unleashed.
-== Common Crash Reasons ==
+== Common Crash or Infinite Loading Reasons ==
 === 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.
+=== Incorrect Material Format (Sonic Unleashed) ===
+Unleashed uses V1 materials while Generations uses V3. If you try to load a V3 material 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.
 === 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" ===
@@ Line 71: / Line 92: @@
 === 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 ===
-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 ===
-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.
-=== Unloaded Sonic Animations ===
+=== Unloaded Sonic Animations (Sonic Generations) ===
 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 114: / Line 135: @@
 </syntaxhighlight>
-=== Lightfield File Too Large ===
+=== Light Field 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.
+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.