Test Class
Main class for GameTest functions, with helpers and data for manipulating the respective test. Note that all methods of this class expect BlockLocations and Locations relative to the GameTest structure block.
Methods
- assert
- assertBlockPresent
- assertBlockState
- assertCanReachLocation
- assertContainerContains
- assertContainerEmpty
- assertEntityHasArmor
- assertEntityHasComponent
- assertEntityInstancePresent
- assertEntityInstancePresentInArea
- assertEntityPresent
- assertEntityPresentInArea
- assertEntityState
- assertEntityTouching
- assertIsWaterlogged
- assertItemEntityCountIs
- assertItemEntityPresent
- assertRedstonePower
- destroyBlock
- fail
- failIf
- getBlock
- getDimension
- getFenceConnectivity
- getSculkSpreader
- getTestDirection
- idle
- killAllEntities
- onPlayerJump
- pressButton
- pullLever
- pulseRedstone
- relativeBlockLocation
- relativeLocation
- removeSimulatedPlayer
- rotateDirection
- rotateVector
- runAfterDelay
- runAtTickTime
- setBlockPermutation
- setBlockType
- setFluidContainer
- setTntFuse
- spawn
- spawnAtLocation
- spawnItem
- spawnSimulatedPlayer
- spawnWithoutBehaviors
- spawnWithoutBehaviorsAtLocation
- spreadFromFaceTowardDirection
- startSequence
- succeed
- succeedIf
- succeedOnTick
- succeedOnTickWhen
- succeedWhen
- succeedWhenBlockPresent
- succeedWhenEntityHasComponent
- succeedWhenEntityPresent
- triggerInternalBlockEvent
- until
- walkTo
- walkToLocation
- worldBlockLocation
- worldLocation
assert
assert(condition: boolean, message: string): void
Tests that the condition specified in condition is true. If not, an error with the specified message is thrown.
Parameters
condition: boolean
Expression of the condition to evaluate.
message: string
Message that is passed if the condition does not evaluate to true.
assertBlockPresent
assertBlockPresent(blockType: minecraftserver.BlockType | string, blockLocation: minecraftserver.Vector3, isPresent?: boolean): void
Tests that a block of the specified type is present at the specified location. If it is not, an exception is thrown.
Parameters
blockType: @minecraft/server.BlockType | string
Expected block type.
blockLocation: @minecraft/server.Vector3
Location of the block to test at.
isPresent?: boolean =
true
If true, this function tests whether a block of the specified type is at the location. If false, tests that a block of the specified type is not present.
assertBlockState
assertBlockState(blockLocation: minecraftserver.Vector3, callback: (arg: minecraftserver.Block) => boolean): void
Tests that a block has a particular state value at the specified location. If it does not have that state value, an exception is thrown.
Parameters
blockLocation: @minecraft/server.Vector3
Location of the block to test at.
callback: (arg: @minecraft/server.Block) => boolean
Callback function that contains additional tests based on the block at the specified location.
Examples
testIfButtonNotPressed.js
test.assertBlockState(buttonPos, (block) => {
return block.permutation.getProperty("button_pressed_bit") == 0;
});
assertCanReachLocation
assertCanReachLocation(mob: minecraftserver.Entity, blockLocation: minecraftserver.Vector3, canReach?: boolean): void
Tests that an entity can reach a particular location. Depending on the value of canReach, throws an exception if the condition is not met.
Parameters
-
Entity that you wish to test the location against.
blockLocation: @minecraft/server.Vector3
Structure-relative location to test whether the specified mob can reach.
canReach?: boolean =
true
If true, tests whether the mob can reach the location. If false, tests whether the mob is not able to reach the location.
assertContainerContains
assertContainerContains(itemStack: minecraftserver.ItemStack, blockLocation: minecraftserver.Vector3): void
Tests that a container (e.g., a chest) at the specified location contains a specified of item stack. If not, an error is thrown.
Parameters
itemStack: @minecraft/server.ItemStack
Represents the type of item to check for. The specified container must contain at least 1 item matching the item type defined in itemStack.
blockLocation: @minecraft/server.Vector3
Location of the block with a container (for example, a chest) to test the contents of.
assertContainerEmpty
assertContainerEmpty(blockLocation: minecraftserver.Vector3): void
Tests that a container (e.g., a chest) at the specified location is empty. If not, an error is thrown.
Parameters
blockLocation: @minecraft/server.Vector3
Location of the block with a container (for example, a chest) to test is empty of contents.
assertEntityHasArmor
assertEntityHasArmor(entityTypeIdentifier: string, armorSlot: number, armorName: string, armorData: number, blockLocation: minecraftserver.Vector3, hasArmor?: boolean): void
Tests that an entity has a specific piece of armor equipped. If not, an error is thrown.
Parameters
entityTypeIdentifier: string
Identifier of the entity to match (e.g., 'minecraft:skeleton').
armorSlot: number
Container slot index to test.
armorName: string
Name of the armor to look for.
armorData: number
Data value integer to look for.
blockLocation: @minecraft/server.Vector3
Location of the entity with armor to test for.
hasArmor?: boolean =
true
Whether or not the entity is expected to have the specified armor equipped.
Examples
horseArmorTest.js
test.assertEntityHasArmor("minecraft:horse", armorSlotTorso, "diamond_horse_armor", 0, horseLocation, true);
assertEntityHasComponent
assertEntityHasComponent(entityTypeIdentifier: string, componentIdentifier: string, blockLocation: minecraftserver.Vector3, hasComponent?: boolean): void
Tests that an entity has a particular component. If not, an exception is thrown.
Parameters
entityTypeIdentifier: string
Identifier of the specified entity (e.g., 'minecraft:skeleton'). If the namespace is not specified, 'minecraft:' is assumed.
componentIdentifier: string
Identifier of the component to check for. If the namespace is not specified, 'minecraft:' is assumed.
blockLocation: @minecraft/server.Vector3
Location of the block with a container (for example, a chest.)
hasComponent?: boolean =
true
Determines whether to test that the component exists, or does not.
Examples
sheepShearedTest.js
test.assertEntityHasComponent("minecraft:sheep", "minecraft:is_sheared", entityLoc, false);
assertEntityInstancePresent
assertEntityInstancePresent(entity: minecraftserver.Entity, blockLocation: minecraftserver.Vector3, isPresent?: boolean): void
Depending on the value for isPresent, tests that a particular entity is present or not present at the specified location. Depending on the value of isPresent, if the entity is found or not found, an error is thrown.
Parameters
entity: @minecraft/server.Entity
Specific entity to test for.
blockLocation: @minecraft/server.Vector3
Location of the entity to test for.
isPresent?: boolean =
true
Whether to test that an entity is present or not present at the specified location.
assertEntityInstancePresentInArea
assertEntityInstancePresentInArea(entity: minecraftserver.Entity, isPresent?: boolean): void
Tests that an entity instance is present within the GameTest area. If not, an exception is thrown.
Parameters
entity: @minecraft/server.Entity
Entity instance to test for.
isPresent?: boolean =
true
If true, this function tests whether the specified entity is present in the GameTest area. If false, tests that the specified entity is not present.
Examples
simpleMobTest.ts
import * as gameTest from '@minecraft/server-gametest';
gameTest
.register('StarterTests', 'simpleMobTest', (test: gameTest.Test) => {
const attackerId = 'fox';
const victimId = 'chicken';
test.spawn(attackerId, { x: 5, y: 2, z: 5 });
const victim = test.spawn(victimId, { x: 2, y: 2, z: 2 });
test.assertEntityInstancePresentInArea(victim, true);
test.succeedWhen(() => {
test.assertEntityInstancePresentInArea(victim, false);
});
})
.maxTicks(400)
.structureName('gametests:mediumglass');
assertEntityPresent
assertEntityPresent(entityTypeIdentifier: string, blockLocation: minecraftserver.Vector3, searchDistance?: number, isPresent?: boolean): void
Depending on the value of isPresent, tests for the presence or non-presence of entity of a specified type at a particular location. If the condition is not met, an exception is thrown.
Parameters
entityTypeIdentifier: string
Type of entity to test for (e.g., 'minecraft:skeleton'). If an entity namespace is not specified, 'minecraft:' is assumed.
blockLocation: @minecraft/server.Vector3
Location of the entity to test for.
searchDistance?: number =
0
The distance to search for the entity from the blockLocation.
isPresent?: boolean =
true
If true, this function tests whether an entity of the specified type is present. If false, tests that an entity of the specified type is not present.
assertEntityPresentInArea
assertEntityPresentInArea(entityTypeIdentifier: string, isPresent?: boolean): void
Tests that an entity of a specified type is present within the GameTest area. If not, an exception is thrown.
Parameters
entityTypeIdentifier: string
Type of entity to test for (e.g., 'minecraft:skeleton'). If an entity namespace is not specified, 'minecraft:' is assumed.
isPresent?: boolean =
true
If true, this function tests whether an entity of the specified type is present in the GameTest area. If false, tests that an entity of the specified type is not present.
Examples
simpleMobTest.ts
import * as gameTest from '@minecraft/server-gametest';
gameTest
.register('StarterTests', 'simpleMobTest', (test: gameTest.Test) => {
const attackerId = 'fox';
const victimId = 'chicken';
test.spawn(attackerId, { x: 5, y: 2, z: 5 });
test.spawn(victimId, { x: 2, y: 2, z: 2 });
test.assertEntityPresentInArea(victimId, true);
test.succeedWhen(() => {
test.assertEntityPresentInArea(victimId, false);
});
})
.maxTicks(400)
.structureName('gametests:mediumglass');
assertEntityState
assertEntityState(blockLocation: minecraftserver.Vector3, entityTypeIdentifier: string, callback: (arg: minecraftserver.Entity) => boolean): void
Tests that an entity (e.g., a skeleton) at the specified location has a particular piece of data. If not, an error is thrown.
Parameters
blockLocation: @minecraft/server.Vector3
Location of the entity to look for.
entityTypeIdentifier: string
Identifier of the entity (e.g., 'minecraft:skeleton') to look for. Note if no namespace is specified, 'minecraft:' is assumed.
callback: (arg: @minecraft/server.Entity) => boolean
Callback function where facets of the selected entity can be tested for. If this callback function returns false or no entity with the specified identifier is found, an exception is thrown.
Examples
villagerEffectTest.js
test.assertEntityState(
villagerPos,
"minecraft:villager_v2",
(entity) => entity.getEffect(MinecraftEffectTypes.Regeneration).duration > 120
); // At least 6 seconds remaining in the villagers' effect
assertEntityTouching
assertEntityTouching(entityTypeIdentifier: string, location: minecraftserver.Vector3, isTouching?: boolean): void
Depending on the value of isTouching, tests that an entity of a specified type is touching or connected to another entity. If the condition is not met, an exception is thrown.
Parameters
entityTypeIdentifier: string
Type of entity to test for (e.g., 'minecraft:skeleton'). If an entity namespace is not specified, 'minecraft:' is assumed.
location: @minecraft/server.Vector3
Location of the entity to test for.
isTouching?: boolean =
true
If true, this function tests whether the entity is touching the specified location. If false, tests that an entity is not testing the specified location.
assertIsWaterlogged
assertIsWaterlogged(blockLocation: minecraftserver.Vector3, isWaterlogged?: boolean): void
Depending on the value of isWaterlogged, tests that a block at a location contains water. If the condition is not met, an error is thrown. Pure water blocks are not considered to be waterlogged.
Parameters
blockLocation: @minecraft/server.Vector3
Location of the block to test for.
isWaterlogged?: boolean =
true
Whether to test that the block at position is expected to be waterlogged.
assertItemEntityCountIs
assertItemEntityCountIs(itemType: minecraftserver.ItemType | string, blockLocation: minecraftserver.Vector3, searchDistance: number, count: number): void
Tests that items of a particular type and count are present within an area. If not, an error is thrown.
Parameters
itemType: @minecraft/server.ItemType | string
Type of item to look for.
blockLocation: @minecraft/server.Vector3
Location to search around for the specified set of items.
searchDistance: number
Range, in blocks, to aggregate a count of items around. If 0, will only search the particular block at position.
count: number
Number of items, at minimum, to look and test for.
Examples
findFeathers.js
test.assertItemEntityCountIs(Items.feather, expectedFeatherLoc, 0, 1);
assertItemEntityPresent
assertItemEntityPresent(itemType: minecraftserver.ItemType | string, blockLocation: minecraftserver.Vector3, searchDistance?: number, isPresent?: boolean): void
Depending on the value of isPresent, tests whether a particular item entity is present or not at a particular location. If the condition is not met, an exception is thrown.
Parameters
itemType: @minecraft/server.ItemType | string
Type of item to test for.
blockLocation: @minecraft/server.Vector3
Location of the item entity to test for.
searchDistance?: number =
0
Radius in blocks to look for the item entity.
isPresent?: boolean =
true
If true, this function tests whether an item entity of the specified type is present. If false, tests that an item entity of the specified type is not present.
assertRedstonePower
assertRedstonePower(blockLocation: minecraftserver.Vector3, power: number): void
Tests that Redstone power at a particular location matches a particular value. If not, an exception is thrown.
Parameters
blockLocation: @minecraft/server.Vector3
Location to test.
power: number
Expected power level.
destroyBlock
destroyBlock(blockLocation: minecraftserver.Vector3, dropResources?: boolean): void
Destroys a block at a particular location.
Parameters
blockLocation: @minecraft/server.Vector3
Location of the block to destroy.
dropResources?: boolean =
false
Whether to add resources exposed with a particular drop.
Important
This function can't be called in read-only mode.
fail
fail(errorMessage: string): void
Marks the current test as a failure case.
Parameters
errorMessage: string
Error message summarizing the failure condition.
Warning
This function can throw errors.
failIf
failIf(callback: () => void): void
Runs the given callback. If the callback does not throw an exception, the test is marked as a failure.
Parameters
callback: () => void
Callback function that runs. If the function runs successfully, the test is marked as a failure. Typically, this function will have .assertXyz method calls within it.
Warning
This function can throw errors.
getBlock
getBlock(blockLocation: minecraftserver.Vector3): minecraftserver.Block
Gets a block at the specified block location.
Parameters
blockLocation: @minecraft/server.Vector3
Location of the block to retrieve.
Returns @minecraft/server.Block
Important
This function can't be called in read-only mode.
getDimension
getDimension(): minecraftserver.Dimension
Gets the dimension of this test.
Returns @minecraft/server.Dimension
getFenceConnectivity
getFenceConnectivity(blockLocation: minecraftserver.Vector3): FenceConnectivity
If the block at the specified block location is a fence, this returns a helper object with details on how a fence is connected.
Parameters
blockLocation: @minecraft/server.Vector3
Location of the block to retrieve.
Returns FenceConnectivity
Important
This function can't be called in read-only mode.
getSculkSpreader
getSculkSpreader(blockLocation: minecraftserver.Vector3): SculkSpreader | undefined
Retrieves a sculk spreader object that can be used to control and manage how sculk grows from a block.
Parameters
blockLocation: @minecraft/server.Vector3
Location of the block to retrieve a sculk spreader from.
Returns SculkSpreader | undefined - Returns the SculkSpreader or undefined if no SculkSpreader is present on the block.
Important
This function can't be called in read-only mode.
getTestDirection
getTestDirection(): minecraftserver.Direction
Returns the direction of the current test - see the @minecraft/server.Direction enum for more information on potential values (north, east, south, west - values 2-5).
Returns @minecraft/server.Direction
idle
idle(tickDelay: number): Promise<void>
This asynchronous function will wait for the specified time in ticks before continuing execution.
Parameters
tickDelay: number
Amount of time to wait, in ticks.
Returns Promise<void>
Important
This function can't be called in read-only mode.
killAllEntities
killAllEntities(): void
Kills all entities within the GameTest structure.
Important
This function can't be called in read-only mode.
onPlayerJump
onPlayerJump(mob: minecraftserver.Entity, jumpAmount: number): void
Parameters
- mob: @minecraft/server.Entity
- jumpAmount: number
Important
This function can't be called in read-only mode.
pressButton
pressButton(blockLocation: minecraftserver.Vector3): void
Presses a button at a block location.
Parameters
blockLocation: @minecraft/server.Vector3
Location to push the button at.
Important
This function can't be called in read-only mode.
print(text: string): void
Displays the specified message to all players.
Parameters
text: string
Message to display.
Important
This function can't be called in read-only mode.
pullLever
pullLever(blockLocation: minecraftserver.Vector3): void
Pulls a lever at a block location.
Parameters
blockLocation: @minecraft/server.Vector3
Location to pull the lever at.
Important
This function can't be called in read-only mode.
pulseRedstone
pulseRedstone(blockLocation: minecraftserver.Vector3, duration: number): void
Sends a Redstone pulse at a particular location by creating a temporary Redstone block.
Parameters
blockLocation: @minecraft/server.Vector3
Location to pulse Redstone at.
duration: number
Number of ticks to pulse Redstone.
Important
This function can't be called in read-only mode.
relativeBlockLocation
relativeBlockLocation(worldBlockLocation: minecraftserver.Vector3): minecraftserver.Vector3
From a BlockLocation, returns a new BlockLocation with coordinates relative to the current GameTest structure block. For example, the relative coordinates for the block above the structure block are (0, 1, 0). Rotation of the GameTest structure is also taken into account.
Parameters
worldBlockLocation: @minecraft/server.Vector3
Absolute location in the world to convert to a relative location.
Returns @minecraft/server.Vector3 - A location relative to the GameTest command block.
relativeLocation
relativeLocation(worldLocation: minecraftserver.Vector3): minecraftserver.Vector3
From a location, returns a new location with coordinates relative to the current GameTest structure block. For example, the relative coordinates for the block above the structure block are (0, 1, 0). Rotation of the GameTest structure is also taken into account.
Parameters
worldLocation: @minecraft/server.Vector3
Absolute location in the world to convert to a relative location.
Returns @minecraft/server.Vector3 - A location relative to the GameTest command block.
Important
This function can't be called in read-only mode.
removeSimulatedPlayer
removeSimulatedPlayer(simulatedPlayer: SimulatedPlayer): void
Removes a simulated player from the world.
Parameters
simulatedPlayer: SimulatedPlayer
Simulated player to remove.
Important
This function can't be called in read-only mode.
rotateDirection
rotateDirection(direction: minecraftserver.Direction): minecraftserver.Direction
Returns a relative direction given the current rotation of the current test. Passing in Direction.south will return the test direction; Passing in Direction.north will return the opposite of the test direction, and so on.
Parameters
direction: @minecraft/server.Direction
Direction to translate into a direction relative to the GameTest facing. Passing in Direction.south will return the test direction; Passing in Direction.north will return the opposite of the test direction, and so on.
Returns @minecraft/server.Direction
Important
This function can't be called in read-only mode.
rotateVector
rotateVector(vector: minecraftserver.Vector3): minecraftserver.Vector3
Parameters
- vector: @minecraft/server.Vector3
Returns @minecraft/server.Vector3
Important
This function can't be called in read-only mode.
runAfterDelay
runAfterDelay(delayTicks: number, callback: () => void): void
Runs a specific callback after a specified delay of ticks
Parameters
delayTicks: number
Number of ticks to delay before running the specified callback.
callback: () => void
Callback function to execute.
Important
This function can't be called in read-only mode.
Warning
This function can throw errors.
runAtTickTime
runAtTickTime(tick: number, callback: () => void): void
Runs the given callback after a delay of tick ticks from the start of the GameTest.
Parameters
tick: number
Tick (after the start of the GameTest) to run the callback at.
callback: () => void
Callback function to execute.
Important
This function can't be called in read-only mode.
Warning
This function can throw errors.
setBlockPermutation
setBlockPermutation(blockData: minecraftserver.BlockPermutation, blockLocation: minecraftserver.Vector3): void
Sets a block to a particular configuration (a BlockPermutation) at the specified block location.
Parameters
blockData: @minecraft/server.BlockPermutation
Permutation that contains the configuration data for a block.
blockLocation: @minecraft/server.Vector3
Location of the block to set.
Important
This function can't be called in read-only mode.
setBlockType
setBlockType(blockType: minecraftserver.BlockType | string, blockLocation: minecraftserver.Vector3): void
Sets a block to a particular type at the specified block location.
Parameters
blockType: @minecraft/server.BlockType | string
Type of block to set.
blockLocation: @minecraft/server.Vector3
Location of the block to set.
Important
This function can't be called in read-only mode.
setFluidContainer
setFluidContainer(location: minecraftserver.Vector3, type: minecraftserver.FluidType): void
For blocks that are fluid containers - like a cauldron - changes the type of fluid within that container.
Parameters
location: @minecraft/server.Vector3
Location of the fluid container block.
type: @minecraft/server.FluidType
Type of fluid to set. See {@link @minecraft/server-gametest.FluidType} for a list of values.
Important
This function can't be called in read-only mode.
setTntFuse
setTntFuse(entity: minecraftserver.Entity, fuseLength: number): void
Sets the fuse of an explodable entity.
Parameters
entity: @minecraft/server.Entity
Entity that is explodable.
fuseLength: number
Length of time, in ticks, before the entity explodes.
Important
This function can't be called in read-only mode.
spawn
spawn(entityTypeIdentifier: string, blockLocation: minecraftserver.Vector3): minecraftserver.Entity
Spawns an entity at a location.
Parameters
entityTypeIdentifier: string
Type of entity to create. If no namespace is provided, 'minecraft:' is assumed. Note that an optional initial spawn event can be specified between less than/greater than signs (e.g., namespace:entityType).
blockLocation: @minecraft/server.Vector3
Returns @minecraft/server.Entity - The spawned entity. If the entity cannot be spawned, returns undefined.
Important
This function can't be called in read-only mode.
Examples
simpleMobTest.ts
import * as gameTest from '@minecraft/server-gametest';
gameTest
.register('StarterTests', 'simpleMobTest', (test: gameTest.Test) => {
const attackerId = 'fox';
const victimId = 'chicken';
test.spawn(attackerId, { x: 5, y: 2, z: 5 });
test.spawn(victimId, { x: 2, y: 2, z: 2 });
test.assertEntityPresentInArea(victimId, true);
test.succeedWhen(() => {
test.assertEntityPresentInArea(victimId, false);
});
})
.maxTicks(400)
.structureName('gametests:mediumglass');
spawnAdultPig.js
test.spawn("minecraft:pig<minecraft:ageable_grow_up>", { x: 1, y: 2, z: 1 });
spawnAtLocation
spawnAtLocation(entityTypeIdentifier: string, location: minecraftserver.Vector3): minecraftserver.Entity
Spawns an entity at a location.
Parameters
entityTypeIdentifier: string
Type of entity to create. If no namespace is provided, 'minecraft:' is assumed. Note that an optional initial spawn event can be specified between less than/greater than signs (e.g., namespace:entityType).
location: @minecraft/server.Vector3
Returns @minecraft/server.Entity - The spawned entity. If the entity cannot be spawned, returns undefined.
Important
This function can't be called in read-only mode.
Examples
spawnAdultPig.js
test.spawn("minecraft:pig<minecraft:ageable_grow_up>", { x: 1.5, y: 2, z: 1.5 });
spawnItem
spawnItem(itemStack: minecraftserver.ItemStack, location: minecraftserver.Vector3): minecraftserver.Entity
Spawns an item entity at a specified location.
Parameters
itemStack: @minecraft/server.ItemStack
ItemStack that describes the item entity to create.
location: @minecraft/server.Vector3
Location to create the item entity at.
Returns @minecraft/server.Entity
Important
This function can't be called in read-only mode.
Examples
spawnEmeralds.js
const oneEmerald = new ItemStack(MinecraftItemTypes.Emerald, 1, 0);
const fiveEmeralds = new ItemStack(MinecraftItemTypes.Emerald, 5, 0);
test.spawnItem(oneEmerald, { x: 3.5, y: 3, z: 1.5 });
test.spawnItem(fiveEmeralds, { x: 1.5, y: 3, z: 1.5 });
spawnSimulatedPlayer
spawnSimulatedPlayer(blockLocation: minecraftserver.Vector3, name?: string, gameMode?: minecraftserver.GameMode): SimulatedPlayer
Creates a new simulated player within the world.
Parameters
blockLocation: @minecraft/server.Vector3
Location where to spawn the simulated player.
name?: string =
"Simulated Player"
Name to give the new simulated player.
gameMode?: @minecraft/server.GameMode =
0
Returns SimulatedPlayer
Important
This function can't be called in read-only mode.
spawnWithoutBehaviors
spawnWithoutBehaviors(entityTypeIdentifier: string, blockLocation: minecraftserver.Vector3): minecraftserver.Entity
Spawns an entity at a location without any AI behaviors. This method is frequently used in conjunction with methods like .walkTo to create predictable mob actions.
Parameters
entityTypeIdentifier: string
blockLocation: @minecraft/server.Vector3
Location where the entity should be spawned.
Returns @minecraft/server.Entity
Important
This function can't be called in read-only mode.
spawnWithoutBehaviorsAtLocation
spawnWithoutBehaviorsAtLocation(entityTypeIdentifier: string, location: minecraftserver.Vector3): minecraftserver.Entity
Spawns an entity at a location without any AI behaviors. This method is frequently used in conjunction with methods like .walkTo to create predictable mob actions.
Parameters
entityTypeIdentifier: string
location: @minecraft/server.Vector3
Location where the entity should be spawned.
Returns @minecraft/server.Entity
Important
This function can't be called in read-only mode.
spreadFromFaceTowardDirection
spreadFromFaceTowardDirection(blockLocation: minecraftserver.Vector3, fromFace: minecraftserver.Direction, direction: minecraftserver.Direction): void
Tests that a particular item entity is present at a particular location. If not, an exception is thrown.
Parameters
blockLocation: @minecraft/server.Vector3
BlockLocation containing a multiface block.
fromFace: @minecraft/server.Direction
Face to spread from. This face must already be set.
direction: @minecraft/server.Direction
Direction to spread. Use the Minecraft.Direction enum to specify a direction.
Important
This function can't be called in read-only mode.
Examples
spreadFromFaceTowardDirection.js
test.spreadFromFaceTowardDirection({ x: 1, y: 2, z: 1 }, Direction.south, Direction.down);
startSequence
startSequence(): GameTestSequence
Creates a new GameTestSequence - A set of steps that play out sequentially within a GameTest.
Returns GameTestSequence - A new GameTestSequence with chaining methods that facilitate creating a set of steps.
Important
This function can't be called in read-only mode.
succeed
succeed(): void
Marks the current test as a success case.
Important
This function can't be called in read-only mode.
Warning
This function can throw errors.
succeedIf
succeedIf(callback: () => void): void
Runs the given callback. If the callback does not throw an exception, the test is marked as a success.
Parameters
callback: () => void
Callback function that runs. If the function runs successfully, the test is marked as a success. Typically, this function will have .assertXyz method calls within it.
Important
This function can't be called in read-only mode.
Warning
This function can throw errors.
succeedOnTick
succeedOnTick(tick: number): void
Marks the test as a success at the specified tick.
Parameters
tick: number
Tick after the start of the GameTest to mark the test as successful.
Important
This function can't be called in read-only mode.
Warning
This function can throw errors.
succeedOnTickWhen
succeedOnTickWhen(tick: number, callback: () => void): void
Runs the given callback at tick ticks after the start of the test. If the callback does not throw an exception, the test is marked as a failure.
Parameters
tick: number
Tick after the start of the GameTest to run the testing callback at.
callback: () => void
Callback function that runs. If the function runs successfully, the test is marked as a success.
Important
This function can't be called in read-only mode.
Warning
This function can throw errors.
succeedWhen
succeedWhen(callback: () => void): void
Runs the given callback every tick. When the callback successfully executes, the test is marked as a success. Specifically, the test will succeed when the callback does not throw an exception.
Parameters
callback: () => void
Testing callback function that runs. If the function runs successfully, the test is marked as a success.
Important
This function can't be called in read-only mode.
Warning
This function can throw errors.
Examples
simpleMobTest.ts
import * as gameTest from '@minecraft/server-gametest';
gameTest
.register('StarterTests', 'simpleMobTest', (test: gameTest.Test) => {
const attackerId = 'fox';
const victimId = 'chicken';
test.spawn(attackerId, { x: 5, y: 2, z: 5 });
test.spawn(victimId, { x: 2, y: 2, z: 2 });
test.assertEntityPresentInArea(victimId, true);
test.succeedWhen(() => {
test.assertEntityPresentInArea(victimId, false);
});
})
.maxTicks(400)
.structureName('gametests:mediumglass');
succeedWhenBlockPresent
succeedWhenBlockPresent(blockType: minecraftserver.BlockType | string, blockLocation: minecraftserver.Vector3, isPresent?: boolean): void
Depending on the condition of isPresent, tests for the presence of a block of a particular type on every tick. When the specified block of a type is found or not found (depending on isPresent), the test is marked as a success.
Parameters
blockType: @minecraft/server.BlockType | string
Type of block to test for.
blockLocation: @minecraft/server.Vector3
Location of the block to test at.
isPresent?: boolean =
true
If true, this function tests whether a block of the specified type is present. If false, tests that a block of the specified type is not present.
Important
This function can't be called in read-only mode.
succeedWhenEntityHasComponent
succeedWhenEntityHasComponent(entityTypeIdentifier: string, componentIdentifier: string, blockLocation: minecraftserver.Vector3, hasComponent: boolean): void
Tests for the presence of a component on every tick. Depending on the value of hasComponent, when the specified component is found, the test is marked as a success.
Parameters
entityTypeIdentifier: string
Type of entity to look for. If no namespace is specified, 'minecraft:' is assumed.
componentIdentifier: string
Type of component to test for the presence of. If no namespace is specified, 'minecraft:' is assumed.
blockLocation: @minecraft/server.Vector3
Block location of the entity to test.
hasComponent: boolean
If true, this function tests for the presence of a component. If false, this function tests for the lack of a component.
Important
This function can't be called in read-only mode.
Warning
This function can throw errors.
succeedWhenEntityPresent
succeedWhenEntityPresent(entityTypeIdentifier: string, blockLocation: minecraftserver.Vector3, isPresent?: boolean): void
Depending on the value of isPresent, tests for the presence of an entity on every tick. When an entity of the specified type is found or not found (depending on isPresent), the test is marked as a success.
Parameters
entityTypeIdentifier: string
Type of entity to test for (e.g., 'minecraft:skeleton'). If an entity namespace is not specified, 'minecraft:' is assumed.
blockLocation: @minecraft/server.Vector3
Location of the entity to test for.
isPresent?: boolean =
true
If true, this function tests whether an entity of the specified type is present. If false, tests that an entity of the specified type is not present.
Important
This function can't be called in read-only mode.
Warning
This function can throw errors.
triggerInternalBlockEvent
triggerInternalBlockEvent(blockLocation: minecraftserver.Vector3, event: string, eventParameters?: number[]): void
Triggers a block event from a fixed list of available block events.
Parameters
blockLocation: @minecraft/server.Vector3
event: string
Event to trigger. Valid values include minecraft:drip, minecraft:grow_stalagtite, minecraft:grow_stalagmite, minecraft:grow_up, minecraft:grow_down and minecraft:grow_sideways.
eventParameters?: number[] =
[]
Important
This function can't be called in read-only mode.
until
until(callback: () => void): Promise<void>
This asynchronous function will wait until the code in the specified callback successfully completes. until can be used in conjunction with .assert functions to evaluate that a condition is true.
Parameters
callback: () => void
Function with code to evaluate.
Returns Promise<void>
Important
This function can't be called in read-only mode.
walkTo
walkTo(mob: minecraftserver.Entity, blockLocation: minecraftserver.Vector3, speedModifier?: number): void
Forces a mob to walk to a particular location. Usually used in conjunction with methods like .spawnWithoutBehaviors to have more predictable mob behaviors. Mobs will stop navigation as soon as they intersect the target location.
Parameters
-
Mob entity to give orders to.
blockLocation: @minecraft/server.Vector3
Location where the entity should be walk to.
speedModifier?: number =
1
Adjustable modifier to the mob's walking speed.
Important
This function can't be called in read-only mode.
walkToLocation
walkToLocation(mob: minecraftserver.Entity, location: minecraftserver.Vector3, speedModifier?: number): void
Forces a mob to walk to a particular location. Usually used in conjunction with methods like .spawnWithoutBehaviors to have more predictable mob behaviors. Mobs will stop navigation as soon as they intersect the target location.
Parameters
-
Mob entity to give orders to.
location: @minecraft/server.Vector3
Location where the entity should be walk to.
speedModifier?: number =
1
Adjustable modifier to the mob's walking speed.
Important
This function can't be called in read-only mode.
worldBlockLocation
worldBlockLocation(relativeBlockLocation: minecraftserver.Vector3): minecraftserver.Vector3
From a BlockLocation with coordinates relative to the GameTest structure block, returns a new BlockLocation with coordinates relative to world. Rotation of the GameTest structure is also taken into account.
Parameters
relativeBlockLocation: @minecraft/server.Vector3
Location relative to the GameTest command block.
Returns @minecraft/server.Vector3 - An absolute location relative to the GameTest command block.
worldLocation
worldLocation(relativeLocation: minecraftserver.Vector3): minecraftserver.Vector3
From a location with coordinates relative to the GameTest structure block, returns a new location with coordinates relative to world. Rotation of the GameTest structure is also taken into account.
Parameters
relativeLocation: @minecraft/server.Vector3
Location relative to the GameTest command block.
Returns @minecraft/server.Vector3 - An absolute location relative to the GameTest command block.
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for