Setting up your own engine

AmbientSounds 3 offers you to create your own configuration. From small changes to complete different scenarios, everything is possible. The library might be expanded even further if people request so.

This tutorial should introduce you into the system. The original engine can be found here. You can replace it by using a resourcepack which includes a assets/ambientsounds/engine.json file and share it with your friends (or include it in your modpack).

Feel free to send your engine to me, so I can add it to the curseforge page. Anyway let's get started.

Types

If you are not known to the basics of programming or have never worked with json this might be interesting for you:

• Integer
  • A "whole" number. Examples: ..,-3,-2,-1,0,1,2,3,...
• Boolean
  • true or false
• Decimal
  • a decimal number, split with a dot: 0.1
• String
  • text in quotes. Example: "A random text"
• Array
  • basically multiple things within brackets separated by a comma. Example: [ "first random text", "second", "something else" ]

Dimensions

This is the first layer of the engine. It determines the general environment settings. Vanilla minecraft has 3 dimensions (the end, hell (Nether) and overworld), but it also possible to support mod added ones.

Selectors

Only one dimension can be active at the same time. AmbientSounds will go through each of your specified dimensions (in the same order as you wrote them) and check if they are selected or not.

• id (integer): Checks for dimension id. Hell: -1, Overworld: 0, The End: 1
• dimension-ids (integer array): Works in the same way as id, but you can specify multiple ids "id": [ 0, 1, 3 ],).
• bad-dimension-ids (integer array): Dimension will be skipped if one of the specified ids is the current one.
• dimension-names (string array): Checks for dimension name (current one can be seen if /ambient-debug command is used).
• bad-dimension-names (string array): Dimension will be skipped if one of the specified names matches the current one.

If you have not specified any selector, the dimension will always be active if all before are inactive. By default the overworld dimension jumps in every time no special dimension could be found.

Properties

• name (string): A unique identifier for the dimension, useful to keep everything organized.
• disableAll (boolean): If true the engine will not play any sounds in this dimension.
• rain (boolean): Forces the engine to think it's either always raining (true) or never (false).
• storm (boolean): Forces the engine to think it's either always storming (true) or never (false).
• average-height (float): Will set the average-height to a constant number. Normally the average-height is the distance between the player and the near surface.
• biome-selector (condition): The selector will determine if biomes are active and what volume multiplicator they have. Normally you want it to be the region surface.
• regions (region): Regions only active in this dimension.

Regions (ambient condition)

Regions are the second layer and should help you to group areas of the game. Every region requires a unique name.

Selectors

• regions (string array): List of regions it depends on. At least one needs to be active.
• bad-regions (string array): Backlist of regions, if one is active this region will not be active.
• biomes (string array): List of biomes. At least one of them needs to be nearby. It will also effect the volume.
• bad-biomes (string array): Blacklist of biomes. if one is nearby this region will not be active.
• specialBiome (biome condition): Select biomes by certain attributes. All of specified attributes have to be met.
  • top-block (string array): List of top blocks. Examples: plains, forest, savanna have minecraft:grass, while desert has minecraft:sand as a top block.
  • temperature (min-max): Might be useful to take a look at Minecraft Wiki to find out the temperature of a specific biome.
  • trees-per-chunk (min-max) only available in 1.15: How many trees a biome will generate per chunk. Useful to separate a forest from other biomes.
  • waterlily-per-chunk (min-max): How many waterlilies a biome will generate per chunk.
  • flowers-per-chunk (min-max): How many flowers a biome will generate per chunk.
  • grass-per-chunk(min-max): How much grass a biome will generate per chunk.
  • deadbush-per-chunk(min-max): How many deadbushes a biome will generate per chunk.
  • mushrooms-per-chunk(min-max): How many mushrooms a biome will generate per chunk.
  • reeds-per-chunk(min-max): How many reeds a biome will generate per chunk.
  • cacti-per-chunk(min-max): How many cacti a biome will generate per chunk.
• storming (boolean): If true it will be active if it is storming and inactive if it is not storming, if false it will be the other way around.
• raining (boolean): If true it will be active if it is raining and inactive if it is not raining, if false it will be the other way around.
• underwater (min-max-fade): Specifies minimum/ maximum underwater level. Including a fade value (which affects volume).
• light (min-max-fade): Specifies minimum/ maximum light level. Including a fade value (which affects volume).
• outside (boolean): Whether the player has to be outside (in an open area). Will affect volume.
• relative-height (min-max-fade): Minimum and maximum relative height (relative height is the distance between the nearby surface and the player).
• absolute-height (min-max-fade): Minimum and maximum absolute height (absolute height is the y value of the player).
• min-height-relative (min-max-fade): Minimum and maximum of the lowest surface block nearby.
• max-height-relative (min-max-fade): Minimum and maximum of the highest surface block nearby.
• sound (sound array): List of possible sounds to be played.
• variants (ambient condition): An array of more selectors. At least one needs to be active. a { variants: [ b {}, c {} } means either a and b or a and c.

Properties

• volume (decimal): Volume multiplier.
• night (decimal): Volume multiplier if it's night time.
• day (decimal): Volume multiplier if it's day time.
• fade-volume (decimal): Constant fade in volume. Will affect fade in and fade out transition. Used if in/out values are not specified. Default is 0.005.
• fade-in-volume (decimal): Specifies fade in speed. Default is 0.005.
• fade-out-volume (decimal): Specifies fade out speed. Default is 0.005.
• pitch (decimal): Pitch multiplier.
• fade-pitch (decimal): Constant fade in pitch. Will affect fade in and fade out transition. Used if in/out values are not specified. Default is 0.005.
• fade-in-pitch (decimal): Specifies fade in speed. Default is 0.005.
• fade-out-pitch (decimal): Specifies fade out speed. Default is 0.005.
• underwater-pitch (climbing property): Pitch multiplier depending on how deep underwater the player is.
  • min (decimal): Minimum value for property to be active.
  • max (decimal): Maximum value for property to be active.
  • distance-factor (decimal): How much the pitch will change depending on the distance (per block)
• transition (integer): Time of transition between two sound files.
• mute (decimal): Needs to be a value between 0 (no affect) and 1 (all other sounds are completely muted).
• pause (min-max): The pause between playing the sounds.
• length (min-max): The length of a sound.

Sound

Sounds can have the same properties as regions, but they also come with some unique requirements:

• files (string array): All sounds files. If there are multiple sounds will not be looped but played after each other, unless a length is defined.
• chances (decimal array): Chances of each sound file to be played.

Special Conditions

Min-Max

• min (decimal): Minimum to be active.
• max (decimal): Maximum to be active.

Min-Max-Fade

• min (decimal): Minimum to be active.
• max (decimal): Maximum to be active.
• fade (decimal): Size of the fade at min and max.

Last words

If you want to create your own engine, I highly recommend to take the original engine and go from there. If you have more questions or suggestions feel free to ask contact us here on github or on discord.