Groundmodel Description File

Introduction

This refers to maps using Version 3 groundmodels ( 0.36.3 or above )

See Version Requirement if you come across an orange box next to a section and you don't know what it means.

Required files and their inputs

To edit a map and add ground models you need:
- to add a line to your .terrn file.
- One texture png with set hexadecimal colors.
- You need the file it links too the Yourmapsname?-landuse.cfg
- If your setting your own ground models you need a yourmapsname?-groundmodel.cfg if not, use the default groundmodels (see below).

---

.Terrn

The .terrn file needs to contain a line to point to the ground model file/'s.

landuse-config yourmapsname?-landuse.cfg

Yourmapsname?_traction.png

This image is usually the same size as your ground texture file. You must use the exact colors that you specify in the -landuse.cfg. Any unspecified colors will default to the default ground model specified in the -landuse.cfg.

Yourmapsname?-landuse.cfg

The -landuse.cfg basically links the colors in your .png image to the designated ground models of your choice. You can get the hexadecimal color values directly from the image by looking at your color pallet in most image editing programs.

In the following example, anywhere on the image that is painted blue (0000ff) will simulate rock.

[config]
# the texture to use
texture = yourmapsname?_traction.png
# the default terrain to be used, if not using landuse its 'gravel'
defaultuse = gravel
# the friction config to load, multiple lines possible to load multiple files
loadGroundModelsConfig = yourmapsname?-groundmodel.cfg
 
# the colour <--> ground type coupling
[use-map]
#colour format explanation: 0x[fixed!](2 Alpha Char)(2 Red Char)(2 Green Char)(2 Blue Char)
 
0xff575757 = concrete
0xffb0b0b0 = asphalt
0xff0000ff = rock
0xff352a00 = mudT1

Yourmapsname?-groundmodel.cfg

The yourmapsname?-groundmodel.cfg is where you define the ground type and feel. You don't have to make your own, you can use the default ground models by setting its name in the -landuse.cfg and if you don't need this file the you would enter ground_models.cfg in its place. The default types are: concrete, asphalt, gravel, rock, ice, snow, metal, grass, sand and mud

The first three lines of this file are as follows:

[general]
version = 3
description = Default Configuration

After this you place each ground type using the following format.
See below for more detailed information of this file.

Ground Model Examples

Example for hard ground types

This example shows one way to simulate a hard surface similar to rock.
NOTE: Hard ground types do not use any fluid parameters so they can be left out.

[rock]
adhesion velocity = 3.0
static friction coefficient = 0.75
sliding friction coefficient = 0.5
hydrodynamic friction = 0.007
stribeck velocity = 8
 
fx_type = PARTICLE
fx_particle_name = tracks/dust_soft
fx_colour = 0.83, 0.71, 0.64

Example for soft ground types

This example shows one way to simulate deep, thick mud using the fluid parameters.

[mudT1]
adhesion velocity = 2.2
static friction coefficient = 0.12
sliding friction coefficient = 0.05
hydrodynamic friction = 0
stribeck velocity = 3
 
fx_type = PARTICLE
fx_particle_name = tracks/dust_soft
fx_colour = 0.83, 0.71, 0.64
 
solid ground level = 2.3
fluid density = 150
flow consistency index = 2600
flow behavior index = 0.0
drag anisotropy = 1

Ground Model Parameters

Name

Name of the material

---

Solid Ground Friction

Adhesion velocity

Below this velocity, static friction rules, above it dynamic friction takes command. It should be something small, in the range of 0.1-0.4 . This velocity threshold is also used by the fluid physics, so you should always define it. NEVER have it at 0.

Parameter range 0.1 -> 0.5 (Never put it at 0)

Static friction coef

Static friction keeps you in the same place when you are stopped on a hill. In the real world this friction is always bigger than dynamic friction (sliding friction). Start with 0.5 and work from there. It is better to try to find some experimentally validated values for this and the rest of surface friction variables in the net, and then to fine tune via strength.

Parameter range 0.1 -> 2

Dynamic friction coef

Or sliding friction coef. It should be smaller than static friction coef. This parameter defines how much friction you'll have when sliding. Try to find some values for it from the net.
Parameter range 0.1 -> 1.5

Hydrodynamic friction coef

This friction defines the added friction that you'll feel from a surface that has a little film of fluid on it. It is kind of redundant with all the fluid physics below, but it is here so as for experimentally validated values from the net to be usable. If you decide that you'll simulate the film of fluid with the more complex fluid physics below, then just set this to 0.

Parameter range 0 -> 1.5 (maybe more)

Stribeck velocity

You'll either find stribeck velocity in the net, or the inverse (1/stribeck velocity) of it described as "stribeck coef". It defines the shape of the dynamic friction curve. Lets leave it at that. Just find some nice values for it from the net. Do  not change The Stribeck effect is described by the parameter v_st which is the characteristic Stribeck velocity. It denotes the sliding velocity where only a 37% of the static friction is active. In other words, small values of v_st give a fast decreasing Stribeck effect and large values of v_st give a slow decreasing Stribeck effect.

Alpha

Its usual value is 2. But you can try others.

Strength

This parameter raises or diminishes surface friction in a generic way. It is here so as to be able to do quick calibrations of friction. Start with having this to 1.0 and after tuning the rest of the surface variables, come back and play with this.

Parameter range 0 -> 2

---

Fluid Parameters

Solid ground level

With this you can define how deep the solid ground is. If it is 0 then the surface will be solid. If it is 0.1 then you'll have 10 cm of fluid on top of solid ground. If it is 100 then the solid ground will be way deep (100m), with fluid on top.

Parameter range 0 -> 200

Flow consistency Index

Think of it as default fluid resistance. Flow behavior index below changes it at real time. Useful values in practice are quite large.
Parameter range 10 -> 100000

Flow behavior index

If it is 1.0 then the fluid will behave like water. The lower you get from 1.0, the more like mud the fluid will behave, meaning that for small velocities the fluid will resist motion and for large velocities the fluid will not resist so much. The higher you get from 1.0 the more like sand the fluid will behave. The bigger the velocity, the bigger the resistance of the fluid (try to hit sand hard it'll feel like stone).

Parameter range -2 -> +2

Fluid density

In mud (or sand) the resistance of the fluid described by the parameters above will stop you and so keep you from sinking. But for substances like water it isn't the drag that stops you from sinking. Its buoyancy. This parameter is here so as to keep you from sinking when you wish to simulate fluids with low drag (resistance). For fluids like mud or sand you can put it at 0, but it is best to keep it at some minimum value. For fluids with behavior index >=1 it will behave like you are in water. For fluids with behavior index <1 it'll behave like you are in mud.

Parameter range 0 -> 1+

Drag anisotropy

This parameter makes getting out of the mud easier by creating a small force that lifts the vehicle upwards away from the mud. The lower the the number, the higher the force. If you want a fun arcade simulation of mud without the hassle of the recovery, set the value low near 0. But if you want the challenge of realistic mud, with high risk of getting stuck, just leave it at 1.

Parameter range 0 -> 1 (DO NOT SET IT OUTSIDE THIS RANGE)

---

Ground Debris FX

fx_type

The type of special effects that RoR will use to give the appearance of a surface. It doesn't affect the physics at all

fx_color

The color of RoR's special effects

See Also

Proposed Description File Sections

---