Skip to content

Instantly share code, notes, and snippets.

@KageDesu

KageDesu/ambient_sound_plugin_mz_guide.md

Created November 25, 2025 13:16
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save KageDesu/1e6b3ca9a17d80e2abe678e7d42906a3 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save KageDesu/1e6b3ca9a17d80e2abe678e7d42906a3 to your computer and use it in GitHub Desktop.
Download ZIP
Ambient Sound plugin guide
Raw
ambient_sound_plugin_mz_guide.md

PKD Ambient Sound Plugin Guide

Author: Pheonix KageDesu
Target: RPG Maker MZ / MV
Website: https://kdworkshop.net/ambient-sound

AmbientSound_new

Overview

The PKD Ambient Sound plugin allows you to create dynamic sound points on your maps that will be played at specified intervals and only when the player is within a certain distance. This creates immersive ambient soundscapes that respond to player position.

Key Features

  • Create sound points at specific map coordinates
  • Link sound points to events (sounds follow event position)
  • Two playback modes: Interval (random timing) and Loop (continuous)
  • Distance-based activation (sounds only play when player is nearby)
  • Volume control for individual sound points
  • Easy-to-use script calls for dynamic sound management
  • Create more natural ambient soundscapes with sound variations
  • Smooth scene transitions with fade effects
  • You can create dynamic day/night cycles using sound groups
  • Spatial audio with automatic panning
  • You can create complex audio scenarios with batch group operations

Plugin Parameters

Volume Multiplier

  • Type: Number
  • Default: 100
  • Range: 1+
  • Description: Global volume multiplier for all ambient sounds in percentage. 100 = 100% volume.

Auto Clear

  • Type: Boolean
  • Default: false
  • Options: Clear / Keep
  • Description: If enabled, all sound points will be automatically cleared when the player changes maps.

Script Calls

All script calls should be used in Script commands within events or through the console.

1. Create Interval Ambient Sound (Map Position)

setAmbientInterval(ID, FILE_NAME, X, Y, T1, T2, DISTANCE)

Creates a sound point that plays at random intervals within a specified time range.

Parameters:

  • ID - Unique identifier for this sound point (used for deletion)
  • FILE_NAME - Name of the SE sound file (without extension) OR array of file names for random selection
  • X - Map X coordinate
  • Y - Map Y coordinate
  • T1 - Minimum time in SECONDS before sound repeats
  • T2 - Maximum time in SECONDS before sound repeats
  • DISTANCE - Activation distance from player (in tiles)

Example:

setAmbientInterval(1, "Miss", 10, 20, 1, 3, 5);
// Plays "Miss" sound at position (10, 20)
// Random interval between 1-3 seconds
// Activates when player is within 5 tiles

// Using array for variety:
setAmbientInterval(2, ["Bird1", "Bird2", "Bird3"], 15, 25, 2, 5, 7);
// Randomly plays one of three bird sounds at position (15, 25)
// Each time a different bird sound may play
// Random interval between 2-5 seconds

2. Create Interval Ambient Sound (Event Position)

setAmbientIntervalEv(ID, FILE_NAME, EVENT_ID, T1, T2, DISTANCE)

Creates a sound point linked to an event. The sound moves with the event.

Parameters:

  • ID - Unique identifier for this sound point
  • FILE_NAME - Name of the SE sound file OR array of file names for random selection
  • EVENT_ID - ID of the event to link to
  • T1 - Minimum time in SECONDS before sound repeats
  • T2 - Maximum time in SECONDS before sound repeats
  • DISTANCE - Activation distance from player (in tiles)

Example:

setAmbientIntervalEv(2, "Equip1", 8, 1, 3, 3);
// Links sound to event #8
// Plays "Equip1" sound every 1-3 seconds
// Activates within 3 tiles

// Using array for footstep variety:
setAmbientIntervalEv(3, ["Step1", "Step2", "Step3"], 10, 0.3, 0.6, 2);
// Links to event #10 with varied footstep sounds
// Randomly picks one of three footstep sounds each time

3. Create Looped Ambient Sound (Map Position)

setAmbientLoop(ID, "FILE_NAME", X, Y, DISTANCE, LOOP_REPEAT_TIME)

Creates a continuously looping sound point at a fixed position.

Parameters:

  • ID - Unique identifier for this sound point
  • FILE_NAME - Name of the SE sound file
  • X - Map X coordinate
  • Y - Map Y coordinate
  • DISTANCE - Activation distance from player (in tiles)
  • LOOP_REPEAT_TIME - Time in MILLISECONDS before sound loops again

Example:

setAmbientLoop(3, "Waterfall", 10, 20, 5, 150);
// Creates looping waterfall sound at (10, 20)
// Loops every 150ms (0.15 seconds)
// Activates within 5 tiles

4. Create Looped Ambient Sound (Event Position)

setAmbientLoopEv(ID, "FILE_NAME", EVENT_ID, DISTANCE, LOOP_REPEAT_TIME)

Creates a continuously looping sound point linked to an event.

Parameters:

  • ID - Unique identifier for this sound point
  • FILE_NAME - Name of the SE sound file
  • EVENT_ID - ID of the event to link to
  • DISTANCE - Activation distance from player (in tiles)
  • LOOP_REPEAT_TIME - Time in MILLISECONDS before sound loops again

Example:

setAmbientLoopEv(4, "Fire", 12, 4, 200);
// Links looping fire sound to event #12
// Loops every 200ms
// Activates within 4 tiles

5. Adjust Sound Volume

setAmbientSoundVolumeMod(ID, VOLUME_MOD)

Modifies the volume of a specific sound point.

Parameters:

  • ID - ID of the sound point to modify
  • VOLUME_MOD - Volume modifier (1.0 = 100%, 0.5 = 50%, etc.)

Example:

setAmbientSoundVolumeMod(1, 0.5);
// Reduces volume of sound point #1 by half

setAmbientSoundVolumeMod(2, 1.5);
// Increases volume of sound point #2 by 50%

6. Clear Ambient Sound

clearAmbientSound(ID)

Removes a sound point from the map.

Parameters:

  • ID - ID of the sound point to remove

Example:

clearAmbientSound(1);
// Removes sound point with ID 1

7. Fade Ambient Sound

fadeAmbientSound(ID, TARGET_VOLUME, FADE_TIME)

Smoothly changes the volume of a sound point over time.

Parameters:

  • ID - ID of the sound point to fade
  • TARGET_VOLUME - Target volume modifier (1.0 = 100%, 0.5 = 50%, etc.)
  • FADE_TIME - Duration of fade in SECONDS

Example:

fadeAmbientSound(1, 0.0, 3);
// Fades sound #1 to silence over 3 seconds (fade out)

fadeAmbientSound(2, 1.0, 2);
// Fades sound #2 to full volume over 2 seconds (fade in)

8. Pause/Resume Ambient Sound

pauseAmbientSound(ID)
resumeAmbientSound(ID)

Pauses or resumes playback of a specific sound point.

Parameters:

  • ID - ID of the sound point to pause/resume

Example:

pauseAmbientSound(1);
// Pauses sound point #1

resumeAmbientSound(1);
// Resumes sound point #1

9. Set Ambient Sound Pitch

setAmbientSoundPitch(ID, PITCH_MOD)

Changes the pitch (playback speed) of a sound point.

Parameters:

  • ID - ID of the sound point to modify
  • PITCH_MOD - Pitch modifier (1.0 = normal, 0.5 = lower/slower, 1.5 = higher/faster)

Example:

setAmbientSoundPitch(1, 0.8);
// Makes sound #1 play 20% lower/slower

setAmbientSoundPitch(2, 1.2);
// Makes sound #2 play 20% higher/faster

10. Set Ambient Sound Pan (Stereo)

setAmbientSoundPan(ID, PAN_VALUE)

Controls stereo panning for a sound point.

Parameters:

  • ID - ID of the sound point to modify
  • PAN_VALUE - Pan value OR auto-pan setting
    • Number: -100 (full left) to 100 (full right), 0 = center
    • Boolean (true): Enable automatic panning based on sound position
    • Boolean (false): Disable automatic panning

Example:

setAmbientSoundPan(1, -50);
// Pan sound #1 to the left channel

setAmbientSoundPan(2, true);
// Enable automatic panning for sound #2
// Sound will pan left/right based on its position relative to player

setAmbientSoundPan(3, false);
// Disable automatic panning for sound #3

11. Check Sound Status

isAmbientSoundActive(ID)
getAmbientSoundInfo(ID)

Check if a sound is active or get detailed information about it.

Parameters:

  • ID - ID of the sound point to check

Returns:

  • isAmbientSoundActive() - Returns true if sound is playing, false if paused or doesn't exist
  • getAmbientSoundInfo() - Returns object with sound details, or null if sound doesn't exist

Example:

if (isAmbientSoundActive(1)) {
    console.log("Sound 1 is playing");
}

const info = getAmbientSoundInfo(1);
if (info) {
    console.log("Volume:", info.volume);
    console.log("Pitch:", info.pitch);
    console.log("Is Active:", info.isActive);
}

Info Object Properties:

  • id - Sound point ID
  • fileName - Sound file name
  • isActive - Whether sound is currently playing
  • isInterval - Whether sound uses interval mode
  • volume - Current volume modifier
  • pitch - Current pitch modifier
  • pan - Current pan value
  • autoPan - Whether auto-pan is enabled
  • distance - Activation distance
  • position - Sound position (x, y coordinates or eventId)

Group Management

Managing multiple sound points together using groups.

12. Add Sound to Group

addAmbientSoundToGroup(ID, "GROUP_NAME")

Adds one or multiple sound points to a named group for easier management.

Parameters:

  • ID - Sound point ID or array of IDs to add to group
  • GROUP_NAME - Name of the group (string). Use empty string "" to remove from all groups

Example:

// Add single sound to group
addAmbientSoundToGroup(1, "forest");

// Add multiple sounds to group
addAmbientSoundToGroup([1, 2, 3, 4], "forest");

// Remove sound from all groups
addAmbientSoundToGroup(1, "");

13. Clear Group

clearAmbientSoundsInGroup("GROUP_NAME")

Removes all sound points in a group and clears the group itself.

Parameters:

  • GROUP_NAME - Name of the group to clear

Example:

clearAmbientSoundsInGroup("forest");
// Removes all sounds in "forest" group

14. Pause/Resume Group

pauseAmbientSoundsInGroup("GROUP_NAME")
resumeAmbientSoundsInGroup("GROUP_NAME")

Pauses or resumes all sound points in a group.

Parameters:

  • GROUP_NAME - Name of the group to pause/resume

Example:

pauseAmbientSoundsInGroup("forest");
// Pauses all forest sounds

resumeAmbientSoundsInGroup("forest");
// Resumes all forest sounds

15. Set Group Volume

setAmbientGroupVolumeMod("GROUP_NAME", VOLUME_MOD)

Sets the volume modifier for all sound points in a group.

Parameters:

  • GROUP_NAME - Name of the group
  • VOLUME_MOD - Volume modifier (1.0 = 100%, 0.5 = 50%, etc.)

Example:

setAmbientGroupVolumeMod("forest", 0.5);
// Sets all forest sounds to 50% volume

Usage Examples

Example 1: Forest Ambience

Create bird chirping sounds at random intervals with variety:

// Using single sound file
setAmbientInterval(101, "Crow", 15, 8, 3, 8, 7);

// Using multiple sound files for more variety
setAmbientInterval(102, ["Bird1", "Bird2", "Bird3"], 25, 12, 4, 9, 7);
setAmbientInterval(103, ["Crow", "Raven"], 18, 20, 5, 10, 7);

Example 2: Waterfall Scene

Create a continuous waterfall sound:

setAmbientLoop(201, "Waterfall", 30, 15, 10, 100);

Example 3: Moving NPC with Footsteps

Link varied footstep sounds to a walking NPC:

// Using single footstep sound
setAmbientIntervalEv(301, "Step", 5, 0.5, 0.8, 2);

// Using multiple footstep sounds for realistic variety
setAmbientIntervalEv(302, ["Step1", "Step2", "Step3", "Step4"], 6, 0.4, 0.7, 2);
// Event #6 plays random footstep every 0.4-0.7 seconds

Example 4: Torch Fire Effect

Create fire sound that follows a torch event:

setAmbientLoopEv(401, "Fire1", 10, 3, 250);
setAmbientSoundVolumeMod(401, 0.6);
// Quieter fire sound on event #10

Example 5: Managing Sound Groups

Group sounds together for easier control:

// Create forest ambience
setAmbientInterval(101, ["Bird1", "Bird2", "Bird3"], 15, 8, 3, 8, 7);
setAmbientInterval(102, ["Crow", "Raven"], 25, 12, 4, 9, 7);
setAmbientLoop(103, "Wind", 20, 15, 10, 200);

// Add all to "forest" group
addAmbientSoundToGroup([101, 102, 103], "forest");

// Later: fade out all forest sounds
setAmbientGroupVolumeMod("forest", 0.3);

// Or pause all forest sounds during dialogue
pauseAmbientSoundsInGroup("forest");

// Resume after dialogue
resumeAmbientSoundsInGroup("forest");

// Clear all when leaving the forest
clearAmbientSoundsInGroup("forest");

Example 6: Day/Night Cycle

Switch between day and night ambience:

// Day sounds
setAmbientInterval(201, ["Bird1", "Bird2"], 10, 10, 2, 5, 10);
setAmbientInterval(202, "Crow", 20, 20, 5, 10, 10);
addAmbientSoundToGroup([201, 202], "day");

// Night sounds
setAmbientInterval(301, ["Cricket1", "Cricket2"], 15, 15, 1, 3, 10);
setAmbientInterval(302, "Owl", 25, 25, 8, 15, 10);
addAmbientSoundToGroup([301, 302], "night");

// When night comes
pauseAmbientSoundsInGroup("day");
resumeAmbientSoundsInGroup("night");

// When day comes
pauseAmbientSoundsInGroup("night");
resumeAmbientSoundsInGroup("day");

Best Practices

1. Use Unique IDs

Always use unique IDs for each sound point to avoid conflicts. Consider using ranges:

  • 1-99: Static map sounds
  • 100-199: Event-based sounds
  • 200+: Temporary sounds

2. Choose Appropriate Distances

  • Close sounds (2-3 tiles): Torches, small objects
  • Medium sounds (5-7 tiles): Animals, water features
  • Far sounds (10+ tiles): Waterfalls, large ambient effects

3. Interval vs Loop

  • Interval: Random natural sounds (birds, wind, drips)
  • Loop: Continuous sounds (waterfalls, fires, machinery)

4. Sound Variety with Arrays

For interval sounds, use arrays of similar sound files to add natural variety:

// Good: Natural variety in footsteps
setAmbientIntervalEv(1, ["Step1", "Step2", "Step3"], 5, 0.5, 0.7, 2);

// Good: Different bird calls
setAmbientInterval(2, ["Bird1", "Bird2", "Bird3", "Bird4"], 20, 15, 3, 8, 10);

// Tip: Use 3-5 variations for best results

5. Loop Timing

For loop sounds, shorter intervals (100-300ms) create smoother continuous effects.

6. Volume Management

Use volume modifiers to create depth:

  • Background sounds: 0.3-0.5
  • Mid-ground sounds: 0.6-0.8
  • Foreground sounds: 0.9-1.2

7. Auto Clear Setting

  • Keep (false): For sounds that should persist across map transitions
  • Clear (true): For map-specific ambience that shouldn't carry over

8. Group Management Best Practices

Organize sounds into logical groups for easier management:

// Good: Organized by theme
addAmbientSoundToGroup([1, 2, 3], "forest_birds");
addAmbientSoundToGroup([10, 11], "forest_wind");
addAmbientSoundToGroup([20, 21, 22], "town_crowd");

// Useful for: scenes, time of day, weather conditions

Benefits of using groups:

  • Batch operations: Control multiple sounds at once
  • Scene management: Easy fade in/out for cutscenes
  • Dynamic environment: Quick switches between states (day/night, calm/storm)
  • Memory efficiency: Clear entire groups when not needed

Troubleshooting

Sound Not Playing

  • Verify the sound file exists in audio/se/ folder
  • Check that the player is within the specified distance
  • Ensure the ID is unique and not conflicting

Sound Playing Everywhere

  • The DISTANCE parameter may be too large
  • Verify X, Y coordinates are correct

Sound Too Loud/Quiet

  • Adjust the global Volume Multiplier in plugin parameters
  • Use setAmbientSoundVolumeMod() for individual sound adjustments

Sounds Not Clearing

  • Enable "Auto Clear" in plugin parameters if you want automatic cleanup
  • Manually clear sounds with clearAmbientSound(ID) when needed

Support & Links

If you like this plugin and want more updates, please support the developer:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment