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.
Both Stage.json
and Splines.json
can be generated 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: