Interface EntityQueryOptions

Contains options for selecting entities within an area.

Example: testBlockConditional.ts

import { Dimension } from '@minecraft/server';

// Having this command:

// execute as @e[type=fox] positioned as @s if block ^ ^-1 ^ stone run summon salmon

// Equivalent scripting code would be:
function spawnFish(dimension: Dimension) {
    dimension
        .getEntities({
            type: 'fox',
        })
        .filter(entity => {
            const block = dimension.getBlock({
                x: entity.location.x,
                y: entity.location.y - 1,
                z: entity.location.z,
            });

            return block !== undefined && block.matches('minecraft:stone');
        })
        .forEach(entity => {
            dimension.spawnEntity('salmon', entity.location);
        });
}

Example: testPlaySoundChained.ts

import { Dimension } from '@minecraft/server';

// Having this command:

// execute as @e[type=armor_stand,name=myArmorStand,tag=dummyTag1,tag=!dummyTag2] run playsound raid.horn @a

// Equivalent scripting code would be:
function playSounds(dimension: Dimension) {
    const targetPlayers = dimension.getPlayers();
    const originEntities = dimension.getEntities({
        type: 'armor_stand',
        name: 'myArmorStand',
        tags: ['dummyTag1'],
        excludeTags: ['dummyTag2'],
    });

    originEntities.forEach(entity => {
        targetPlayers.forEach(player => {
            player.playSound('raid.horn');
        });
    });
}

Example: testPropertyOptionsWithEqualsComparison.ts

import { world, EntityQueryOptions } from '@minecraft/server';

// Having this command:

// execute as @e[has_property={propId=propValue}]

// Equivalent scripting code would be:
function findEntitiesHavingPropertyEqualsTo(propId: string, propValue: boolean | number | string) {
    const queryOption: EntityQueryOptions = {
        propertyOptions: [{ propertyId: propId, value: { equals: propValue } }]
    };

    const overworld = world.getDimension('overworld');
    const entities = overworld.getEntities(queryOption);
}

Example: testPropertyOptionsWithGreaterThanComparison.ts

import { world, EntityQueryOptions } from '@minecraft/server';

// No equivalent commands as `propValue..` is inclusive in commands

function findEntitiesHavingPropertyGreaterThan(propId: string, propValue: number) {
    const queryOption: EntityQueryOptions = {
        propertyOptions: [{ propertyId: propId, value: { greaterThan: propValue } }]
    };

    const overworld = world.getDimension('overworld');
    const entities = overworld.getEntities(queryOption);
}

Example: testPropertyOptionsWithGreaterThanOrEqualsComparison.ts

import { world, EntityQueryOptions } from '@minecraft/server';

// Having this command:

// execute as @e[has_property={propId=propValue..}]

// Equivalent scripting code would be:
function findEntitiesHavingPropertyGreaterThanOrEqualsTo(propId: string, propValue: number) {
    const queryOption: EntityQueryOptions = {
        propertyOptions: [{ propertyId: propId, value: { greaterThanOrEquals: propValue } }]
    };

    const overworld = world.getDimension('overworld');
    const entities = overworld.getEntities(queryOption);
}

Example: testPropertyOptionsWithHavingAProperty.ts

import { world, EntityQueryOptions } from '@minecraft/server';

// Having this command:

// execute as @e[has_property={property=propId}]

// Equivalent scripting code would be:
function findEntitiesHavingAProperty(propId: string) {
    const queryOption: EntityQueryOptions = {
        propertyOptions: [{ propertyId: propId }]
    };

    const overworld = world.getDimension('overworld');
    const entities = overworld.getEntities(queryOption);
}

Example: testPropertyOptionsWithLessThanComparison.ts

import { world, EntityQueryOptions } from '@minecraft/server';

// No equivalent commands as `..propValue` is inclusive in commands

function findEntitiesHavingPropertyLessThan(propId: string, propValue: number) {
    const queryOption: EntityQueryOptions = {
        propertyOptions: [{ propertyId: propId, value: { lessThan: propValue } }]
    };

    const overworld = world.getDimension('overworld');
    const entities = overworld.getEntities(queryOption);
}

Example: testPropertyOptionsWithLessThanOrEqualsComparison.ts

import { world, EntityQueryOptions } from '@minecraft/server';

// Having this command:

// execute as @e[has_property={propId=..propValue}]

// Equivalent scripting code would be:
function findEntitiesHavingPropertyLessThanOrEqualsTo(propId: string, propValue: number) {
    const queryOption: EntityQueryOptions = {
        propertyOptions: [{ propertyId: propId, value: { lessThanOrEquals: propValue } }]
    };

    const overworld = world.getDimension('overworld');
    const entities = overworld.getEntities(queryOption);
}

Example: testPropertyOptionsWithNotEqualsComparison.ts

import { world, EntityQueryOptions } from '@minecraft/server';

// Having this command:

// execute as @e[has_property={propId=!propValue}]

// Equivalent scripting code would be:
function findEntitiesHavingPropertyNotEqualsTo(propId: string, propValue: boolean | number | string) {
    const queryOption: EntityQueryOptions = {
        propertyOptions: [{ propertyId: propId, value: { notEquals: propValue } }]
    };

    const overworld = world.getDimension('overworld');
    const entities = overworld.getEntities(queryOption);
}

Example: testPropertyOptionsWithNotHavingAProperty.ts

import { world, EntityQueryOptions } from '@minecraft/server';

// Having this command:

// execute as @e[has_property={property=!propId}]

// Equivalent scripting code would be:
function findEntitiesNotHavingAProperty(propId: string) {
    const queryOption: EntityQueryOptions = {
        propertyOptions: [{ propertyId: propId, exclude: true }]
    };

    const overworld = world.getDimension('overworld');
    const entities = overworld.getEntities(queryOption);
}

Example: testPropertyOptionsWithRangeComparison.ts

import { world, EntityQueryOptions } from '@minecraft/server';

// Having this command:

// execute as @e[has_property={propId=lowerBoundValue..upperBoundValue}]

// Equivalent scripting code would be:
function findEntitiesHavingPropertyWithinRange(propId: string, lowerBoundValue: number, upperBoundValue: number) {
    const queryOption: EntityQueryOptions = {
        propertyOptions: [{ propertyId: propId, value: { lowerBound: lowerBoundValue, upperBound: upperBoundValue } }]
    };

    const overworld = world.getDimension('overworld');
    const entities = overworld.getEntities(queryOption);
}

Example: testSendMessageAllPlayers.ts

import { Dimension } from '@minecraft/server';

// Having this command:

// execute as @e[type=armor_stand,name=myArmorStand,tag=dummyTag1,tag=!dummyTag2] run tellraw @a { "rawtext": [{"translate": "hello.world" }] }

// Equivalent scripting code would be:
function sendMessagesToPlayers(dimension: Dimension) {
    const targetPlayers = dimension.getPlayers();
    const originEntities = dimension.getEntities({
        type: 'armor_stand',
        name: 'myArmorStand',
        tags: ['dummyTag1'],
        excludeTags: ['dummyTag2'],
    });

    originEntities.forEach(entity => {
        targetPlayers.forEach(player => {
            player.sendMessage({ rawtext: [{ translate: 'hello.world' }] });
        });
    });
}

Example: testSetScoreBoardChained.ts

import { Dimension, world } from '@minecraft/server';

// Having these commands:

// scoreboard objectives add scoreObjective1 dummy
// scoreboard players set @e[type=armor_stand,name=myArmorStand] scoreObjective1 -1

// Equivalent scripting code would be:
function setScores(dimension: Dimension) {
    const objective = world.scoreboard.addObjective('scoreObjective1', 'dummy');
    dimension
        .getEntities({
            type: 'armor_stand',
            name: 'myArmorStand',
        })
        .forEach(entity => {
            if (entity.scoreboardIdentity !== undefined) {
                objective.setScore(entity.scoreboardIdentity, -1);
            }
        });
}

Example: testSummonMobChained.ts

import { Dimension } from '@minecraft/server';

// Having this command:

// execute as @e[type=armor_stand] run execute as @a[x=0,y=-60,z=0,c=4,r=15] run summon pig ~1 ~ ~

// Equivalent scripting code would be:
function spawnPigs(dimension: Dimension) {
    const armorStandArray = dimension.getEntities({
        type: 'armor_stand',
    });
    const playerArray = dimension.getPlayers({
        location: { x: 0, y: -60, z: 0 },
        closest: 4,
        maxDistance: 15,
    });
    armorStandArray.forEach(entity => {
        playerArray.forEach(player => {
            dimension.spawnEntity('pig', {
                x: player.location.x + 1,
                y: player.location.y,
                z: player.location.z,
            });
        });
    });
}
interface EntityQueryOptions {
    closest?: number;
    excludeFamilies?: string[];
    excludeGameModes?: GameMode[];
    excludeNames?: string[];
    excludeTags?: string[];
    excludeTypes?: string[];
    families?: string[];
    farthest?: number;
    gameMode?: GameMode;
    location?: Vector3;
    maxDistance?: number;
    maxHorizontalRotation?: number;
    maxLevel?: number;
    maxVerticalRotation?: number;
    minDistance?: number;
    minHorizontalRotation?: number;
    minLevel?: number;
    minVerticalRotation?: number;
    name?: string;
    propertyOptions?: EntityQueryPropertyOptions[];
    scoreOptions?: EntityQueryScoreOptions[];
    tags?: string[];
    type?: string;
    volume?: Vector3;
}

Hierarchy (View Summary)

Properties

closest? excludeFamilies? excludeGameModes? excludeNames? excludeTags? excludeTypes? families? farthest? gameMode? location? maxDistance? maxHorizontalRotation? maxLevel? maxVerticalRotation? minDistance? minHorizontalRotation? minLevel? minVerticalRotation? name? propertyOptions? scoreOptions? tags? type? volume?

Properties

Optionalclosest

closest?: number

Remarks

Limits the number of entities to return, opting for the closest N entities as specified by this property. The location value must also be specified on the query options object.

OptionalexcludeFamilies

excludeFamilies?: string[]

Remarks

Excludes entities that match one or more of the specified families.

OptionalexcludeGameModes

excludeGameModes?: GameMode[]

Remarks

Excludes entities if have a specific gamemode that matches the specified gamemode.

OptionalexcludeNames

excludeNames?: string[]

Remarks

Excludes entities that have a name that match one of the specified values.

OptionalexcludeTags

excludeTags?: string[]

Remarks

Excludes entities with a tag that matches one of the specified values.

OptionalexcludeTypes

excludeTypes?: string[]

Remarks

Excludes entities if they are one of the specified types.

Optionalfamilies

families?: string[]

Remarks

If specified, includes entities that match all of the specified families.

Optionalfarthest

farthest?: number

Remarks

Limits the number of entities to return, opting for the farthest N entities as specified by this property. The location value must also be specified on the query options object.

OptionalgameMode

gameMode?: GameMode

Remarks

If specified, includes entities with a gamemode that matches the specified gamemode.

Optionallocation

location?: Vector3

Remarks

Adds a seed location to the query that is used in conjunction with closest, farthest, limit, volume, and distance properties.

OptionalmaxDistance

maxDistance?: number

Remarks

If specified, includes entities that are less than this distance away from the location specified in the location property.

OptionalmaxHorizontalRotation

maxHorizontalRotation?: number

Remarks

If specified, will only include entities that have at most this horizontal rotation.

OptionalmaxLevel

maxLevel?: number

Remarks

If defined, only players that have at most this level are returned.

OptionalmaxVerticalRotation

maxVerticalRotation?: number

Remarks

If specified, only entities that have at most this vertical rotation are returned.

OptionalminDistance

minDistance?: number

Remarks

If specified, includes entities that are least this distance away from the location specified in the location property.

OptionalminHorizontalRotation

minHorizontalRotation?: number

Remarks

If specified, will only include entities that have at a minimum this horizontal rotation.

OptionalminLevel

minLevel?: number

Remarks

If defined, only players that have at least this level are returned.

OptionalminVerticalRotation

minVerticalRotation?: number

Remarks

If specified, will only include entities that have at least this vertical rotation.

Optionalname

name?: string

Remarks

Includes entities with the specified name.

Optional BetapropertyOptions

propertyOptions?: EntityQueryPropertyOptions[]

OptionalscoreOptions

scoreOptions?: EntityQueryScoreOptions[]

Remarks

Gets/sets a collection of EntityQueryScoreOptions objects with filters for specific scoreboard objectives.

Optionaltags

tags?: string[]

Remarks

Includes entities that match all of the specified tags.

Optionaltype

type?: string

Remarks

If defined, entities that match this type are included.

Optionalvolume

volume?: Vector3

Remarks

In conjunction with location, specified a cuboid volume of entities to include.

Settings

Member Visibility

On This Page

Properties