Edit

Share via

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

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.

Notes:

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.

Notes:

assertBlockState

assertBlockState(blockLocation: minecraftserver.Vector3, callback: (arg0: 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

Notes:

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

  • mob: @minecraft/server.Entity

    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.

Notes:

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.

Notes:

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.

Notes:

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.

Notes:

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.

Notes:

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.

Notes:

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.

Notes:

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');

(preview) Work with this sample on the MCTools.dev code sandbox.

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.

Notes:

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.

Notes:

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');

(preview) Work with this sample on the MCTools.dev code sandbox.

simpleMobGameTest.ts
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function simpleMobGameTest(test: Test) {
  const attackerId = MinecraftEntityTypes.Fox;
  const victimId = MinecraftEntityTypes.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);
  });
}
register("StarterTests", "simpleMobTest", simpleMobGameTest).maxTicks(400).structureName("gametests:mediumglass");

(preview) Work with this sample on the MCTools.dev code sandbox.

assertEntityState

assertEntityState(blockLocation: minecraftserver.Vector3, entityTypeIdentifier: string, callback: (arg0: 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: (arg0: @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.

Notes:

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.

Notes:

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.

Notes:

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.

Notes:

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.

Notes:

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

Notes:

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.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

fail

fail(errorMessage: string): void

Marks the current test as a failure case.

Parameters

  • errorMessage: string

    Error message summarizing the failure condition.

Notes:

  • 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.

Notes:

  • This function can throw errors.

getBlock

getBlock(blockLocation: minecraftserver.Vector3): minecraftserver.Block

Gets a block at the specified block location.

Parameters

Returns @minecraft/server.Block

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

getDimension

getDimension(): minecraftserver.Dimension

Gets the dimension of this test.

Returns @minecraft/server.Dimension

Notes:

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

Returns FenceConnectivity

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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

Returns SculkSpreader | undefined - Returns the SculkSpreader or undefined if no SculkSpreader is present on the block.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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>

Notes:

  • This function can't be called in read-only mode.

killAllEntities

killAllEntities(): void

Kills all entities within the GameTest structure.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

onPlayerJump

onPlayerJump(mob: minecraftserver.Entity, jumpAmount: number): void

Parameters

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

pressButton

pressButton(blockLocation: minecraftserver.Vector3): void

Presses a button at a block location.

Parameters

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

print

print(text: string): void

Displays the specified message to all players.

Parameters

  • text: string

    Message to display.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

pullLever

pullLever(blockLocation: minecraftserver.Vector3): void

Pulls a lever at a block location.

Parameters

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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

Returns @minecraft/server.Vector3 - A location relative to the GameTest command block.

Notes:

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

Returns @minecraft/server.Vector3 - A location relative to the GameTest command block.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

removeSimulatedPlayer

removeSimulatedPlayer(simulatedPlayer: SimulatedPlayer): void

Removes a simulated player from the world.

Parameters

Notes:

  • 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

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

rotateVector

rotateVector(vector: minecraftserver.Vector3): minecraftserver.Vector3

Parameters

Returns @minecraft/server.Vector3

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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.

Notes:

  • This function can't be called in read-only mode.
  • 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.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

runOnFinish

runOnFinish(callback: () => void): void

Runs the given callback after the GameTest has completed regardless if the test passed, failed, or timed out.

Parameters

  • callback: () => void

    Callback to execute.

Notes:

  • This function can't be called in read-only mode.
  • 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

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

setBlockType

setBlockType(blockType: minecraftserver.BlockType | string, blockLocation: minecraftserver.Vector3): void

Sets a block to a particular type at the specified block location.

Parameters

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

Examples

minibiomes.ts
import { EntityComponentTypes } from "@minecraft/server";
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftBlockTypes, MinecraftEntityTypes } from "@minecraft/vanilla-data";

function minibiomes(test: Test) {
  const minecart = test.spawn(MinecraftEntityTypes.Minecart, { x: 9, y: 7, z: 7 });
  const pig = test.spawn(MinecraftEntityTypes.Pig, { x: 9, y: 7, z: 7 });

  test.setBlockType(MinecraftBlockTypes.Cobblestone, { x: 10, y: 7, z: 7 });

  const minecartRideableComp = minecart.getComponent(EntityComponentTypes.Rideable);

  minecartRideableComp?.addRider(pig);

  test.succeedWhenEntityPresent(MinecraftEntityTypes.Pig, { x: 8, y: 3, z: 1 }, true);
}
register("ChallengeTests", "minibiomes", minibiomes).structureName("gametests:minibiomes").maxTicks(160);

(preview) Work with this sample on the MCTools.dev code sandbox.

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

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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<spawnEvent>).

  • blockLocation: @minecraft/server.Vector3

Returns @minecraft/server.Entity - The spawned entity. If the entity cannot be spawned, returns undefined.

Notes:

  • This function can't be called in read-only mode.
  • 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');

(preview) Work with this sample on the MCTools.dev code sandbox.

simpleMobGameTest.ts
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function simpleMobGameTest(test: Test) {
  const attackerId = MinecraftEntityTypes.Fox;
  const victimId = MinecraftEntityTypes.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);
  });
}
register("StarterTests", "simpleMobTest", simpleMobGameTest).maxTicks(400).structureName("gametests:mediumglass");

(preview) Work with this sample on the MCTools.dev code sandbox.

phantomsShouldFlyFromCats.ts
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function phantomsShouldFlyFromCats(test: Test) {
  test.spawn(MinecraftEntityTypes.Cat, { x: 4, y: 3, z: 3 });
  test.spawn(MinecraftEntityTypes.Phantom, { x: 4, y: 3, z: 3 });

  test.succeedWhenEntityPresent(MinecraftEntityTypes.Phantom, { x: 4, y: 6, z: 3 }, true);
}

register("MobBehaviorTests", "phantoms_should_fly_from_cats", phantomsShouldFlyFromCats)
  .structureName("gametests:glass_cells");

(preview) Work with this sample on the MCTools.dev code sandbox.

minibiomes.ts
import { EntityComponentTypes } from "@minecraft/server";
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftBlockTypes, MinecraftEntityTypes } from "@minecraft/vanilla-data";

function minibiomes(test: Test) {
  const minecart = test.spawn(MinecraftEntityTypes.Minecart, { x: 9, y: 7, z: 7 });
  const pig = test.spawn(MinecraftEntityTypes.Pig, { x: 9, y: 7, z: 7 });

  test.setBlockType(MinecraftBlockTypes.Cobblestone, { x: 10, y: 7, z: 7 });

  const minecartRideableComp = minecart.getComponent(EntityComponentTypes.Rideable);

  minecartRideableComp?.addRider(pig);

  test.succeedWhenEntityPresent(MinecraftEntityTypes.Pig, { x: 8, y: 3, z: 1 }, true);
}
register("ChallengeTests", "minibiomes", minibiomes).structureName("gametests:minibiomes").maxTicks(160);

(preview) Work with this sample on the MCTools.dev code sandbox.

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<spawnEvent>).

  • location: @minecraft/server.Vector3

Returns @minecraft/server.Entity - The spawned entity. If the entity cannot be spawned, returns undefined.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

spawnItem

spawnItem(itemStack: minecraftserver.ItemStack, location: minecraftserver.Vector3): minecraftserver.Entity

Spawns an item entity at a specified location.

Parameters

Returns @minecraft/server.Entity

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

spawnSimulatedPlayer

spawnSimulatedPlayer(blockLocation: minecraftserver.Vector3, name?: string, gameMode?: minecraftserver.GameMode): SimulatedPlayer

Creates a new simulated player within the world.

Parameters

Returns SimulatedPlayer

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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

Returns @minecraft/server.Entity

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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

Returns @minecraft/server.Entity

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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.

Notes:

  • This function can't be called in read-only mode.

succeed

succeed(): void

Marks the current test as a success case.

Notes:

  • This function can't be called in read-only mode.
  • 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.

Notes:

  • This function can't be called in read-only mode.
  • 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.

Notes:

  • This function can't be called in read-only mode.
  • 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.

Notes:

  • This function can't be called in read-only mode.
  • 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.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

Examples

simpleMobGameTest.ts
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function simpleMobGameTest(test: Test) {
  const attackerId = MinecraftEntityTypes.Fox;
  const victimId = MinecraftEntityTypes.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);
  });
}
register("StarterTests", "simpleMobTest", simpleMobGameTest).maxTicks(400).structureName("gametests:mediumglass");

(preview) Work with this sample on the MCTools.dev code sandbox.

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.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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.

Notes:

  • This function can't be called in read-only mode.
  • 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.

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

Examples

phantomsShouldFlyFromCats.ts
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftEntityTypes } from "@minecraft/vanilla-data";

function phantomsShouldFlyFromCats(test: Test) {
  test.spawn(MinecraftEntityTypes.Cat, { x: 4, y: 3, z: 3 });
  test.spawn(MinecraftEntityTypes.Phantom, { x: 4, y: 3, z: 3 });

  test.succeedWhenEntityPresent(MinecraftEntityTypes.Phantom, { x: 4, y: 6, z: 3 }, true);
}

register("MobBehaviorTests", "phantoms_should_fly_from_cats", phantomsShouldFlyFromCats)
  .structureName("gametests:glass_cells");

(preview) Work with this sample on the MCTools.dev code sandbox.

minibiomes.ts
import { EntityComponentTypes } from "@minecraft/server";
import { Test, register } from "@minecraft/server-gametest";
import { MinecraftBlockTypes, MinecraftEntityTypes } from "@minecraft/vanilla-data";

function minibiomes(test: Test) {
  const minecart = test.spawn(MinecraftEntityTypes.Minecart, { x: 9, y: 7, z: 7 });
  const pig = test.spawn(MinecraftEntityTypes.Pig, { x: 9, y: 7, z: 7 });

  test.setBlockType(MinecraftBlockTypes.Cobblestone, { x: 10, y: 7, z: 7 });

  const minecartRideableComp = minecart.getComponent(EntityComponentTypes.Rideable);

  minecartRideableComp?.addRider(pig);

  test.succeedWhenEntityPresent(MinecraftEntityTypes.Pig, { x: 8, y: 3, z: 1 }, true);
}
register("ChallengeTests", "minibiomes", minibiomes).structureName("gametests:minibiomes").maxTicks(160);

(preview) Work with this sample on the MCTools.dev code sandbox.

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[] = []

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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>

Notes:

  • 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

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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

Notes:

  • This function can't be called in read-only mode.
  • This function can throw errors.

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

Returns @minecraft/server.Vector3 - An absolute location relative to the GameTest command block.

Notes:

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

Returns @minecraft/server.Vector3 - An absolute location relative to the GameTest command block.

Notes: