Engine

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 scans the surrounding area of the player to consider whether the player is standing inside a small room or is outside. Furthermore it is used to detect nearby blocks. 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.

The scan starts at the players location and scan through air until a block is found. Notice the tree even though it is close enough is never detected because there is no air connection to the player.

Note: This values should be tweaked carefully. It is important that you understand what they do if you change them, otherwise the system might not properly anymore.

Blocks

Blocks connected to your "air pocket" are 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

Air

The air pocket scan is also used for the air condition. It basically defines how much space there is around the player and is used for example in caves to play different sounds when being in a large room. The value is between 0 (when the player is standing in a small tunnel) and 1 (when being outside or inside a large room). You can also use the debug screen to see the current air value.

The air value is calculated by dividing the scanned air blocks within the air-distance (default 60) with the maximum amount of possible air blocks inside this given distance. Meaning on a flat world this value 0.5, because only about half of the air pocket is actually filled with air.

But there is more to it. If the player is standing outside and can see the sky the air value will also be increased. This is done by checking if a given position can see the sky or not. All blocks within the air-sky-distance (default 13) are considered. If sky is detected more air blocks will be added to the air block counter (which will result in a higher air value). How many air blocks are added when there is sky is defined by the air-sky-distance and air-sky-weight.

Calculation is: (1 - (posDistance - air-sky-distance)) * air-sky-weight.

posDistance is the distance of the detected block that can see the sky. Seems complicated but is quite simple. Blocks closer to the player will be more weighted than blocks further away.

At last this air value will be interpreted by the engine. All values below air-min will be considered to be 0, all values above air-max will be considered 1 and all positions in between will be interpolated linear.

Sky

A value that defines how close the sky is. It is 1 if the player is standing outside and 0 in a cave. sky-distance defines the distance at which blocks are considered. When sky is detected it is added to a counter depending on the distance: counter += posDistance - sky-distance.

The engine then interprets this value with sky-min-count (below this value sky is 0) and sky-max-count (above this value sky is 1). All values in between will be interpolated linear.

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": [
        "#minecraft:doors",
        "#minecraft:impermeable",
        "#minecraft: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",