About This Project

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.

Motivation

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.

Solution

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

How to Create a Stage

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).

Stage Folder Layout

The following describes the layout of each stage folder:

Files 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.

Stage.json

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.

Splines.json

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.

Integrating into Level Editing Tools (for Programmers)

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.

Prerequisites

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

Generating Stage.json

• 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");

Generating Splines.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");

Splines.json: Vertex Properties

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.

Vertex Properties: Distance to Next

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!

Vertex Properties: Pitch

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);

Example

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]);
}

Other Features

This mod also fixes crashes in the following scenarios:

• Loading the Test level.

• Loading 2P mode in 1P levels.

• Loading 1P in 2P levels.

Acknowledgements

island by nareerat jaikaew from Noun Project