Tutorial: Condition Strings

For 3.1.3.0BETA+

When creating a configuration file some of the elements have a condition string option. The condition string tells Dynamic Surroundings the circumstances under which a sound or effect can occur. For example, attached the the PLAYER biome is the heartbeat sound that will play when the player is considered “hurt” and will not play at any other time.

In Dynamic Surroundings versions prior to 3.1.3.0BETA this condition string was a regular expression that would match a series of tokens in a string generated by Dynamic Surroundings. Though it worked well regular expressions can be daunting, especially if a more complicated set of circumstances needed to be crafted.

Starting with 3.1.3.0BETA the condition string can be in the form a logical equation. Using the heartbeat example above the regular expression for the sound “(?i).*#hurt#.*” can be replaced with “player.isHurt”. Another example is the rattlesnake sound that plays in deserts: “(?i)(?!.*#raining#.*).*#day#.*” can be turned into “isNotRaining && isDay”.

Since Dynamic Surroundings can do either regular expressions or logical equation the way it determines which to use is based on the starting characters in the string. If the string starts with “(?i)” it will consider it a regular expression. Otherwise, it will treat the string as a logical equation to be executed.

There are no boolean types in the language. TRUE and FALSE are based the classic C approach: 0 means FALSE, and TRUE is not FALSE. An expression like “10 * FALSE” will evaluate to “0”.

The expression must generate a TRUE or FALSE result. Any other result will cause an error.

Built-In Operators

Operator	Name	Example
+	Plus	5 + 6
-	Minus	6 - 5
*	Multiply	4 * 5
/	Divide	9 / 4
%	Modulus	8 % 4
&&	Logical And	isNotRaining && isDay
||	Logical Or	player.isWarm || player.isCold
>	Greater Than	9 > 8
>=	Greater Than Equal	10 >= 11
<	Less Than	8 < 9
<=	Less Than Equal	6 <= 6
=	Equal	8 = 9
==	Equivalent	“this” == “that”
!=	Not Equal	9 != 10
<>	Not Equal	9 <> 10

Built-in Functions

Function	Description
MATCH(regex, input)	Performs a regular expression match
NOT(expression)	Performs a logical not on an expression. A value of 0 becomes 1, and a value of non-zero becomes 0.
IF(condition, trueExp, falseExp)	Performs one of two evaluations based on a condition
MAX(exp1,exp2,…)	Determines the max value from a selection of expressions
MIN(exp1,exp2,…)	Determines the min value from a selection of expressions
ABS(exp)	Determines the absolute value of an expression
ROUND(exp)	Rounds a number to the closest integer value
FLOOR(exp)	Returns the largest integer less than or equal to exp.
CEILING(exp)	Returns the smallest integer greater than or equal to exp.
SQRT(exp)	Calculates the square root of an expression
CLAMP(exp,min,max)	Ensures that an expression is within the specified bounds

Built-in Variables

Variables	Description
TRUE	Indicates true. Has a value of 1.
FALSE	Indicates false. Has a value of 0.
isRaining	If it is currently raining
isNotRaining	Inverse of isRaining; same as NOT(isRaining)
isDay	It is currently daylight
isNight	Inverse of isDay; same as NOT(isDay)
isSunrise	It is currently sunrise
isSunset	It is currently sunset
isFoggy	There is some sort of fog effect being applied
isHumid	The player biome has high rainfall
isDry	The player biome has no rainfall
isAuroraVisible	The player dimension can display auroras
moonPhaseFactor	The current phase of the moon
hasSky	The player dimension has a sky
player.isHurt	Indicates if the players health is below the configured threshold
player.isHungry	Indicates if the player’s food level is below the configured threshold
player.isBurning	The player is on fire
player.isSuffocating	The player is out of air
player.isFlying	The player is flying
player.isSprinting	The player is sprinting
player.isInLava	The player is currently swimming in lava
player.isInvisible	The player is invisible
player.isBlind	The player is affected by the Blindness potion effect
player.isInWater	The player is currently swimming in water
player.isRiding	The player is mounted on a mob such as a horse or pig
player.isOnGround	The player is standing on the ground
player.isMoving	The player is moving
player.isInside	The player is considered inside a structure
player.isUnderground	The player is considered underground
player.isInSpace	The player is considered at a very high Y level
player.isInClouds	The player is around the dimension cloud height
player.isFreezing	The temperature at the player location is very low
player.isCold	The climate of the player biome is considered COLD
player.isWarm	The climate of the player biome is considered WARM
player.dimension	The dimension id of the dimension the player is in
player.dimensionName	The name of the dimension the player is in
player.Y	The players current elevation
player.biome	The players current biome (e.g. “Plains”)
player.health	The player’s current health level
player.maxHealth	The player’s max health
player.luck	The player’s luck
player.food.saturation	The player’s current food saturation level
player.food.level	The player’s current food level (i.e. number of hams)

---

Examples

player.health <= 8

This is essentially “player.isHurt” based on a default configuration. This is fragile, howevever, because a modpack author cannot tune the threshold.

player.biome == "Plains"

Returns TRUE if the player’s current biome name is “Plains”.

MATCH("(?i)(.*plains.*)", player.biome)

Uses a regular expression to evaluate the player’ current biome name. If the name contains “plains” regardless of case it will return TRUE.

IF(player.dimension == 0, player.isHurt, player.health <= 16)

If the player is currently in Overworld (dimension 0) it will return whether the player is hurt or not. If it is not Overworld then it will return whether the player’s current health is less than or equal to 16.

---

Notes

• If you use strings in an expression you will need to escape them in the configuration file. The example below has “Overworld” escaped:

{
    "biomeName":"(?i)(.*taiga.*|.*snow.*forest.*)",
    "sounds":[
	{
		"sound":"dsurround:owl",
		"conditions":"player.dimensionName == \"Overworld\" && isNotRaining && isNight",
		"soundType":"spot",
		"volume":0.3
	},