Animals

The animals as a seperate model type and wildlife animals are a new feature in Transport Fever 2. Basically they are models as any other object in the game but they have some unique events and a special metadata block.

In addition to the general .mdl properties, animals use the cameraConfig block as players can follow animals in first person view. Furthermore, there is a metadata block called animal:

function data()
return {
  -- bounding box
  -- collider
  -- lods
 
  metadata = {
    description = {
      description = _("salmon-description"),
      name = _("Salmon"),
    },
    cameraConfig = {...},
    animal = {
      config = {...},
      flockName = "",
      flockFormationFn = "models/model/animal/animal.flock.salmon",
      movement = {...},
      movementTypes = {...},
      suitableAreas = {...},
    },
  },
  version = 1,
}
end

The name is shown as the default name if the user clicks on an animal. It can be translated in a strings.lua file.

The cameraConfig block is used for the first person view. To learn how to define camera views, read the relevant section in the model definition documentation.

The animal block is described below.

The config block contains several general properties for animals:

• density is a float value. Land animals and birds usually have value 1, fishes have density 4.
• fish is a boolean value. When it is set to true, the animal is restricted to water.
• idleTime is the time that is spent in idle mode before moving somewhere else.
• predator is a boolean value. If set to true, this animal will be avoided by some others, e.g. deers avoid bears.
• targetDistance is a float value. It is the distance in which the animals look for new target locations.

Birds and Fishes may travel around in flock formations. If an animal has a configured flock, it will move in this group. Otherwise the animal will move alone.

The flock formations have a name that is specified in flockName. The formation is configured in an external .script file. This is referenced in flockFormationFn. The path is relative to the res folder. If the reference is “models/model/animal/animal.flock.salmon”, then the actual file is in “res/models/model/animal/animal.script”. The function for the flock has no parameter and a list of vectors with x,y and z values is expected. These vectors are relative to the flock origin.

The external file looks like this:

function data()
return {
  flock = {
    salmon = function() ... end
  },
  ...
}
end

The movement block describes some restrictions regarding where the animals move:

• alignToTerrain is true for land animals, as they move along the terrain surface. Birds or fishes have the property set to false.
• heightOffset is the value they are offsetted of the water height if alignToTerrain is false or the terrain surface, if alignToTerrain is set to true. Fishes usually have negative values, birds have positive values.
• rollWhileTurning is set to true if the animal should roll a bit when turning around curves. Usually that is done for birds.
• stickToWater restricts animals to water areas. This is set to true for fishes.
• wobbleWhenIdle is set to true, if the animal should move slightly in idle state. This is usually used for fishes too.

It is possible to define several movement types. For example, land animals can stay around (idle), walk and run. For each of the movement types, there is a block in the movementTypes list with the following properties:

• angularSpeed is the turn speed. Slow angular speed results in the animal having very large curve radii.
• description is a translatable String to describe the current action. It is shown in the animal detail window.
• eventName is the name of the event that is defined in the levels of detail.
• playOnce is set to true, if the animation is not looping, e.g. when the animal dies.
• playRandomly is set to true, if this movementType can occure randomly. The normal behaviour of an animal is a series of such random animations.
• playWhenSelected is set to true if the animation should be played whenever the player clicks on the animal. For example, a bear is roaring.
• speed is the speed of the animal while this animation is played. It is specified in meter per second.

The suitableAreas block is used to limit the occurance and movement of animals to certain areas. There are several terrain related factors as well as factors related to other animals. All factors are mapped to scores. The overall sum of scores summarizes the likelyhood of the animal existing in a certain spot. If an animal gets into an area with negative score, it will try to run away. If it fails to leave the non suitable area it will eventually die.

• bias is a static score offset applied to any animal.
• height is a block property that maps an interval of heightlevels mapFrom to an interval of scores mapTo. Height values below the lower interval limit are considered equal to the lower limit, height values above the upper limit are considered equal to the upper limit.
• noise is a block property that maps an interval of emission levels mapFrom to an interval of scores mapTo. Height values below the lower interval limit are considered equal to the lower limit, height values above the upper limit are considered equal to the upper limit.
• scores is a block of criterias with static scores:
  • civilisation is everywhere were AI or player constructed buildings and streets are.
  • fish is the area around water animals.
  • forest is the area around trees.
  • predator is the area around animals with config.predator == true.
  • ship is the area around ships on rivers or lakes.
  • shore is the area along river and lake borders.
  • water is the area where there is water.
• slope is a block property that maps an interval of steepness levels mapFrom to an interval of scores mapTo. Height values below the lower interval limit are considered equal to the lower limit, height values above the upper limit are considered equal to the upper limit.

It is possible to analyze the score factor maps with the ingame debug tools.

The events of animals are mostly defined by their movementTypes. The most common events are:

• idle animation is used for a resting animal or for sailing birds. It can be looped.
• idle_standing animation is used for resting birds. It can be looped.
• walk / fly / swim animations are used for actively moving animals. It can be looped.
• run animation is used for fast moving animals. It can be looped.
• roar / intimidate / eat / pee / baa / kick / sitdown animations are used for random events or when the player clicks on an animal.
• die is used for the end of life sequence of an animal. It is played only once.