Material effects in CryENGINE are defined as the way a surface material reacts to other materials. For example, a metal material will react to bullet impacts differently (that is, by generating sparks) than a grass material does (that is, by generating dirt or dust). Because hardcoding these effects in C++ would require a huge amount of maintenance, these effects are exposed through a number of small asset files.
It is important that the files involved in this recipe are explained.
The SurfaceTypes.xml, defined in <CryENGINE_root>/<game_folder>/Libs/MaterialEffects/SurfaceTypes.xml, defines the physical properties of all the available material types. It can be edited with any text editor. The MaterialEffects.xml, which usually resides in <CryENGINE_root>/<game_folder>/Libs/MaterialEffects/MaterialEffects.xml, defines the interaction of two materials as it defines what effect to generate on an interactive event between two surface types. For example, it defines that when a bullet collides with the soil surface, a dirt particle effect is spawned. This file must be read and edited with Microsoft Excel. The Effect libraries, found in <CryENGINE_root>/<game_folder>/Libs/MaterialEffects/FXLibs, contain the associated effects.
Let's create a material effect.
Material effect events are those events that occur on interactions between two surface types, as defined in MaterialEffects.xml.
In this example, we will add a flow graph that is to be played as the event:
- The first thing that you should do to make your own FG effect is to create a new
.xmlinGameLibsMaterialEffectsFXLibs. - This file should be saved as
newfx.xmland its content should be as follows:<FXLib> <Effect name="hit_mat_wood_custom" delay="0.05"> <FlowGraph name="hit_effects_fg" maxdist="10"/> </Effect>
In this example, I've set this event to fire a flowgraph called "hit_effects_fg" within a maximum distance of 10 meters from the event's location.
Now that we have a new entry to access, we need to add it to the
MaterialEffects.xml. Open theMaterialEffects.xmlin Excel.
- Enter the new MFX event. The previous example enters the event into the "bullet" row and the "mat_wood" column. You can see the way the material event is read by entering the new event as the
libraryname:eventname, so mine isnewFX:hit_mat_wood_custom. - Create a flow graph.
The previous example shakes the camera for the player.
- Once you have created the flow graph, go to File | Save As in the flow graph editor and save it with the name you registered in the event earlier in the
<FlowGraph name="hit_effects_fg" maxdist="10"/>line of the event. For this example, it is hit_effects_fg. - Now that it's all saved and the events are being called when the bullet impacts the wood, start up sandbox and go shoot some wood and you'll see that the event triggers and the flow graph is activated.
The cross-reference between two 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).
There are many parameters that can be added and tweaked to the Material Effects system, such as bullet pierceability through materials and creating all new surface types.
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.
New surface types have to be added both as a row and as a column, and have to be kept in the same order.
With the existence of surface effects, we can apply some advanced characteristics to materials in the engine.
Some of the parameters that are added to the physics block are:
- Pierceability is an 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
- Friction defines 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
- Go to Chapter 9, Game Logic to learn more about Game Logic and FlowGraph scripting.