TerraScript Functions

Terra's TerraScript implementation contains many functions for interacting with the world, getting and setting data, and debugging.

block

The block function sets a block at a location.

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) to place block
y	num	Y coordinate (relative to origin) to place block
z	num	Z coordinate (relative to origin) to place block
data	str	Block Data string to place (must be constant expression)
replace	bool	Whether to replace an existing block. This is optional and defaults to true. When true, any block will be overwritten (this is the default behavior when this parameter is unspecified) When false, only air will be overwritten.

Returns: VOID

check

The check function checks the "type" of a location. It is a fast way to tell whether a location is in the air, ocean, or ground. While it cannot provide specific block state information, it is much faster than getBlock, and does not force-load chunks it is used in. It is recommended to avoid getBlock in regular structures, and use check whenever possible.

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) to check
y	num	Y coordinate (relative to origin) to check
z	num	Z coordinate (relative to origin) to check

Returns: STRING - The type of the location at the parameter coordinates, added to the structure origin. Must be one of:

• AIR - The location is air.
• LAND - The location is in the land.
• OCEAN - The location is in the ocean.

structure

The structure function generates another structure within the current structure, with an offset origin and rotation.

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) to place structure
y	num	Y coordinate (relative to origin) to place structure
z	num	Z coordinate (relative to origin) to place structure
structure	str	ID of structure to generate (equal to the id statement of that structure's script)
rotation	str...	Rotations to generate this structure with. One of these rotations will be randomly selected. Valid rotations are: NONE (No rotation), CW_90 (Clockwise 90 degrees), CCW_90 (Counterclockwise 90 degrees), and CW_180 (180 degrees)

* ... in the rotation parameter type description means that it is a vararg parameter - it may contain any number of values.

Returns: BOOlEAN - true if structure successfully generated, false if generation failed.

randomInt

The randomInt function returns a random value within a range.

Arguments:

Parameter	Type	Description
range	num	Maximum value (exclusive)

Returns: NUMBER - A random integer (whole number) between 0 (inclusive) and range (exclusive). For example, randomInt(10) would return a number from 0 to 9.

recursions

The recursions function gets the number of recursions that have occurred prior to the generation of the structure. It is incredibly useful for preventing infinite recursion in recursive structures.

Arguments: none

Returns: NUMBER - The number of recursions that have occurred.

If structure_a is generates structure_b via the structure function, recursions() would return 0 in structure_a, then 1 in structure_b. If structure_b then generated structure_a again, recursions() would return 2 in the second instance of structure_a only.

setMark

The setMark function is one of two functions for interacting with Marks, which allow data to be stored in structures and accessed later, without affecting generation. A Mark is a string assigned to a location in a structure. It is set by the setMark function, and then can be retrieved by the getMark function. One possible use case includes marking locations where structures generate, then checking them with getMark to ensure structures do not overlap.

Marks set in recursive structures are visible by parent structures. if structure_a generates structure_b via the structure function, and structure_b sets a mark, structure_a can retrieve that mark. Marks are set relative to the added origins of all recursions.

Setting a mark that already exists will overwrite it with a new value.

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) to set mark
y	num	Y coordinate (relative to origin) to set mark
z	num	Z coordinate (relative to origin) to set mark
content	str	Content of the mark to place

Returns: VOID

getMark

The getMark function is one of two functions for interacting with Marks, which allow data to be stored in structures and accessed later, without affecting generation. A Mark is a string assigned to a location in a structure. It is set by the setMark function, and then can be retrieved by the getMark function. One possible use case includes marking locations where structures generate, then checking them with getMark to ensure structures do not overlap.

Marks set in recursive structures are visible by parent structures. if structure_a generates structure_b via the structure function, and structure_b sets a mark, structure_a can retrieve that mark. Marks are set relative to the added origins of all recursions.

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) to check mark
y	num	Y coordinate (relative to origin) to check mark
z	num	Z coordinate (relative to origin) to check mark

Returns: STRING - The content of the mark at the location. Returns "" (empty string) if the mark is empty or not present.

pull

The pull function sets a block at a location, then "pulls" it down to ground. The pull function will search at the specified location, then downwards, until the block is not air.

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) to place block
y	num	Y coordinate (relative to origin) to start search
z	num	Z coordinate (relative to origin) to place block
data	str	Block Data string to place (must be constant expression)

Returns: VOID

loot

The loot function populates a container with loot. A container is any block with an inventory (chests, shulker boxes, furnaces, brewing stands, etc.)

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) to fill loot
y	num	Y coordinate (relative to origin) to fill loot
z	num	Z coordinate (relative to origin) to fill loot
table	str	Filename of the loot table, relative to pack/structures/loot. Example: village/village_house.json

Returns: VOID

entity

The entity function spawns an entity at a location.

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) to spawn entity
y	num	Y coordinate (relative to origin) to spawn entity
z	num	Z coordinate (relative to origin) to spawn entity
entity	str	Entity ID to spawn

Returns: VOID

getBiome

The getBiome function gets the Terra biome at a location.

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) to check biome
y	num	Y coordinate (relative to origin) to check biome
z	num	Z coordinate (relative to origin) to check biome

Returns: STRING - The ID of the biome, E.G. "ARID_MOUNTAINS".

getBlock

The getBlock function checks the Block State at a location. It should NOT be used in regular structures!

The getBlock function force-loads chunks when it runs. This is fine in trees, which load chunks anyways, but in regular structures it will cause cascading chunk loading whenever a structure generates. Use the check function instead in regular structures!

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) to check block
y	num	Y coordinate (relative to origin) to check block
z	num	Z coordinate (relative to origin) to check block

Returns: STRING - The ID of the block, without properties, E.G. "minecraft:stone".

state

The state function manipulates NBT data on block entities (like signs and mob spawners).

Data is formatted as "key1=value1,key2=value2". E.G. "text1=hello,text2=world" applied to a sign would cause the sign to read:

hello
world

Arguments:

Parameter	Type	Description
x	num	X coordinate (relative to origin) of block
y	num	Y coordinate (relative to origin) of block
z	num	Z coordinate (relative to origin) of block
data	str	Data to apply to block

Returns: VOID

print

The print function prints a string to the console. It is a debug function, and as such will only work with debug mode enabled.

Arguments:

Parameter	Type	Description
message	str	Message to print to console

Returns: VOID