Tutorial: Condition Strings

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.

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.temperature == ‘icy’ || player.temperature == ‘cold’
>	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
!	Not	Inverts a logical value (See NOT function below)

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
ONEOF(exp,v1,…)	Determines if the result of the expression matches any of the specified values

Built-in Variables

Variable	Type	Description
TRUE	boolean	Indicates true. Has a value of 1.
FALSE	boolean	Indicates false. Has a value of 0.
hasSky	boolean	Indicates if the world has a sky
isAuroraVisible	boolean	Indicates if the world can have auroras
isDay	boolean	Current celestial angle of the sun indicates daytime
isNight	boolean	Not day
isSunrise	boolean	Current celestial angle of the sun indicates sunrise
isSunset	boolean	Current celestial angle of the sun indicates sunset
moonPhaseFactor	float	Phase of the moon: 0.0, 0.25, 0.5, 0.75, 1.0
season	string	Name of the current season if supported: ‘noseason’, ‘spring’, ‘summer’, ‘autumn’, ‘winter’
battle.inBattle	boolean	Whether a battle is taking place near the player (v3.4.1.1+)
battle.isBoss	boolean	A boss is involved in a battle (v3.4.1.1+)
battle.isDragon	boolean	The Ender Dragon is battling (v3.4.1.1+)
battle.isWither	boolean	The Wither is battling (v3.4.1.1+)
biome.isBEACH	boolean	The current player biome has the BEACH trait (v3.4.1.0+)
biome.isCOLD	boolean	The current player biome has the COLD trait (v3.4.1.0+)
biome.isCONIFEROUS	boolean	The current player biome has the CONIFEROUS trait (v3.4.1.0+)
biome.isDEAD	boolean	The current player biome has the DEAD trait (v3.4.1.0+)
biome.isDENSE	boolean	The current player biome has the DENSE trait (v3.4.1.0+)
biome.isDRY	boolean	The current player biome has the DRY trait (v3.4.1.0+)
biome.isEND	boolean	The current player biome has the END trait (v3.4.1.0+)
biome.isFOREST	boolean	The current player biome has the FOREST trait (v3.4.1.0+)
biome.isHILLS	boolean	The current player biome has the HILLS trait (v3.4.1.0+)
biome.isHOT	boolean	The current player biome has the HOT trait (v3.4.1.0+)
biome.isJUNGLE	boolean	The current player biome has the JUNGLE trait (v3.4.1.0+)
biome.isLUSH	boolean	The current player biome has the LUSH trait (v3.4.1.0+)
biome.isMAGICAL	boolean	The current player biome has the MAGICAL trait (v3.4.1.0+)
biome.isMESA	boolean	The current player biome has the MESA trait (v3.4.1.0+)
biome.isMOUNTAIN	boolean	The current player biome has the MOUNTAIN trait (v3.4.1.0+)
biome.isMUSHROOM	boolean	The current player biome has the MUSHROOM trait (v3.4.1.0+)
biome.isNETHER	boolean	The current player biome has the NETHER trait (v3.4.1.0+)
biome.isOCEAN	boolean	The current player biome has the OCEAN trait (v3.4.1.0+)
biome.isPLAINS	boolean	The current player biome has the PLAINS trait (v3.4.1.0+)
biome.isRARE	boolean	The current player biome has the RARE trait (v3.4.1.0+)
biome.isRIVER	boolean	The current player biome has the RARE trait (v3.4.1.0+)
biome.isSANDY	boolean	The current player biome has the SANDY trait (v3.4.1.0+)
biome.isSAVANNA	boolean	The current player biome has the SAVANNA trait (v3.4.1.0+)
biome.isSNOWY	boolean	The current player biome has the SNOWY trait (v3.4.1.0+)
biome.isSPARSE	boolean	The current player biome has the SPARSE trait (v3.4.1.0+)
biome.isSPOOKY	boolean	The current player biome has the SPOOKY trait (v3.4.1.0+)
biome.isSWAMP	boolean	The current player biome has the SWAMP trait (v3.4.1.0+)
biome.isVOID	boolean	The current player biome has the VOID trait (v3.4.1.0+)
biome.isWASTELAND	boolean	The current player biome has the WASTELAND trait (v3.4.1.0+)
biome.isWATER	boolean	The current player biome has the WATER trait (v3.4.1.0+)
biome.isWET	boolean	The current player biome has the WET trait (v3.4.1.0+)
biome.name	string	Name of the player biome
biome.rainfall	float	The rainfall rating of the player biome
biome.temperature	string	The temperature rating of the player biome: ‘icy’, ‘cold’, ‘mild’, ‘warm’, ‘hot’
biome.temperatureValue	float	The temperature value of the player biome
player.X	float	Player’s X coordinate
player.Y	float	Player’s Y coordinate (elevation)
player.Z	float	Player’s Z coordinate
player.canRainOn	boolean	The player can get rained on in the current location
player.canSeeSky	boolean	The player can see sky from the current location
player.dimension	float	Dimension ID of the current player dimension
player.dimensionName	string	Dimension name of the current player dimension
player.food.saturation	float	The player’s current food saturation level
player.food.level	float	The player’s current food level (i.e. number of hams)
player.health	float	The player’s current health level
player.maxHealth	float	The player’s max health
player.inBoat	boolean	Player is currently in a boat
player.isBlind	boolean	Player has the blindness potion effect
player.isBurning	boolean	Player is on fire
player.isFlying	boolean	Player is flying
player.isHungry	boolean	Indicates if the player’s food level is below the configured threshold
player.isHurt	boolean	Indicates if the players health is below the configured threshold
player.isInClouds	boolean	The player is around the dimension cloud height
player.isInLava	boolean	The player is currently swimming in lava
player.isInSpace	boolean	The player is considered at a very high Y level
player.isInWater	boolean	The player is currently swimming in water
player.isInside	boolean	The player is considered inside a structure
player.isInvisible	boolean	The player is invisible
player.isMoving	boolean	The player is moving
player.isOnGround	boolean	The player is standing on the ground
player.isRiding	boolean	The player is mounted on a mob such as a horse or pig
player.isSprinting	boolean	The player is sprinting
player.isSuffocating	boolean	The player is out of air
player.isUnderground	boolean	The player is considered underground
player.isUnderwater	boolean	The player’s head is in a liquid block
player.isWet	boolean	Player is getting rained on, swimming, or underwater
player.lightLevel	float	Light level calculated at the player’s legs
player.luck	float	The player’s luck
player.temperature	string	Current temperature the player is feeling: ‘icy’, ‘cold’, ‘mild’, ‘warm’, or ‘hot’
weather.isNotRaining	boolean	Not raining/snowing
weather.isNotThundering	boolean	Not thundering (not in a storm)
weather.isRaining	boolean	Is raining/snowing
weather.isThundering	boolean	Is thundering (in a storm)
weather.rainfall	float	Amount of rainfall if currently raining/snowing
weather.temperature	string	Weather temperature: ‘icy’, ‘cold’, ‘mild’, ‘warm’, ‘hot’
weather.temperatureValue	float	Weather temperature value

---

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.

biome.name == 'Plains'

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

MATCH('(?i)(.*plains.*)', biome.name)

Uses a regular expression to evaluate the player’s 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.

ONEOF(biome.temperature, 'icy', 'cold', 'mild')

Returns TRUE if the ‘biome.temperature’ is ‘icy’, ‘cold’, or ‘mild’. This is a more compact form of chaining a bunch of ‘==’ expressions with ‘||’.

ONEOF(player.dimension, 0, -1)

Returns TRUE if the player dimension is either Overworld or Nether.

---

Notes

• Strings are denoted in a script by using the apostrophe ‘. This is to minimize errors introduced in the Json config because of escaping. Example of the word ‘Overworld’ below:

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

• In a lot of cases ‘player.temperature’ and ‘biome.temperature’ will be the same. However, other mods can change dynamics of what the player experiences and what actually exists in the biome. A good example is the mod Tough As Nails. My recommendation is to use ‘player.temperature’ when dealing with PLAYER biome effects, and ‘biome.temperature’ for things attached to Biomes.