Class SurfaceMap

Defines the mapping between a specific surface type and the methods used to detect it. Links terrain texture indices and/or object tags to a SurfacePreset that defines the surface properties.

Each SurfaceMap represents a unique surface type in your scene and specifies:

  • Which terrain texture indices should be treated as this surface type
  • Which object tags should be treated as this surface type
  • The SurfacePreset that defines friction, visual effects, and audio for this surface

Detection priority: Ground detection prioritizes tag-based detection over terrain texture detection. This allows objects (roads, bridges, ramps) to override terrain textures beneath them.

Usage scenarios:

  • Map terrain texture 0 (grass) to a grass SurfacePreset
  • Map object tag "Road" to an asphalt SurfacePreset
  • Map multiple terrain textures (dirt variations) to the same dirt SurfacePreset
  • Override terrain with tagged objects for special surface areas

If both lists are empty, this surface map will never be matched.

Inheritance
object
SurfaceMap
Namespace: NWH.VehiclePhysics2.GroundDetection
Assembly: NWH.VehiclePhysics2.dll
Syntax
[Serializable]
public class SurfaceMap

Fields

name

Display name for this surface map. Used for organization and debugging purposes only. Does not affect functionality but helps identify the surface type in editor and debug logs.

Recommended naming: Use descriptive names matching the surface type (e.g., "Asphalt", "Wet Grass", "Sand").

Declaration
[Tooltip("Name of the surface map. For display purposes only.")]
public string name
Field Value
Type Description
string

surfacePreset

The surface preset that defines all properties for this surface type including friction characteristics, particle effects, skidmark settings, and audio properties. This preset will be applied to any wheel that matches the terrain texture indices or object tags specified in this surface map.

The SurfacePreset contains:

  • FrictionPreset for wheel physics (grip, slip curves)
  • Rolling resistance multiplier
  • Particle emission settings (dust/smoke)
  • Skidmark appearance and intensity
  • Surface-specific audio clips and volumes

Multiple SurfaceMaps can reference the same SurfacePreset if different terrain textures or tags should behave identically (e.g., multiple dirt texture variations using the same dirt preset).

Declaration
[Tooltip("Surface preset defining the properties for this surface type.")]
public SurfacePreset surfacePreset
Field Value
Type Description
SurfacePreset

tags

List of Unity tags that identify objects as this surface type. When a wheel collides with an object that has any of these tags, this surface map will be matched and its SurfacePreset applied.

Tag-based detection takes priority over terrain texture detection. This is useful for:

  • Non-terrain surfaces (roads, bridges, ramps, tracks)
  • Special surface areas that override terrain textures
  • Objects that should have specific surface properties regardless of underlying terrain
  • Indoor environments or non-terrain levels

Tags must be created in Unity's Tag Manager before being added to this list. Multiple tags can be added to match different object types to the same surface preset.

Example setup:

  • Asphalt SurfaceMap tags: "Road", "Bridge", "Parking"
  • Ice SurfaceMap tags: "Ice", "FrozenLake"
  • Wood SurfaceMap tags: "WoodBridge", "Deck"

Performance note: Tag comparison is very fast and happens before terrain texture sampling, making it an efficient way to handle non-terrain surfaces.

Declaration
[Tooltip("Objects with tags in this list will be recognized as this type of surface.")]
public List<string> tags
Field Value
Type Description
List<string>

terrainTextureIndices

List of terrain texture indices that represent this surface type. These indices correspond to the order of textures in the terrain's Paint Texture settings, starting from 0 for the first (top-left) texture.

When a wheel is on terrain, the ground detection system samples the terrain splatmap to determine which texture is dominant at that location, then checks if that texture index exists in any surface map.

Important notes:

  • Index 0 = first texture in terrain settings (top-left in Paint Texture panel)
  • Index 1 = second texture, index 2 = third texture, and so on
  • Must match the exact texture order in your terrain setup
  • Indices are zero-based (first texture is 0, not 1)
  • Multiple surface maps can reference the same texture index for different effects (though only first match is used)

Setup workflow:

  1. Open your terrain's Paint Texture panel
  2. Note the order of textures (starting from 0)
  3. Add the corresponding index to this list for textures representing this surface

Example:

  • Terrain has: [0] Grass, [1] Dirt, [2] Rock, [3] Sand
  • Grass SurfaceMap: terrainTextureIndices = {0}
  • Dirt SurfaceMap: terrainTextureIndices = {1}
  • Rock SurfaceMap: terrainTextureIndices = {2}
  • Sand SurfaceMap: terrainTextureIndices = {3}

Multiple indices can be added if several terrain textures should use the same surface properties (e.g., {1, 4, 7} for different dirt texture variations).

Declaration
[Tooltip("Indices of terrain textures that represent this type of surface. Starts with 0 with the first texture being in the top left corner under terrain settings - Paint Texture.")]
public List<int> terrainTextureIndices
Field Value
Type Description
List<int>

See Also