.esfx files

The esfx (Easel sound effects) file format is a simple way to create sound effects for your game. It is a text-based format that allows you to define a sound effect by chaining together sound processing functions. You may choose from a range of built-in oscillators, noise generators, and filters.

The .esfx Reference lists all the functions you can use in an .esfx file.

Play blocks

An esfx file constists of one or more Play blocks. Each Play block defines a single sound effect and how long to play it for.

Play(duration=1.5s, delay=0.5s, cutoff=0.5s) {
    BrownNoise
    BandPass(freq=[220,330], q=[1,5])
    Envelope(attack=0.25s, release=0.5s)
}

Parameters:

• duration: Required. The duration of the sound effect.
• delay: Optional. The time to wait before playing the sound effect. Normally you would only use this if you have multiple Play blocks in the same file and would like to offset some of them.
• cutoff: Optional. The time to fade out the sound effect if it is cut short. This could happen if using the Sing function to play the sound effect and the entity generating the sound is despawned.

The body of the Play block is a stack of sound processing functions that are chained from top to bottom. Each function takes the output of the function above it and processes it in some way. The final output is the sound effect that is played.

Parameters

Ramp parameters

A ramp parameter is a parameter that can change over the duration of the sound effect.

For example, this is an Oscillator which generates a sound at a fixed frequency of 300 Hz:

Oscillator(freq=300)

We can make the frequency change over time by passing an array of values to the freq parameter instead:

Oscillator(freq=[300,500])

This means that the frequency will start at 300 Hz and end at 500 Hz over the duration of the sound effect. The frequency will increase linearly over time.

Q factors

The q parameter is a quality factor that determines how sharp the filter is. A higher q value will make the filter more aggressive, while a lower q value will make the filter more gentle.

Wikipedia has a good article on Q factors.

dB values

Some functions take parameters that are in decibels (dB). These are used to specify volume or a change in volume of the sound effect.

Wikipedia has a good article on decibels.

Routing

Normally, the output of a function is passed to the next function in the list that takes input.

If multiple sound-generating functions appear in a sequence, their outputs will be added together.

Play {
    Oscillator(freq=500)
    Oscillator(freq=750)
    LowPass(freq=1000) // receives the sum of the two oscillators above
}

More complex chains of functions can be created by using the Input and Output functions.

Play {
    Oscillator(freq=500)
    Envelope(attack=0.01s)
    Output(into=$abc)
    
    Oscillator(freq=750)
    Envelope(attack=0.5s)
    Output(into=$abc)
    
    Input(key=$abc)
    LowPass(freq=1000) // receives from the two Outputs above
}