Tutorial: Biome Configuration

Internally Dynamic Surroundings has a Biome Registry where it finds information related to background fog and density, fog color, whether the biome can spawn auroras, etc. A modpack author can override what Dynamic Surroundings uses in order to provide specific biome effects.

NOTE: The /ds command has an option reload. This allows you to reload biome config files without having to exit Minecraft. However, if you create a new one and add it to the dsurround.cfg file you will still need to restart Minecraft.

The table below describes the various parameters that can be defined:

Parameter	Value Type	Comment
biomeName	String	The biome for which these options apply. Can be a Java regex expression.
precipitation	boolean	Supports rain/snow
dust	boolean	Has dust particles when raining (deserts)
dustColor	String	RGB triple that describes dust fog color
aurora	boolean	Can spawn auroras
fog	boolean	Has background fog effect
fogColor	String	RGB triple that describes background fog color
fogDensity	Float	Number indicating fog density
sounds	List	List of sounds configured for the biome. See below.
soundReset	Boolean	Tells Dynamic Surroundings to reset any existing sound list for the biome.
spotSoundChance	Integer	1-in-N chance per tick of triggering spot sound.

In order to define biome options the first thing that needs to be done is to create a Json file in the ./minecraft/config/dsurround/ configuration directory. It is a normal text file but has a specific Json syntax that must be followed. Here is an example of such a file:

{
    "biomes":[
        {
            "biomeName":".*",
	    "dust":true,
	    "dustColor":"204,185,102",
	    "fog":true,
	    "fogDensity":0.04,
	    "fogColor":"64,128,64"
	}
		
    ]
}

In the example above the biomeName is “.*”. This is a Java regex expression that essentially matches any biome name. The result of this configuration is that every biome registered with Minecraft will have a dust effect when it is raining, and will have a background fog that is tinted a greenish color. If you are not familiar with regex the biomeName could have been explicit, such as “Swampland”. In this case it would only match a biome that has the exact name of “Swampland”. Internally Dynamic Surroundings uses a Json config to set the initial state of the biomes in the Biome Registry. The file can be found here if you are interested.

Not all parameter values have to be specified. If they are not present in a config entry Dynamic Surroundings will continue to use the existing setting. Do note, though, the higher level entries parameter. This must be present for Dynamic Surroundings to process the file. As an example this is the minimal do-nothing configuration Json configuration:

{
    "entries":[
		
    ]
}

The color values are RGB triples. A good reference chart can be found here to help you decide on colors.

The selection of a fog density can be a bit tricky. There is no hard fast calculation that can be performed to determine the best value to use in a given situation. Selection of the value is trial and error. By default Dynamic Surroundings uses a fog density of 0.04. Raising this value increases density, were as reducing the value reduces density. I suggest moving the density by small amounts, like +/- 0.005 until you get the desired effect.

It is possible to have multiple entries in the config file that match the same biome. The entries in the file are processed in order, so entries further down in the list can override the effects of entries higher in the list. This makes it possible to do things like “All biomes that look like this have these parameters, except for this one because it is special”. It is possible to accomplish the same effect with regex, but sometimes it is easier to spell it out.

Once the configuration file is created Dynamic Surroundings needs to be told to process the file during it’s initialization. To do that edit the dsurround.cfg file and set the Config Files parameter:

biomes {
    # Configuration files for configuring Biome Registry [default: ]
    S:"Config Files" <
        BoP.json
        apocalypse.json
     >
}

In this example there are two external configuration files BoP.json and apocalypse.json. BetterRain will load and process each of these config files, in order. This means that it would be possible for apocalypse.json to override what BoP.json has configured. This is useful for when someone comes up with general settings in support of a mod (such as Biomes O’Plenty), but wants to make some tweaks to give it an “end of the world” or apocalyptic feel.

More Examples

Set a general background haze for all biomes. Good for the wasteland type feel.

{
    "entries":[
        {
            "biomeName":".*",
	    "fog":true,
	    "fogDensity":0.04,
	    "fogColor":"64,64,64"
	}
}

Set a biome fog for magical biomes that is blue in color but less dense than swamps:

{
    "entries":[
        {
            "biomeName":"(?i).*magic.*",
	    "fog":true,
	    "fogDensity":0.02,
	    "fogColor":"0,191,255"
	}
}

Make it so auroras can trigger when a player is standing in a Plains biome:

{
    "entries":[
        {
            "biomeName":"Plains",
	    "aurora":true
	}
}

Precipitation sucks. Turn off rain/snow textures and water splashes. Good for wasteland maps. This does not turn off the rain function in Minecraft - just the client side rendering of such effects.

{
    "entries":[
        {
            "biomeName":".*",
	    "precipitation":false
	}
}

Biome Sounds

A background sound can be played while a player is standing in a biome that is configured for sound. A biome can be configured with several sound entries. Dynamic Surroundings will make a sound selection for a given biome based on current environmental conditions. A sound will continue to play until the player changes biomes or the conditions for the sound no longer apply.

Parameter	Value Type	Comment
sound	String	The name of the sound resource to play.
conditions	String	A Java regex expression that match the condition for playing.
volume	float	The volume level at which to play the sound.
pitch	float	The pitch to use when playing the sound.
spot	Boolean	Indicates the sound is a spot sound. *.0.5.4BETA+ DEPRECATED: Replace with “soundType”:”spot”
soundType	String	*.0.5.4BETA+ Indicates the type of sound. Possible values are “background”, “spot”, and “periodic”. Defaults to “background” if not specified.
repeatDelay	Integer	Number of ticks to delay when submitting sound when looping.
repeatDelayRandom	Integer	*.0.5.4BETA+ Optional number of ticks to randomly delay; added to repeatDelay to get an effective delay amount.
weight	Integer	Selection weight of the spot sound if more than one can be selected.

Before we get into the nitty gritty details here are some examples from the internal Dynamic Surroundings configuration Json:

	{
		"biomeName":"(?i)(.*swamp.*)",
		"fog":true,
		"fogColor":"64,128,64",
		"fogDensity":0.04
	},
	{
		"biomeName":"(?i)(?!.*dead.*)(.*swamp.*)",
		"sounds":[
			{
				"sound":"dsurround:crickets",
				"volume":0.1
			}
			
		]
		
	},

These two entries configure biomes that contain the character sequence swamp. The first entry configures all biomes that contain the sequence swamp to have fog of a greenish tint and density of 0.04. The second entry defines a single sound that is to be played in all swamp biomes that do not have the character sequence of dead in the name (i.e. doesn’t apply to a Dead Swamp).

Here is another example for forest like biomes:

	{
		"biomeName":"(?i)(?!.*dead.*|.*flower.*|.*fungi.*|.*frost.*)(.*forest.*|.*cherry.*|.*orchard.*)",
		"sounds":[
			{
				"sound":"dsurround:forest",
				"conditions":"(?i)(?!.*raining.*).*day.*"
			},
			{
				"sound":"dsurround:crickets",
				"conditions":"(?i)(?!.*raining.*).*night.*",
				"volume":0.1
			}
			
		]
		
	},

This rule matches all biomes that have forest, cherry, and orchard in their name excepting those that have dead, flower, fungi, or frost. Two sounds are configured, one that plays dsurround:forest sound during the day if it is not raining, and the other is for dsurround:crickets if it is at night and not raining. The sound entries in this list are processed in order, so the first sound to match the specific conditions will be selected.

Sound

This value determines what sound to play. It is in a ResourceString format. As an example, “dsurround:crickets” tells Minecraft to play the sound “crickets” from the mod “dsurround”. This can be any valid sound reference, whether it is from Minecraft, Dynamic Surroundings, or another mod. For example, if you want to play the Minecart movement sound you could use “minecraft:minecart.base”, or want to use the Minecraft flame sound “minecraft:fire.fire”.

Conditions

Currently there are three conditions that could occur singly or in combination: “day”, “night”, and “raining”. The conditions regular expression operates on a string that is built with these tokens. For example, if it is daytime and is raining the condition string the regex will operate on is “day raining”. If the sound conditions regex matches the condition string the sound will be selected for play.

This tables describes the tokens that can be present in the condition string. These tokens are separated by the hash # character.

Token	Context	Comment
day	World	It is daytime. Exclusive of night.
night	World	It is nighttime. Exclusive of day.
raining	World	Currently raining.
<DIMENSION>	World	Name of the player dimension (i.e. Overworld)
<SEASON>	World	Current season (winter, spring, summer, fall) if CalendarAPI installed, otherwise “noseason”.
fog	World	Current fog level at the player location is >= 0.01
dry	World	Current player biome is dry (no rain).
humid	World	Current player biome is humid.
tcocean	World	Temp category of the player biome is ocean.
tccold	World	Temp category of the player biome is cold.
tcmedium	World	Temp category of the player biome is medium.
tcwarm	World	Temp category of the player biome is warm
hurt	Player	40% or less health remaining.
hungry	Player	40% or less food bar remaining.
burning	Player	On fire.
noair	Player	Suffocating (no air).
flying	Player	Is flying.
sprinting	Player	Is sprinting.
inlava	Player	Standing in lava.
inwater	Player	Standing in water.
invisible	Player	Is invisible.
blind	Player	Blindness potion effect active.
ridingminecart	Player	Riding a minecart.
ridinghorse	Player	Riding a horse.
ridingboat	Player	Riding a boat.
ridingpig	Player	Riding a pig.
riding	Player	Riding something that isn’t known.
freezing	Player	Temp at the player location is freezing.
inside	Player	The player appears to be inside a structure.

Volume

Normally a sound will be played at a volume of 1.0F as a default. Sometimes the supplied sound is too loud so specifying a lower volume would be appropriate. You will have to experiment to find the right value for the sound you are playing.

Pitch

Pitch will raise or lower the pitch of the sound. Typically lowering the pitch makes the sound “deeper”, and raising will make it more “shallow”. For example, Dynamic Surroundings uses the regular beach wave noise for Deep Ocean by lowering the pitch to make it deeper to match the deep water.

SoundReset

Sometimes a modpack author wants to reset the sound configuration for a biome before setting up new ones. To do this specified soundReset in the biome record before defining new sounds. For example:

{
    "entries":[
        {
            "biomeName":".*",
            "soundReset":true,
            "sounds":[
                {
                    "sound":"dsurround:wind",
                    "volume":0.3
                }
            ]
	}
    ]
}

This entry will cause currently configured sound information to be removed from all biomes. After that, a new sound will be defined for each, in this case a “dsurround:wind” sound that will play at a low volume regardless of the current conditions.

Spot (*.0.5.4BETA DEPRECATED; replace with “soundType”)

Indicates the sound is a spot sound. Spot sounds randomly occur when a player stands in the biome. The frequency of this occurrence is determined by the spotSoundChance setting for the biome. Like background biome sounds, multiple spot sounds can be configured along with conditions. If more than one spot sound is configured and eligible for play, Dynamic Surrounds will randomly select one for play.

SoundType (*.0.5.4BETA+)

Indicates the type of sound this entry represents. The following are the possible sound types:

SoundType	Comment
background	Sound will play in a continuous loop until conditions change.
periodic	Sound will queue based on the repeatDelay and repeatDelayRandom settings.
spot	Sound is a spot sound and will play based on appropriate conditions and randmoness.
step	Sound is a sound that can play while a player is walking on a block. Only applies to block sounds.

RepeatDelay

The number of ticks to delay between sound plays. Sometimes there needs to be spacing when playing a sound, such as the stomach rumble when a player is hungry.

RepeatDelayRandom (*.0.5.4BETA+)

An additional random number of ticks that will be added to repeatDelay when calculating the number of ticks to delay for the next play interval. For example, if repeatDelay is 300, and repeatDelayRandom is 1000, the effective delay amount will be 300-1299 ticks.

Weight

Specifies the relative weight of a particular sound when a random selection can be made. The higher the weight the higher the likelyhood of selection. Selection behavior of a sound is similar to the weighted selections from Minecraft’s chest content tables. If a weight is not specified a value of 10 is assumed.

Spot Sounds

A spot sound is a non-repeating sound that has a random chance of playing while a player is present in a biome. While a biome sound can be thought of as background audible ambiance/theme for a biome, a spot sound is more like punctuation. For example a Jungle could have a biome sound that gives the sense of leaves moving in the breeze and the scurrying/noise of small creatures within the leaf canopy. To accent this experience jaguar growls could be introduced as spot sound. The growl would randomly play while the player is present in a Jungle, but it is not part of the sound track. Another example is an owl hooting in a Forest at night while the crickets chirp.

Fake Biomes

A fake biome is similar to a fake player in that they really don’t exist, but serve as a proxy for getting things done. In the case of fake biomes Dynamic Surroundings will use them to better refine the players locale for the purposes of configuring environmental effects. Fake biomes do not show up in the regular Minecraft/Forge biome listings - they are strictly internal to Dynamic Surroundings.

Name	Comment
Underground	Biome for when a players Y value is several blocks below the defined sea level for the dimension.
UnderOCN	Underwater in an Ocean biome. (“(?i)(?!.*deep.*)(.*ocean.*|.*kelp.*|.*coral.*)”)
UnderDOCN	Underwater in a Deep Ocean biome. (“(?i).*deep.*ocean.*|.*abyss.*”)
UnderRVR	Underwater in a River biome. (“(?i).*river.*”)
Underwater	Underwater and the player is not in an Ocean, Deep Ocean, or River biome.
Player	Special biome that is used to configure sounds for the player themselves.

Java regex Notes

• The period . is a special operator meaning “any character”. The asterisk * is another operator meaning “zero or more”. So when you see something like “.*swamp” it means “swamp that can have zero or more characters in front of it”.
• The plus + is another operator. Since some biomes have the + character in the name to reference it in a regex expression you must escape it by using a couple of backslash characters: “\\+”.
• Use (?i) to ignore letter case. Example: “(?i)swamp” will match “Swamp” and “swamp”.
• To do a not style match use (?!). Example: “(?!Swamp)” will match any string that is not “Swamp”.
• Use | to do an OR. Example: “This|That” will match strings “This” or “That”.
• Combine the above together to form complex criteria matching. Example: “(?i)(?!.*swamp.*)(.*wet.*|.*smelly.*)” will match any string containing “wet” or “smelly”, but does not include “swamp”. The comparison is made ignoring case.
• More detailed regex information can be found on the Java website.