Heroes Stage Injector

Creating Custom Stages should be Easy

So why not make it that?

Id: sonicheroes.utils.stageinjector

This mod uses the Hooks Shared Library. Please download and extract that mod first.

This mod uses the Universal Redirector. Please download and extract that mod first.

This mod provides a framework to allow for the loading of custom stages into Sonic Heroes without the need to write manual code by hand.

In contrast to more modern games in the franchise like Sonic Unleashed or Sonic Generations where modifying stages can be done entirely by modifying files; Heroes and the rest of the Adventure-engine games store a lot of the stage metadata embedded in the executable.

This metadata includes features such as bobsled paths, splines (rails, loops) and spawn points. Users lacking programming knowledge would normally be unable to access or modify these features.

The solution to this problem is to make everything available through files, and this mod does exactly that.

A sample mod (Radical Highway by Shadowth117) is available in the Releases section.

• Create an Empty Reloaded II mod.
• Add a dependency in ModConfig.json to this mod.

"ModDependencies": ["sonicheroes.utils.stageinjector"]

• Add a folder named Stages.
• For each stage you want to add, create a folder (folder can have any name).

The following describes the layout of each stage folder:

This folder is used for file redirection and maps to the executable directory of Sonic Heroes. For example to change the textures for Seaside Hill (s01.txd), you would place the file \dvdroot\textures\s01.txd inside the Files folder.

This file contains the spawn properties and level ID this stage is supposed to replace.

The level ID can be obtained from the following page SCHG: Sonic Heroes (under the EXE and RAM label).

If you are replacing a singleplayer stage, the StartPositions represent the spawn positions of each of the following teams in order Sonic, Dark, Rose, Chaotix, Foredit (unused team).

If you are a multiplayer stage, the first two StartPositions are used for P1 and P2 respectively and the BragPositions represent the positions the team introductions are performed before a race.

This file contains the information about each loop, rail and other kind of splines to be used by the stage.

At the moment, no tools exist for creating Splines.json (this should change real soon!). For Stage.json, it can be created by Heroes Power Plant.

This is a quick barebones introduction/summary of how you can generate Splines.json and Stage.json to be used with this mod in your own programs.

• Add the sonicheroes.utils.stageinjection.common NuGet package to your project.

• Create a new instance of the Config class.

var config = new Config();

• Fill all the fields.

config.StageId = StageId.SeasideHill;
config.StartPositions = new PositionStart[] { ... };

• Save as Stage.json

Config.ToPath(config, "Stage.json");

• Create a new instance of the SplineFile class.

var splineFile = new SplineFile();

• Create an array of Splines.

splineFile.Splines = new ManagedSpline[] { ... }

• Save as Splines.json

SplineFile.ToPath(splineFile, "Splines.json");

Each of the spline vertices inside Splines.json have a distinct set of properties. Below are some of the key properties that can be auto-calculated without manual input.

It is recommended that these properties are autogenerated first, before letting the user manually customize them.

Each vertex stores the distance to the next vertex in the spline. This distance can be automatically calculated using the GetDistance function of the SplineVertex struct.

Usage:

splineVertex.DistanceToNextVertex = splineVertex.GetPitch(nextSplineVertex);

This property must be used. Without this property the splines will not work!

For each vertex of a spline, the pitch (vertical rotation/angle) can be automatically calculated using the GetPitch function of the SplineVertex struct.

Usage:

splineVertex.Pitch = splineVertex.GetPitch(nextSplineVertex);

Auto-calculate distance and pitch for all vertices of the spline.

var vertices = managedSpline.Vertices;
for (int x = 0; x < vertices.Length - 1; x++)
{
    vertices[x].DistanceToNextVertex = vertices[x].GetDistance(vertices[x + 1]);
    vertices[x].Pitch = (ushort)vertices[x].GetPitch(vertices[x + 1]);
}

This mod also fixes crashes in the following scenarios:

• Loading the Test level.

• Loading 2P mode in 1P levels.

• Loading 1P in 2P levels.