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

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

Parameter

Description

friction

A material's friction (friction is the average of contacting materials). A recommended default is 0.8. Internally it's clamped to 0.1 if it's below that.

elasticity

Also known as Bounciness. It's averaged from 2 materials. Clamped to 0 as the elasticity can't be negative. Recommended default is 0, unless you specifically want something bouncy.

breakable_id

Procedural breakability index; a corresponding boolean cutter shape should be registered in the physics.lua.

pierceability

Integer from 0-15, with 0 being the least pierceable. For each ray, a hit is pierceable if ray's pierceability is less than the material's pierceability.

break_energy

Energy= (mass*velocity^2/2) and it refers to the colliding object that triggers breaking (typically should be tweaked based on bullets' params).

hit_points

Each collision above break_energy takes round_to_int(collision_energy/break_energy) hitpoints; real breaking only happens when hitpoints are depleted.

hit_maxdmg

Max amount of hitpoints a single hit can take.

hit_radius

Hitpoints can be localized with this radius (i.e. it'll require that all hits are within this radius from each other); 0 disables.

hit_lifetime

Lifetime for localized hits info, it expires after that (note that it's just a hint; it can expire earlier if there are too many newer hit infos, or later if there's no concurrency).

hole_size

Characteristic size for boolean carving; shape registered in physics.lua is scaled by this size / shape's characteristic size (specified in physics.lua).

hole_size_explosion

Same as above, but for explosions (first one is for collisions with bullets and general physicalized objects).

breakable_2d

If set, uses 2D breakability instead of 3D boolean carving.

vehicle_only_collisions

Entire node will only collide with vehicle (even if material with this flag is only applied to some triangles of it).

<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

Parameter

Description

blast_radius

Procedural hole size (note that when an object hits the surface, it will use the colliding area's size instead – unless it's smaller than this).

blast_radius_first

Same as above, but for the first hit that breaks the object.

vert_size_spread

Vertical hole size = blast_radius * (1+random(0..vert_size_spread)).

rigid_body

Broken pieces will be physicalized as rigid bodies (otherwise as physical particles).

lifetime

Pieces will expire after that (currently it'll only happen when the player looks away, but that might change).

cell_size

Cell size for the breakage grid (default 0.1).

max_patch_tris

Governs the number of grid triangles in each shard (triangles are taken from the breakage grid, around the hit point and within blast_radius); default is 6.

filter_angle

Filters the hole's edges with this angle to avoid the 'saw tooth' look; default 0 (disabled), but 75 seems to look good in most cases.

shard_density

Used to calculate shards' masses and buoyancy (float/sink) properties; default 1200.

max_fracture

Triggers full fracture when the object is damaged beyond this (0..1); default 1.

particle_effect

Name of the effect to generate along the broken edges.

fracture_fx

Single effect for each breakage.

full_fracture_fx

Effect to play when a full fracture condition is triggered.

no_procedural_full_fracture

In case of full fracture, doesn't generate broken pieces procedurally, relies only on full_fracture_fx.

use_edge_alpha

Sets alpha of vertices along the broken edges to 0 (should be used if there's a special shader that expects that).

crack_decal_mtl

Puts a decal with this material whenever a break occurs.

crack_decal_scale

Sets the decal size wrt the hole size (0 disables crack decals).

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:

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.

Ammo surface types do not need to be added to the SurfaceTypes.xml file.

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:

Attribute

Description

direction

Effect spawn direction:
"Normal" : (default) surface normal.
"Ricochet" : reflection of hit source direction off surface normal.
"Reverse" : reverse of hit source direction.

minscale / maxscale

Scale to apply to effect when it's near / far from camera.

maxscaledist

Distance at which maxscale applies.

maxdist

Max distance to show effect.

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:

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

Non visual debug information will be shown in the console.

Reloading

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

Because it is necessary to have matching rows and columns in the MaterialEffects.xml file it is possible to set mfx_debug to 1/2/3 for an automatic check before reloading the Material Effects. Any warnings are outputted to the console.

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.

创建和编写材质特效

材质特效是两种特定材质互相发生作用时的特有现象。举例来说,一个子弹击中金属表面会发出火花,而子弹击中草地则只能溅起泥土。因为这些效果在代码中硬编码就不可能保持刷新,这些效果通过少量资源文件来表现:

文件总览

新建表面类型

添加一个表面类型到 SurfaceTypes.xml

表面类型是由 SurfaceType 的 xml 文件类型所定义。其属性*名称*可在 Sandbox 编辑器中选择。这里定义的表面类型将作为材质编辑器下拉列表中的选项。其它属性*类型*为可选项。可以被游戏代码在其他进程调用。物理参数由*物理元素*定义。

物理参数表:

参数描述
friction材质的摩擦力(摩擦力是接触材质的平均值。)建议默认值为 0.8,最低值为 0.1。
elasticity弹性可以理解为弹开度,在两个物体间普遍存在,被降低到 0,就是两个物体不会互相反弹。 如果你不想要什么被弹开,建议设置为 0。
breakable_id碎裂方式索引表,在 physics.lua 文件中注明了应当发生的碎裂方式.。
pierceability范围从 0~15,0 是最小阈值。每次击中发生时,材质穿孔性大于射击物的穿孔性,则会发生穿孔。
break_energy公式:能量=(质量×速度^2/2)涉及到物体碰撞引发碎裂(碎裂度取决于子弹的参数。)*
hit_points每次表面的碰撞会产生一个单次打击点(碰撞能/打击力)打击点耗尽后,碎裂随即发生。
hit_maxdmg每次打击能产生的最大打击点数量。
hit_radius限定打击点在半径范围内(即要求所有打击须在这个半径内),禁用 0。
hit_lifetime局部承受打击的寿命信息,旋即会过期(注意:这是一个提示,如果有太多的新的袭击同时发生它可以提前到期,或者延迟。)
hole_size碎裂外观的尺寸,这个值指定在 physics.lua 文件中,定义碎裂形状半径/平面碎裂半径。
hole_size_explosion与上面含义相同,但用于爆炸(第一个是用于子弹产生的物理碰撞)。
breakable_2d设置后,平面碎裂将替代三维碎裂.。
vehicle_only_collisions用于交通工具撞击的项目节点(也用于在材质中仅仅标记在某些三角面的情况)。
<SurfaceType name="mat_new_material">
 <Physics friction="0.5" elasticity="1"  pierceability="3" can_shatter="1"  />
</SurfaceType>

破碎参数由 breakable_2d 元素来定义。

breakable_2d 参数表::

参数描述
blast_radius生成孔洞尺寸(注:当一个物体撞击表面,它将使用碰撞面积的尺寸来替换,除非是它小于这个数值)。
blast_radius_first同上,但仅是作用于物体的首次爆裂.。
vert_size_spread垂直孔尺寸= blast_radius (1 +random(0 . . vert_size_spread)
rigid_body碎片被作为刚性体(否则物理粒子)。
lifetime碎块延续时间段(目前只会发生在主角视线漂离后,但这可能改变)。
cell_size破损网格的单元尺寸(默认0.1)。
max_patch_tris指定各个方向碎裂三角形网格的数量(三角形网格生成自破损中心的半径范围),默认值为 6。
filter_angle为避免“锯齿”出现,在洞口边缘的过滤角,默认 0(禁用),但是 75 也有不错的效果。
shard_density用于计算碎片的质量及浮力(浮/沉)属性,默认1200。
max_fracture判定的对象完全损坏的碎裂值(0 . .1);默认 1。
particle_effect沿断裂边缘产生的效果的名称。
fracture_fx每个破坏的单独效果。
full_fracture_fx完全损毁被触发后的整体特效。
no_procedural_full_fracture完全损毁状况,不生成碎块,而只依赖于整体损毁特效。
use_edge_alpha碎裂边际的 alpha 效果(如有特别效果指定产生)。
crack_decal_mtl碎裂发生后被替换在体表的疤痕材质。
rask_decal_scale设置生成疤痕的孔洞尺寸(0 是禁用疤痕)。

除了*<Physics 物理>元素,可选的< BreakageParticles >*定义的粒子类型会引发破损。其属性*类型*定义碎裂类型时采取下列的值:

特效*属性指出将引发破损的粒子效果,将引发了破损,同时属性 *count_per_unitcount_scale 和*scale* 分别定义产生的粒子系统和缩放的数量。通常情况下,它们的值应该是 1

 

Note
弹药表面类型不需要添加到 SurfaceTypes.xml 文件中。

 

添加事件到 MaterialEffects.xml

新型表面类型要增加一个循环,既作为一个专栏,而必须保持为相同的顺序。2 个表面类型间的相互参照定义互动时将发生的事件的类型。仅由代码调用的表面类型只需要有行并且必须添加到底部,位于 SurfaceTypes.xml 定义的表面类型之下。(除了在需要通过材质编辑器使用时)。

添加材质特效事件

材质特效 (MFX) 事件是发生在两个表面相互作用时候发生的事件,如 *MaterialEffects.xm*l 所定义。他们按照以下格式指定名称:

<MFX_lib_name>:<MFX_name>

例如,For instance, bulletimpacts:hit_mat_soil 指向事件(和 XML 元素)hit_mat_soil defined in Game/Libs/MaterialEffects/FXLibs/bulletimpacts.xml。如下方式定义:

<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>

每个特效名称可有以下附加属性选项:

属性描述
方向特效产生的方向:“曲面”:(默认)曲面法线“跳弹”: 从曲面法线撞击源方向的反射: 撞击源方向的背面
minscale / maxscale靠近/远离摄像机时应用的比例
maxscaledistmaxscale 应用的距离
maxdist显示特效的最大距离

添加弹药表面类型

弹药表面类型为弹药文件中的 XML 元素*弹药*的属性*名称*。它的值要和在 MFX 表中的值相同。

除错

在 Sandbox 编辑器或启动器中 存在几个控制台变量用于进行材质特效调试:

 

Note
非可视调试信息会显示在控制台上。

 

重新加载

要从 MaterialEffect.xml 文件中重新加载所有材质特效,可以使用控制台命令 mfx_reload

 

Note
因为必须匹配 MaterialEffects.xml 文件中的行和列,可以将 mfx_debug 设置为 1/2/3,以便在重新加载材质特效前自动检查。如有警告信息,将输出到控制台。

 

已知问题

当行和列中的顺序与计划不一致时,MFX 列表易发生破损和意外情况,例如在使用“查找/替换“或“插入单元格”后。