k8vavoom terrain extensions and bootprint definition, v0.91
===========================================================


terrain
=======

everything that is at https://zdoom.org/wiki/TERRAIN is supported (as of May, 2021).

in addition, you can modify an existing terrain by redefining it like:

  terrain Name modify {
    ...
  }

the difference between this and standard terrain override is that without "modify"
keyword, existing terrain will be reset to default values. if you'll try to modify
the definition that wasn't yet defined, "modify" will be ignored.

there are extended options for terrain, which should be used in "k8vavoom" block.

  terrain Name {
    ...
    k8vavoom {
      ...
    }
  }

this is done so other engines could simply skip the extensions without knowing how to
parse k8vavoom options.


extended options are:

noprotection
  removes "allowprotection" flag.

notliquid
  removes "liquid" flag.

nodamageonland
  removes "damageonland" flag.

playeronly
  this terrain definition is applied only for players. for other entities, default
  terrain will be used.

everybody
  removes "playeronly" flag.

optout
  if "gm_vanilla_liquids" cvar is false, default terrain will be returned instead of this one.

nooptout
  removes "optout" flag.

bootprint <name>
  bootprint definition for this terrain.
  note that bootprint flat (specified in bootprint definition) has higher priority.

detectfloorflat <globmask>
  flats matching this globmask will be marked as belonging to this terrain.
  this option can be specified several times, and it is cumulative.
  "globmask" is a wildcard expression, it supports "*" and ranges in "[]"


"land step sound" will be used when a player landed on the given terrain.
"small object" is the object with a mass less than 10, or with "small splash" flag set.
landing sound will be played regardless of splash object presence. i.e. you can use
landing sound to avoid spawning dummy splash objects. this sound will be played for both
liquids and normal terrains.
you can use zero volume to disable land sounds.

landvolume <float>
  landing sound volume, [0..1]. default is 1.0.

smalllandvolume <float>
  "small object" landing sound volume, [0..1]. default is 1.0.

alllandvolume <float>
  landing sound volume for both object types, [0..1]. default is 1.0.

landsound <soundname>
  landing sound name.

smalllandsound <soundname>
  "small object" landing sound name.

alllandsound <soundname>
  landing sound name for both object types.


footsteps are used to produce footstep sounds on a given terrain.
you can use zero time or volume to disable footstep sounds for a given mode.

walkingstepvolume <float>
  footstep sound volume when walking, [0..1]. default is 1.0.

runningstepvolume <float>
  footstep sound volume when running, [0..1]. default is 1.0.

crouchingstepvolume <float>
  footstep sound volume when crouching, [0..1]. default is 1.0.

allstepvolume <float>
  footstep sound volume for all modes, [0..1]. default is 1.0.

walkingsteptime <float>
  footstep sound interval when walking, in seconds. default is 0.0 (no sound).

crouchingsteptime <float>
  footstep sound interval when crouching, in seconds. default is 0.0 (no sound).

runningsteptime <float>
  footstep sound interval when running, in seconds. default is 0.0 (no sound).

allsteptime <float>
  footstep sound interval for all modes, in seconds. default is 0.0 (no sound).

leftstepsound <soundname>
  sound for the left foot.

rightstepsound <soundname>
  sound for the right foot.

allstepsound <soundname>
  assign the given sound for both feets.



bootprint
=========

this is bootprint definition section. it will use base bootprint decal (as specified
in `PlayerPawn`) to leave bootprints. You can change decal shade, translucency and
animator.

  bootprint VanillaWater {
    time   default  // or: time minsecflt maxsecflt
    shade "00 00 4f"
    translucent 0.6
    animator LiquidBootPrintFader
    flat   "fwater[0-9]"
  }

bootprint redefinition completely removes the old bootprint, including any flats for it.
i.e. redefined bootprint will not be assigned to any flats. you can use "modify" to
modify an existing bootprint. if you'll try to modify the definition that wasn't yet
defined, "modify" wiil be ignored.

note that bootprint decal should be drawn for the right foot. it will be mirrored for
the left foot. the engine will automatically apply some offset too, so decal sprite
"center point" should be roughly at the center of the decal.


booptprint options:

time <default | min max>
  how long the player should leave bootprints, in seconds?
  "default" is some default value (around 4.0 seconds).
  you can specify minimum and maximum time instead, and the engine will choose something
  in that range (inclusive) at random.

flat <globmask>
  globlask for flats that leaves this bootprint. this option is cumulative.

shade <color>
  set decal shade (as in decaldef):
    shade "ff 00 ff"

stade flatpic [maxout <byte>]
  decal shade will be taken as average color of the floor texture.
  note that this cannot be used for blood decal bootprints yet.
  "maxout" will scale the average color up to the given value.
  scaling is done by selecting maximum color component, and scaling others.
  i.e. like this:
    maxv = max(r, g, b);
    r = r*maxout/maxv;
    g = g*maxout/maxv;
    b = b*maxout/maxv;
  there are some special scaling values:
    0: don't scale
    1: multiply all color components by 1.5
    2: multiply all color components by 2.0
    3: multiply all color components by 2.5
    4: multiply all color components by 3.0
    5: multiply all color components by 3.5
    6: multiply all color components by 4.0
  default is 2 (i.e. multiply by 2.0).

shade fromdecal
  this is used for bootprints from floor decals.
  currently no extended options are available.
  this is default if no shade was specified.

translucent <float>
  set decal translucency

solid
  set translucency to 1.0

animator <name>
  force decal animator. you can use "none" to remove default decal animators.

usesourcedecalalpha
  this is useful for decals from bloodsplats: bootprint decal will take its
  translucency from the corresponding bloodsplat decal.



default bootprint animators
===========================

there are some predefined animators you can use for various bootprint types.

LiquidBootPrintFader
  this is default fadeoff animator for bootprints from liquids.



bootprints from floor decals
============================

flat decal definition can contain k8vavoom block to specify bootprints for such decals:

  k8vavoom {
    BootPrint K8Gore_BootPrint
  }



assign flats to bootprints and to terrains
==========================================

it is possible to use special blocks to assign flats to bootprints:

  assign_bootprint BootprintName {
    ...
  }

and to terrains:

  assign_bootprint TerrainName {
    ...
  }

currently, the only supported command in such blocks is:

  flat "globmask"



new `PlayerPawn` properties
===========================

you can use the following DECORATE properties to control player decal:

Player.BaseBootPrintDecal <name>
  set base decal name for bootprints.
  default is "BaseBootPrintDecal"

Player.BootPrintDelayTime0 <float>
Player.BootPrintDelayTime1 <float>
  delay between bootprints, in seconds.
  this specifies the interval, the actual time will be something in that
  interval (choosen by random). always specify both values.
  default is: 0.12 to 0.16

Player.BootPrintMinDist <float>
  minimum distance between two bootprints, in game units.
  default is 12

Player.BootPrintRadiusMult <float>
  actor radius will be multiplied by this value to calculate bootprint
  decal offset from the actor origin.
  default is 0.4

Player.BootPrintRandomOfs0 <float>
Player.BootPrintRandomOfs1 <float>
  a random value from this interval will be added to decal offset.
  default: 0 to 2


new `PlayerPawn` flags
======================

Player.BootPrintEnabled
  are bootprints enabled for this pawn?
  default: true

Player.BootPrintFlip
  should the engine flip bootprint decal for the left foot?
  default: true

Player.BootPrintFlipOffset
  should the engine flip bootprint decal offset for the left foot?
  default: true
