Editing Sonic Frontiers/Heightmaps

Heightmaps are a feature introduced in Sonic Frontiers to create large amounts of terrain with reduced filesize and greater performance over [[Resources/Terrain Model|Terrain Models]].

Heightmaps are generated from a series of greyscale [[Resources/Textures|textures]], which are used as height data to displace geometry of a plane up to a certain height. In the vanilla game this is typically a set of 16 tiles in a 4x4 grid for the open zones, though for certain heightmaps such as Big's Fishing Spot, only a single tile is used.

Collision is automatically generated if no [[Resources/Heightfield|heightfield]] is present, but if a heightfield is present, then the heightmap will have no collision on its own.

The material for a heightmap is determined by a [[Resources/Terrain Material|Terrain Material]].

=== Texels ===
Texels are the area of geometry that corresponds to each pixel on the heightmap texture. If the number of texels is not the same as the number of pixels, the heightmap will fail to render. The open zones use a texel density of 1 texel/m², while Big's Fishing Spot uses an increased texel density of 4 texels/m².

The limit for the number of texels is 67,108,864 texels, corresponding to a map 8192 texels long and 8192 texels wide. Since texel density cannot be lowered below 1 texel/m², this places an upper limit on a map size of 8192m x 8192m (approx. 8.2km x 8.2km).

On the other hand, the number of texels cannot go below 1,048,576 texels, as this is the number generated by one heightmap tile that is 1024 x 1024 pixels. However, the actual map size can go very small by increasing the texel density while decreasing the map size.

=== Parameters ===
The parameters for a heightmap are defined in the world's [[Resources/Reflection/NeedleFxSceneData|NeedleFxSceneData]] [[Resources/Reflection|Reflection]] file, under needleFxSceneData > stageConfig.

==== useHeightMapTerrain (Boolean) ====
This determines whether the heightmap is enabled. No Cyberspace levels use Heightmaps, so this is disabled for all of them, while the open zones and fishing spots do use them, so this is enabled.

==== useHalfPrecision (Boolean) ====
Could potentially determine whether the heightmap uses 16-bit greyscale colour or 32-bit greyscale colour. This is always set to True, so it always uses 16-bit colour in vanilla. It could be possible to use 32-bit heightmaps, but no suitable DirectDraw format has been found to allow for this.

==== precision ====

===== heightRange (Float) =====
The range which the heightmap covers vertically i.e. the maximum height of the heightmap. A pure black pixel on the heightmap texture will correspond to terrain at Y = 0, while a pure white pixel will correspond to the maximum height above Y = 0.

If this value is set to a negative number, the heightmap itself does not generate, but interestingly, any density foliage that snaps to terrain, such as trees, will generate on a flipped copy of the heightmap.

==== worldSize (sint32) ====
The size of the generated heightmap in texels, along one edge. This is ideally a power of two, though other values may work. The open zones use 4096 for this value, and Big's Fishing Spot uses 512.

If this value is set to a negative number, the game freezes on the loading screen.

==== heightMapTexelDensity (sint32) ====
The density of the texels used to construct the heightmap. A value of 1 equates to 1x1 texels per m², while a value of 2 equates to 2x2 texels per m² (4 texels). Note that if this is changed, the world size must also be changed to compensate. For example, if texel density is doubled, world size must be halved.

==== heightScale (Float) ====
This determines the height of the detail, determined by the displacement textures for each terrain material.

==== smallestCellSize (Float) ====
The size of the geometry that can be displaced to create detail. Anything below roughly 0.01 crashes the game. Values such as 0.1 work fine, and can reduce the amount of geometry used for the detail.

==== slopeClipThreshold (Float) ====
Sets a certain slope steepness beyond which the terrain will be culled. Unknown unit, though a threshold of 0.9 culls every slope steeper than about 30° from horizontal. 1 culls all terrain, and 0 culls none.

==== aabbMin/aabbMax (2D Vectors) ====
A set of two 2D vectors that define a boundary in which heightmap terrain is only to be rendered, used for cases like Kronos, which only uses about 2/3rds of the available area, so the rest is outside this boundary.

==== material ====

===== uvScaleDetail (Float) =====
The uv scale of details, a larger number scales the details down, while a smaller one scales the details up.

===== uvScaleBase (Float) =====
Similar to uvScaleDetail, but it determines the scale of the base texture, rather than the detail.

===== detailDistance (Float) =====
The distance, that the detail will be rendered fully within. This is also influenced by the camera angle.

===== detailFadeRange (Float) =====
The distance that the detail will be slowly reduced within until it disappears.