You can find everything related to the engine here.

Basics

Multiple engines can be defined. Using the command /cmdclientconfig the user can switch between the available engines, by default there is only one called basic.

Debug

You can use the command /ambient-debug to see what AmbientSounds has scanned. If you adjust the engine in anyway this is useful to see if the change has the expected result.

config.json

This file is located in assets/ambientsounds/ and stores some basic information. The default engine and all available engines.

{
    "default-engine": "basic",
    "engines": [
        "basic"
    ]
}

Definition

The engine itself is located in a subfolder. In the case of basic that is assets/ambientsounds/basic/. It is good practice to look at the basic engine to get an idea of how things work (source).

Every engine folder must contain the file engine.json, which must include the name and version at least:

{
    "name": "basic",
    "version": "2.1.1",

The engine file can used to configuration how AmbientSounds scans the environment, provide default sound properties and much more.

Ticker

There are two types of processors (tickers).

1. The environment-tick kicks off some scans of the environment. By default this is done every 40 ticks, which is exactly every 2 seconds. This processor does need quite some performance, decreasing the tick delay will result in noticeable performance drops. It does include the air-pocket and biome-type scan.
2. The sound-tick does some less intense updates. For example check if the player is underwater and how deep, if it is raining or storming, scans the average height, ...

    "environment-tick-time": 40,
    "sound-tick-time": 4,

To make it clear, if you do not know what you are doing, leave these two values as they are. Only in custom scenarios the might need some adjustments.

Average height scan

Scans the height of the area around the player and calculates and average height. This is used to determine whether the player is underground, walking at the surface or high up in the air.

    "average-height-scan-distance": 2,
    "average-height-scan-count": 5,

These two variables determine the distance between each scan point and how many points there are in one direction. Here is an example (note that the variables are not as the default ones to make it easier to understand):

Biome scan

The biome scan works in the exact same way as the average height scan, but instead of checking the height it will search for the biome at the given position. The further outside a biome is detected the lower the volume will be. The volume will be determined by the closest distance of the biome.

    "biome-scan-distance": 5,
    "biome-scan-count": 3,

Air pocket scan

This scan is used to detect if the player is in a small room, large hall or outside. Furthermore, it detects the blocks in the surrounding. Here is an example of how it looks like. Notice the tree even though it is close enough is never detected because there is no air connection to the player.

The scan is handled off thread and there are several parameters to adjust it as you please.

The air-pocket-count (default is 50000) limits how many blocks will be scanned at maximum. The higher the number the longer the longer the scan will take.

air-pocket-distance (default is 13) is used to determine whether the playing is standing in an open or closed area. Only blocks lower or equal the distance of 13 will be considered as air around the player. Once the scan is complete the counted air will be divided by the highest possible air count based on the given distance.

If we refer back to the image above, there are 55 blocks to be considered air (only air with a distance of 13 or lower). A air-pocket-distance of 13 can have 3003 blocks of air at maximum. If we divide these two values, we get the percentage of air around the player, which is: found / possible = 55 / 3003 = 0.0183 = 1.83 %. This will be considered a closed area in the default engine.

Air pocket scan is also used to scan the blocks around the player. Therefore, every adjacent block is considered:

If we count the scanned blocks it would look like this.

Material	Count
stone	32
diorite	5
water	2

But there is a problem. If you want to implement a water sound for example, which is supposed to play if water is around. A block of water 100 meters away would have the same impact as a water block next to the player. As you can imagine this is not a good way to tell water is around or not. To get around this issue there are so called air-pocket-groups. Basically, it is a priority system. Blocks nearby should be more important than blocks far away.

You can define these groups like so:

    "air-pocket-groups": [
        {
            "distance": 5,
            "weight": 10
        },
        {
            "distance": 5,
            "weight": 5
        },
        {
            "distance": 5,
            "weight": 2
        },
        {
            "distance": 10,
            "weight": 1
        }
    ],

The result will look like this. In the header is the distance and below the weight.

A stone at a distance of 1-5 will be considered as 10x stone blocks and a stone block 15 meters away as 2x stone blocks.

With these new rules applied the result looks like this.

Material	Count
stone	242
diorite	30
water	10

Solids

Some blocks are not considered to be solid, but can block sound nonetheless. This list is used to define blocks that should be considered being solid even though they are not. Each entry is written in the block format.

    "solids": [
        "t->doors",
        "t->impermeable",
        "t->stairs"
    ],

Biome-types

Biome types are used to define special rules in a dimension for all regions that use one of these types.

    "biome-types": [
        "surface",
        "underground"
    ],
    "default-biome-type": "surface"

The default-biome-type is used when no biome type in defined. For example, the surface biome type is used to make sure it can only play when the player is at the surface. While underground biomes can play everywhere as long the biome is close.

Fade settings

Determines how fast a sound can fade in and out. The lower the value the longer it will take. This can be done for the volume and pitch. These settings can also be changed by the user using the command /cmdclientconfig.

    "fade-volume": "0.005",
    "fade-pitch": "0.005",