Add tutorial for footsteps playback on surface type

Author: mafiesto4

manual/physics/index.md

@@ -37,4 +37,4 @@ Using built-in physics engine helps with creating realistic behaviour for game o
 
 * [How to create a bouncing ball](tutorials/bouncing-ball.md)
 * [How to use a trigger](tutorials/use-trigger.md)
-
+* [How to play footsteps on different surfaces](tutorials/footsteps.md)

manual/physics/tutorials/footsteps.md

@@ -0,0 +1,72 @@
+# HOWTO: Play footsteps on different surfaces
+
+In this tutorial, you will learn how to create a script that will play different footstep sounds for the player depending on the surface type underneath. It uses raycasting down the player's feet to detect the physical material under the player and play matching sound effect. Script utilities `Tag` which improves readability of gameplay components (relation between physical material type and sound effect).
+
+## 1. Create a script
+
+Firstly we need to write a script (named for example `Footsteps`). It will handle the logic that detects the surface type and play the proper sound. To learn more about creating scripts see [this page](../../scripting/new-script.md).
+
+```cs
+using System.Collections.Generic;
+using FlaxEngine;
+
+public class Footsteps : Script
+{
+    /// <summary>
+    /// Maps surface type (Tag rom Physical Material) to the audio clip for footstep playback.
+    /// </summary>
+    public Dictionary<Tag, AudioClip> SoundPerSurfaceType = new();
+
+    /// <summary>
+    /// Mask with all layers of the world object - except player (to prevent raycasting itself).
+    /// </summary>
+    public LayersMask WorldLayersMask = LayersMask.Default;
+
+    /// <summary>
+    /// Sound volume.
+    /// </summary>
+    public float Volume = 1.0f;
+
+    public override void OnUpdate()
+    {
+        // This can exist in AnimEvent for animated character footsteps or in player movement script
+        // For explanation purpose, run on Spacebar key
+        if (!Input.GetKeyDown(KeyboardKeys.Spacebar))
+            return;
+
+        // Raycast physical surface below the actor
+        var feetLocation = Actor.Position;
+        if (Physics.RayCast(feetLocation, Vector3.Down, out RayCastHit hit))
+        {
+            // Try get sound for a specific physical surface material (empty tag as a fallback)
+            var tag = hit.Material ? hit.Material.Tag : new Tag();
+            if (SoundPerSurfaceType.TryGetValue(tag, out AudioClip sound))
+            {
+                // Play sound at feet position (with auto-destroy)
+                var source = new AudioSource
+                {
+                    HideFlags = HideFlags.DontSave,
+                    Volume = Volume,
+                    Clip = sound,
+                    Position = feetLocation,
+                };
+                Level.SpawnActor(source);
+                source.Play();
+                Destroy(source, sound.Length);
+            }
+        }
+    }
+}
+```
+
+## 2. Setup a script
+
+![Setup a Script](media/footsteps-properties.png)
+
+Add a script to the created player or test actor, uncheck the layer with player actor from `WorldLayersMask`, and setup `SoundPerSurfaceType` to contain various surface types. That dictionary maps `Tag` into `AudioClip`. Tag has to match tag assigned in [Physical Material](../physical-material.md). It is a common practice to use namespaces for better organization of the surface types. For example, `Surface.Dirt`, `Surface.Metal` and so on.
+
+![Physical Material Properties](media/footsteps-materials.png)
+
+## 3. Test it out!
+
+Hit **Play** button and test script by pressing `Spacebar` key to test sound when actor is above certain collider - it works with [Terrain](../../terrain/collision.md) layers too.

manual/physics/tutorials/index.md

@@ -2,3 +2,4 @@
 
 * [How to create a bouncing ball](bouncing-ball.md)
 * [How to use a trigger](use-trigger.md)
+* [How to play footsteps on different surfaces](footsteps.md)

manual/physics/tutorials/media/footsteps-materials.png

@@ -23,6 +23,7 @@ You can use **Ctrl + F** to quickly find what you are looking for.
 * [How to spawn a prefab](../../get-started/prefabs/spawning-prefabs.md)
 * [How to create a bouncing ball](../../physics/tutorials/bouncing-ball.md)
 * [How to use a trigger](../../physics/tutorials/use-trigger.md)
+* [How to play footsteps on different surfaces](../../physics/tutorials/footsteps.md)
 * [How to create a decal](../../graphics/decals/create-decal.md)
 * [How to report a bug](../../contributing/report-a-bug.md)
 * [How to use raycasting](../../physics/raycasting.md)

manual/physics/tutorials/media/footsteps-properties.png

@@ -6,3 +6,8 @@ Terrain uses heightfield collider per terain patch. You can specify the **Collis
 
 If your game uses runtime-generated terrain then ensure to enable **Support Cooking At Runtime** option in Physics Settings to support generating heightfield data at runtime.
 
+## Physical Materials
+
+![Terrain Physical Materials](media/terrain-physical-materials.png)
+
+Terrain supports up to 8 different physical materials assigned for each Terrain Layer - can reflect material appearance.

manual/samples-tutorials/tutorials/index.md

@@ -398,6 +398,7 @@
 ## [Tutorials](physics/tutorials/index.md)
 ### [How to create a bouncing ball](physics/tutorials/bouncing-ball.md)
 ### [How to use a trigger](physics/tutorials/use-trigger.md)
+### [How to play footsteps on different surfaces](physics/tutorials/footsteps.md)
 
 # [Particles](particles/index.md)
 ## [Particle Emitter](particles/particle-emitter.md)