Godot Material Footsteps

Automatically play footstep sounds based on surface materials in Godot 4
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
   • Features
2. Getting Started
   • Installation
3. Usage
   • Step 1: Add the Footstep Player
   • Step 2: Configure the Footstep Player
   • Step 3: Set Up Your Surfaces
4. Roadmap
5. Contributing
6. License
7. Acknowledgments

About The Project

Godot Material Footsteps is an addon for Godot 4 that plays footstep sounds based on the surface your character is walking on. Instead of manually scripting sounds for each type of surface, you can directly configure the surfaces in the editor inspector. It works with different setups, including metadata on meshes, GridMap tiles, and HTerrain Classic4 shaders.

This addon is available on the Godot Asset Library.

(back to top)

Built With

• 
• 

(back to top)

Features

• Multiple Detection Methods: Metadata, GridMap tiles, and HTerrain shader support
• Easy Configuration: Map sounds to materials directly in the inspector
• Fallback System: Default sounds when no material match is found
• Efficient: Very performant

(back to top)

Getting Started

Installation

1. Download the addon from the Godot Asset Library or clone this repository

   git clone https://github.com/COOKIE-POLICE/godot-material-footsteps.git

2. Copy the addons/godot_material_footsteps folder into your project's addons directory

3. Enable the plugin in Project Settings:

   • Go to Project → Project Settings → Plugins
   • Find "Godot Material Footsteps" and check the Enable box

(back to top)

Usage

Step 1: Add the Footstep Player

In your player scene, add a MaterialFootstepPlayer3D node as a child of your character node.

CharacterBody3D (Your Player)
└── MaterialFootstepPlayer3D

(back to top)

Step 2: Configure the MaterialFootstepPlayer3D

In the Inspector for the MaterialFootstepPlayer3D, you'll see three main properties to configure:

2.1 Set Target Character

Set the target_character property to your player node (usually the parent node).

Inspector → MaterialFootstepPlayer3D
├── target_character: CharacterBody3D

2.2 Create Material Sound Map

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

2.3 Set Default Sound

Configure default_material_footstep_sound as a fallback.

Inspector → MaterialFootstepPlayer3D
└── default_material_footstep_sound: MaterialFootstep
	├── material_name: "default"
	└── sounds: Array[AudioStream]
		└── generic_step.wav

(back to top)

Step 3: Set Up Your Surfaces

Now that the player is configured, you need to tell surfaces what material they are. Choose the method that matches your level design:

Method A: Using Metadata (Recommended)

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"

Method B: Using GridMap

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

Method C: Using HTerrain Classic4 Shader

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]

(back to top)

Roadmap

• Metadata-based surface detection
• GridMap support
• HTerrain Classic4 shader support
• Support for Terrain3D
• Automatic volume adjustment based on movement speed

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

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!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Top contributors:

(back to top)

License

Distributed under the MIT License. See LICENSE.txt for more information.

(back to top)

Acknowledgments

• Choose an Open Source License
• Godot Engine
• HTerrain Plugin
• Best README Template
• Img Shields
• GitHub Pages

(back to top)