From Blue Mars Developer Guidebook

This page is protected and certified by Avatar Reality Inc. Only Editable by Avatar Reality Staff Members.

Contents 1 Material Effects Overview 1.1 Replacing Material Effects 2 Surface Types 3 Material Effects 4 FX Libs 4.1 Collisions 4.2 Footsteps 5 Testing & Debugging 6 Usage: Assigning Surface Types 6.1 Do not assign these Surface Types

Material Effects Overview

Material Effects and Surface Types are defined in the following interrelated files. A Material Effect is triggered when two Surface Types come in contact, or a footstep takes place on a Surface Type. A Surface Type is assigned to a physical object's physical sub-material.

• Libs/MaterialEffects/
  • MaterialEffects.xml - references material effects such as collisions and footsteps (according to Surface Types in contact)
  • SurfaceTypes.xml - contains Surface Type definitions including physics friction and elasticity settings
  • FXLibs/ - these files define the effects which can contain sound, decal, particle effects
    • collisions.xml - defines collision effects
    • footsteps.xml - defines footstep effects
    • etc...

Replacing Material Effects

Since these files are interrelated, in order to alter or replace any of these files for your city, the whole set of files needs to be supplied under your vendor-specific directory under /Libs/ (see the Directory Structure guidelines). I.e., Game/Levels/CompanyCode/Common/Libs/MaterialEffects or Game/Levels/CompanyCode/CityName/Libs/MaterialEffects).

An easy way to do this is to use our sample files (File:MaterialEffects.zip) as a starting point, then you can:

• replace sound, particle, decal effects in an FXLibs effect
• add new FXLibs effects (e.g., new footstep or collision effects)
• alter physics settings in existing surface types (e.g., friction, elasticity in SurfaceTypes.xml)
• add your own Surface Types
• alter which effects are triggered by particular material interactions (e.g., change which effect is triggered for a collision or a footstep on a particular surface type in MaterialEffects.xml)

Surface Types

Material physical definitions are defined in SurfaceTypes.xml, which should be edited in a text editor

<SurfaceTypes>
  <SurfaceType name="mat_golfBall">
    <Physics friction="0" elasticity="0.3" />
  </SurfaceType>
  ...

• Friction -- when two materials come in contact, the average of their two friction settings is the resulting friction; most values are between 0.1 and 1.5, however some are higher (glue = 50); the value can also be negative
• Elasticity -- most values are between 0 and 0.3; value can also be negative (usually -1 or -2)
• Pierceability -- (less applicable to Blue Mars) range: 0-14; 0 is bulletproof, 8 is used for metal, 10 is used for a softer pierceable surface, 14 is used for leaves which anything can go through

Surface Types are assigned in the Material Editor (or an .mtl file), and only need to be assigned to the physical sub-material.

Material Effects

Material interactions are stored in a matrix-like library in Libs/MaterialEffects.xml

• This spreadsheet should be opened in Excel
  • The list of Surface Types appears in the first column and is repeated in the first row to create a table of effects triggered when two materials (Surface Types) come in contact
  • There is a single footsteps row in the first column which is used to reference effects (defined in footsteps.xml) triggered when an avatar steps on a Surface Type

Below is an example of two plastic materials coming in contact: the mat_plastic row meets the mat_plastic column at a cell which contains the collisions:plastic_plastic effect. This effect would be defined as plastic_plastic in the collisions.xml file. Note that the collisions spreadsheet is shown here as an illustration, but should be edited in a text editor.

FX Libs

The FX Libs directory contains files for collisions and footstep effects (along with destructibles, vegetation, etc.). Effect definitions can include sound, particles, and decals. It is also possible to define the minScale, maxScale, and decal material for a random effect of decals to be placed on the collision spot; this is done similarly for particles (see the sand footstep effect below).

A tip on sounds: make sure your sounds are properly setup as described in Sound Creation. When a sound event is referenced in an FXLibs file, the path starts with levels/.../sounds/ and note that the particular sound directory is followed by a colon (:), not a forward slash (/). In the example levels/ar/common/sounds/golf:golf_sfx:land_rough, golf is the sound directory and FMOD project name, golf_sfx is the FMOD event group, and land_rough is the sound event.

Collisions

• Libs/MaterialEffects/FXLibs/collisions.xml should be edited in a text editor
• Collisions are defined in this file and then entered in the MaterialEffects.xml spreadsheet according to SurfaceType row/column intersection

<FXLib>
  <Effect name="golf_ball_fairway">
    <Sound>
      <Name>levels/ar/common/sounds/golf:golf_sfx:land_rough</Name>
    </Sound>
  </Effect>

  <Effect name="golf_ball_green">
    <Sound>
      <Name>levels/ar/common/sounds/golf:golf_sfx:land_green</Name>
    </Sound>
  </Effect>
  ...
</FXLib>

Footsteps

• Libs/MaterialEffects/FXLibs/footsteps.xml should be edited in a text editor
• Footstep effects are defined in this footsteps.xml file and then entered in the footsteps row in MaterialEffects.xml

<FXLib>
  <Effect name="grass">
    <Sound><Name>sounds/AR/Common/physics:footstep_walk:mat_grass</Name></Sound>
  </Effect>

  <Effect name="sand" >
    <Sound>
      <Name>sounds/AR/Common/physics:footstep_walk:mat_sand_dry</Name>
    </Sound>
    <Particle>
      <Name minscale="0.9" maxscale="0.9" maxscaledist="100">collisions.footsteps.sand</Name>
    </Particle>
    <RandEffect>
      <Decal minscale="0.14" maxscale="0.14">
        <Material>materials/ar/common/decals/sand/footstep_sand</Material>
      </Decal>
    </RandEffect>
  </Effect>
  ...
</FXLib>

Testing & Debugging

Use mfx_Debug 1 in the console to enable Material FX debugging in the City Editor. Other Console/MaterialEffects commands are also available.

Here's an example of the information logged for the golf ball/sand collision with mfx_Debug enabled:

[MFX] Running effect for:
      : SrcClass=RigidBodyEx SrcName=Ball1 Arch=Golf.ball
      : Mat0=mat_golfBall
      : Mat1=mat_sand_dry
impact-speed=4.339306 fx-threshold=2.000000 mass=0.032500 speed=0.083687

Use s_DebugSound 1 in the console to enable sound debugging in the City Editor.

A footstep which triggers a sound will be logged:

sound sounds/AR/Common/physics:footstep_walk:mat_sand_dry loaded

Usage: Assigning Surface Types

As mentioned above, a Surface Type is assigned to a physicalized/proxy sub-material in the Material Editor. If you do not need any material effects for a surface, or want to delay the decision, assign mat_blank which has no sound/decal/particle effects associated with it. The Surface Type drop down menu is pictured below:

If a physical material has no Surface Type assigned (or mat_default), you will see the following level load error in the City Editor:

Physical object has material (*) with invalid Surface Type. Please assign a proper value or mat_blank

Do not assign these Surface Types

For the most part, the current list is stable. However, some types should be avoided if your city is using the standard Material Effects files. The following list, which appears in bottom section of SurfaceTypes.xml, contains code-dependent surface types which may be removed in the future and therefore should be avoided at this point.

• mat_invulnerable
• mat_kevlar
• mat_metal_barbwire
• mat_hand_left
• mat_hand_right
• mat_head
• mat_helmet
• mat_torso
• mat_arm_left
• mat_arm_right
• mat_leg_left
• mat_leg_right
• mat_foot_left
• mat_foot_right
• mat_rock_vehicleonly
• mat_metal_vehicleonly
• mat_glass_vehicle
• mat_wood_vehicleonly
• mat_concrete_vehicleonly

The following should also be avoided:

• mat_default (for default footsteps sounds, use mat_asphalt or mat_concrete)