Overview

Material effects expose the way a surface material reacts to other materials. For example, a metal material will react to bullet impacts differently (i.e. by generating sparks) than a grass material does (i.e. by generating dirt or dust).

Because hard-coding these effects in code would be impossible to keep updated, these effects are exposed through a small number of asset files.

Files Overview

• The SurfaceTypes, defined in Game/Libs/MaterialEffects/SurfaceTypes.xml defines the physical properties of all the available material types. It can be edited with any text editor.
• The MaterialEffects, which usually resides in Game/Libs/MaterialEffects/MaterialEffects.xml, define the interaction of 2 materials, i.e. what effect to generate on an interactive event between 2 surface types. For example, it defines that when a bullet collides with the soil surface, a dirt particle effect is spawned. This file has to be read and edited with Microsoft Excel.
• The Effect libraries, found in Game/Libs/MaterialEffects/FXLibs, contain the associated effects. The ammo files in Game/Scripts/Entities/Items/Ammo define what material a bullet is made from.

Creating a New Surface Type

Adding a Surface type to SurfaceTypes.xml

A surface type is defined by the XML element SurfaceType. Its attribute name is the one that can be selected in the Sandbox Editor.

Surface types defined here will appear as options in the drop down list of the Material Editor. The other attribute type is optional. It can be used in other processes by game code. The physical parameters are defined by the Physics element.

Physics block

<SurfaceType name="mat_new_material">
 <Physics friction="0.5" elasticity="1"  pierceability="3" can_shatter="1"  />
</SurfaceType>

The breakable parameters are defined by the breakable_2d element.

breakable_2d block

Besides the <Physics> element, the optional <BreakageParticles> defines the type of particle that will be spawned on breakage. Its attribute type defines the break event and can take one of the following values:

• breakage
• joint_break
• joint_shatter
• destroy

The effect attribute points to the particle effect that will be spawned on breakage, along with the attributes count_per_unit, count_scale and scale defining respectively the number of particle systems to be spawned, and their scale. Normally, their value should be 1.

Adding Events to MaterialEffects.xml

New surface types have to be added both as a row and as a column, and have to be kept in the same order. The cross reference between 2 surface types defines the type of event that will happen on interaction.

Surface types that are only called by code are required to only have rows and must be added at the bottom, below the surface types defined in SurfaceTypes.xml (the exception is when it is needed to be used on materials through the Material Editor).

Obsolete:

It should be noted that Objects which need to use Alpha Test for Collision (railings, etc) should have a surface type with the suffix _RayProxy. This is also used to allow characters to see through glass objects and such as part of the perception system.

Adding Material Effect Events

Material effect (MFX) events are those events that occur at interactions between 2 surface types, as defined in MaterialEffects.xml. They are named according to the following schema:

<MFX_lib_name>:<MFX_name>

For instance, bulletimpacts:hit_mat_soil points to the event (and XML element) hit_mat_soil defined in Game/Libs/MaterialEffects/FXLibs/bulletimpacts.xml.

This event is defined as follows:

<Effect name="hit_mat_soil" delay="0.05">
  <Sound>
    <Name>sounds/physics:bullets/impacts:grass</Name>
  </Sound>
  <RandEffect>
    <Decal minscale="0.03" maxscale="0.07">
      <Filename>textures/decals/metal.dds</Filename>
      <Material>materials/decals/terrain_soil</Material>
    </Decal>
  </RandEffect>
  <RandEffect>
    <Particle>
      <Name direction="normal" minscale="0.6" maxscale="1.2" maxscaledist="80">bullet.hit_soil.a</Name>
    </Particle>
    <Particle>
      <Name direction="ricochet" minscale="0.6" maxscale="1.2" maxscaledist="80">bullet.hit_soil.b</Name>
    </Particle>
    <Particle>
      <Name direction="reverse" minscale="0.6" maxscale="1.2" maxscaledist="80">bullet.hit_soil.c</Name>
    </Particle>
  </RandEffect>
  <FlowGraph name="dirt_bullet_hit" maxdist="2"/>
</Effect>

Each effect Name can have the following optional additional attributes:

Adding an Ammo Surface Type

The surface type for ammunition is the attribute name of the XML element ammo in an ammo file. Its value is required to be the same as the value in the MFX table.

Debugging

There exist a couple of console variables to debug the Material Effects in the Sandbox Editor or the Launcher:

• mfx_Debug: 0 (Disabled) / 1 (Collisions) / 2 (Breakage) / 3 (Both)

  [MFX] Running effect for:
        : Mat0=mat_metal_shell
        : Mat1=mat_concrete
  impact-speed=5.756900 fx-threshold=2.000000 mass=0.018203 speed=0.147297
  

• mfx_DebugVisual: 0 (Disabled) / 1 (Basic visual debugging) / 2 (Enhanced visual debugging):
  
• mfx_DebugVisualFilter: 0 (Disabled) / Name (Only show visual debug information for this Material Effect).
• mfx_DebugFlowGraphFX: 0 (Disabled) / 1 (Show debug information for triggered Material Effect flowgraphs)

Material FlowGraphFX manager: Effect Test1 was triggered.
Material FlowGraphFX manager: Effect 'Test1' .Dynamic parameter 'BlendOutTime' set to value 0.056

Reloading

To reload all Material Effects from the MaterialEffect.xml file it is possible to use the console command mfx_reload.

Known issues

The MFX table is prone to breakage and unexpected behavior when the order in rows and columns is different from the expected one, e.g. after using find-replace and/or inserting cells.