Automatically play footstep sounds based on surface materials in Godot 4
Explore the docs »
View Demo
·
Report Bug
·
Request Feature
Table of Contents
Godot Material Footsteps is an addon for Godot 4 that plays footstep sounds based on the surface your character is walking on. You can directly configure the surfaces in the editor inspector. It works with different setups, including metadata on meshes, GridMap tiles, HTerrain Classic4 shaders, Terrain3D and even direct surface material detection.
This addon is available on the Godot Asset Library.
- Multiple Detection Methods: Metadata, GridMap tiles, HTerrain shader support, and surface material detection
- Easy Configuration: Map sounds to materials directly in the inspector
- Fallback System: Default sounds when no material match is found
- Efficient: Very performant
-
Download the addon from the Godot Asset Library or clone this repository
git clone https://github.com/COOKIE-POLICE/godot-material-footsteps.git
-
Copy the
addons/godot_material_footstepsfolder into your project'saddonsdirectory -
Enable the plugin in Project Settings:
- Go to Project → Project Settings → Plugins
- Find "Godot Material Footsteps" and check the Enable box
In your player scene, add a MaterialFootstepPlayer3D node as a child of your character node.
CharacterBody3D (Your Player)
└── MaterialFootstepPlayer3D
In the Inspector for the MaterialFootstepPlayer3D, you'll see three main properties to configure:
Set the target_character property to your player node (usually the parent node).
Inspector → MaterialFootstepPlayer3D
├── target_character: CharacterBody3D
This is where you define which sounds play on which surfaces.
Inspector → MaterialFootstepPlayer3D
└── material_footstep_sound_map: Array[MaterialFootstep]
├── [0] MaterialFootstep
│ ├── material_name: "wood"
│ └── sounds: Array[AudioStreamPlaylist]
│ ├── wood_step_01.wav
│ ├── wood_step_02.wav
│ └── wood_step_03.wav
├── [1] MaterialFootstep
│ ├── material_name: "stone"
│ └── sounds: Array[AudioStreamRandomizer]
│ ├── stone_step_01.wav
│ └── stone_step_02.wav
└── [2] MaterialFootstep
├── material_name: "grass"
└── sounds: Array[AudioStream]
└── grass_step_01.wav
Configure default_material_footstep_sound as a fallback.
Inspector → MaterialFootstepPlayer3D
└── default_material_footstep_sound: MaterialFootstep
├── material_name: "default"
└── sounds: Array[AudioStream]
└── generic_step.wav
Now that the player is configured, you need to tell surfaces what material they are. Choose the method that matches your level design:
Best for: StaticBody3D meshes
The option to add metadata is at the very bottom of the in-editor inspector.
Example Scene Structure:
Level
├── WoodenFloor (StaticBody3D)
│ ├── CollisionShape3D
│ └── MeshInstance3D
│ └── Metadata:
│ surface_type: "wood"
├── StoneWall (StaticBody3D)
│ ├── CollisionShape3D
│ └── MeshInstance3D
│ └── Metadata:
│ surface_type: "stone"
└── GrassField (StaticBody3D)
├── CollisionShape3D
└── MeshInstance3D
└── Metadata:
surface_type: "grass"
Best for: Tile-based levels, dungeon crawlers, grid-based games
For GridMap-based levels, the tile's name in the MeshLibrary is automatically detected.
MeshLibrary
├── Item 0: "stone" ← Matches "stone" in sound map
├── Item 1: "wood" ← Matches "wood" in sound map
├── Item 2: "grass" ← Matches "grass" in sound map
Best for: HTerrain-based levels
Example Configuration:
material_footstep_sound_map:
├── [0] MaterialFootstep
│ ├── material_name: "0" ← HTerrain texture layer 0 (grass)
│ └── sounds: [grass_01.wav, grass_02.wav]
├── [1] MaterialFootstep
│ ├── material_name: "1" ← HTerrain texture layer 1 (dirt)
│ └── sounds: [dirt_01.wav, dirt_02.wav]
├── [2] MaterialFootstep
│ ├── material_name: "2" ← HTerrain texture layer 2 (rock)
│ └── sounds: [rock_01.wav, rock_02.wav]
└── [3] MaterialFootstep
├── material_name: "3" ← HTerrain texture layer 3 (sand)
└── sounds: [sand_01.wav, sand_02.wav]
Best for: If you want to detect based on actual material and surfaces.
The surface detector reads material names from the hit surface in this order:
resource_name- Material file name
Match these values with material_name entries in material_footstep_sound_map.
- Metadata-based surface detection
- GridMap support
- HTerrain Classic4 shader support
- Actual material surface-based detection
- Support for Terrain3D
- Automatic volume adjustment based on movement speed
- Full documentation website
See the open issues for a full list of proposed features and known issues.
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
- Fork the Project
- Create your Feature Branch (
git checkout -b feature/AmazingFeature) - Commit your Changes (
git commit -m 'Add some AmazingFeature') - Push to the Branch (
git push origin feature/AmazingFeature) - Open a Pull Request
Distributed under the MIT License. See LICENSE.txt for more information.