跳到主要内容

Class: Player

Represents a player within the world.

Extends​

Constructors​

new Player()​

private new Player(): Player

Returns​

Player

Overrides​

Entity . constructor

Properties​

camera​

readonly camera: Camera

Remarks​

The player's Camera.

Throws​

This property can throw when used.

dimension​

readonly dimension: Dimension

Remarks​

Dimension that the entity is currently within.

Throws​

This property can throw when used.

Inherited from​

Entity . dimension

fallDistance​

Beta

readonly fallDistance: number

Remarks​

The distance an entity has fallen. The value is reset when the entity is teleported. The value is always 1 when gliding with Elytra.

Throws​

This property can throw when used.

Inherited from​

Entity . fallDistance

id​

readonly id: string

Remarks​

Unique identifier of the entity. This identifier is intended to be consistent across loads of a world instance. No meaning should be inferred from the value and structure of this unique identifier - do not parse or interpret it. This property is accessible even if Entity.isValid is false.

Inherited from​

Entity . id

inputPermissions​

Beta

readonly inputPermissions: PlayerInputPermissions

Remarks​

Input permissions of the player.

isClimbing​

readonly isClimbing: boolean

Remarks​

Whether the entity is touching a climbable block. For example, a player next to a ladder or a spider next to a stone wall.

Throws​

This property can throw when used.

Inherited from​

Entity . isClimbing

isEmoting​

readonly isEmoting: boolean

Remarks​

If true, the player is currently emoting.

Throws​

This property can throw when used.

isFalling​

readonly isFalling: boolean

Remarks​

Whether the entity has a fall distance greater than 0, or greater than 1 while gliding.

Throws​

This property can throw when used.

Inherited from​

Entity . isFalling

isFlying​

readonly isFlying: boolean

Remarks​

Whether the player is flying. For example, in Creative or Spectator mode.

Throws​

This property can throw when used.

isGliding​

readonly isGliding: boolean

Remarks​

Whether the player is gliding with Elytra.

Throws​

This property can throw when used.

isInWater​

readonly isInWater: boolean

Remarks​

Whether any part of the entity is inside a water block.

Throws​

This property can throw when used.

Inherited from​

Entity . isInWater

isJumping​

readonly isJumping: boolean

Remarks​

Whether the player is jumping. This will remain true while the player is holding the jump action.

Throws​

This property can throw when used.

isOnGround​

readonly isOnGround: boolean

Remarks​

Whether the entity is on top of a solid block. This property may behave in unexpected ways. This property will always be true when an Entity is first spawned, and if the Entity has no gravity this property may be incorrect.

Throws​

This property can throw when used.

Inherited from​

Entity . isOnGround

isSleeping​

readonly isSleeping: boolean

Remarks​

If true, the entity is currently sleeping.

Throws​

This property can throw when used.

Inherited from​

Entity . isSleeping

isSneaking​

isSneaking: boolean

Remarks​

Whether the entity is sneaking - that is, moving more slowly and more quietly.

This property can't be edited in read-only mode.

Inherited from​

Entity . isSneaking

isSprinting​

readonly isSprinting: boolean

Remarks​

Whether the entity is sprinting. For example, a player using the sprint action, an ocelot running away or a pig boosting with Carrot on a Stick.

Throws​

This property can throw when used.

Inherited from​

Entity . isSprinting

isSwimming​

readonly isSwimming: boolean

Remarks​

Whether the entity is in the swimming state. For example, a player using the swim action or a fish in water.

Throws​

This property can throw when used.

Inherited from​

Entity . isSwimming

level​

readonly level: number

Remarks​

The current overall level for the player, based on their experience.

Throws​

This property can throw when used.

lifetimeState​

Beta

readonly lifetimeState: EntityLifetimeState

Remarks​

Whether the entity reference that you have is valid or not. For example, an entity may be unloaded if it moves into a chunk that is unloaded, but may be reactivated if the chunk it is within gets reloaded.

Inherited from​

Entity . lifetimeState

location​

readonly location: Vector3

Remarks​

Current location of the entity.

Throws​

This property can throw when used.

Inherited from​

Entity . location

name​

readonly name: string

Remarks​

Name of the player.

Throws​

This property can throw when used.

nameTag​

nameTag: string

Remarks​

Given name of the entity.

This property can't be edited in read-only mode.

Inherited from​

Entity . nameTag

onScreenDisplay​

readonly onScreenDisplay: ScreenDisplay

Remarks​

Contains methods for manipulating the on-screen display of a Player.

Throws​

This property can throw when used.

scoreboardIdentity?​

optional readonly scoreboardIdentity: ScoreboardIdentity

Remarks​

Returns a scoreboard identity that represents this entity. Will remain valid when the entity is killed.

Inherited from​

Entity . scoreboardIdentity

selectedSlotIndex​

Beta

selectedSlotIndex: number

Remarks​

This property can't be edited in read-only mode.

target?​

Beta

optional readonly target: Entity

Remarks​

Retrieves or sets an entity that is used as the target of AI-related behaviors, like attacking. If the entity currently has no target returns undefined.

Throws​

This property can throw when used.

Inherited from​

Entity . target

totalXpNeededForNextLevel​

readonly totalXpNeededForNextLevel: number

Remarks​

The overall total set of experience needed to achieve the next level for a player.

Throws​

This property can throw when used.

typeId​

readonly typeId: string

Remarks​

Identifier of the type of the entity - for example, 'minecraft:skeleton'. This property is accessible even if Entity.isValid is false.

Inherited from​

Entity . typeId

xpEarnedAtCurrentLevel​

readonly xpEarnedAtCurrentLevel: number

Remarks​

The current set of experience achieved for the player.

Throws​

This property can throw when used.

Methods​

addEffect()​

addEffect(effectType, duration, options?): Effect

Parameters​

ParameterTypeDescription
effectTypestring | EffectTypeType of effect to add to the entity.
durationnumberAmount of time, in ticks, for the effect to apply. There are
20 ticks per second. Use TicksPerSecond constant to
convert between ticks and seconds. The value must be within
the range [0, 20000000].
options?EntityEffectOptionsAdditional options for the effect.

Returns​

Effect

Returns nothing if the effect was added or updated successfully. This can throw an error if the duration or amplifier are outside of the valid ranges, or if the effect does not exist.

Inherited from​

Entity . addEffect

Remarks​

Adds or updates an effect, like poison, to the entity.

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

Throws​

This function can throw errors.

Examples​

// Spawns a villager and gives it the poison effect
import {
    DimensionLocation,
} from '@minecraft/server';
import { MinecraftEffectTypes } from '@minecraft/vanilla-data';

function spawnPoisonedVillager(location: DimensionLocation) {
    const villagerType = 'minecraft:villager_v2<minecraft:ageable_grow_up>';
    const villager = location.dimension.spawnEntity(villagerType, location);
    const duration = 20;

    villager.addEffect(MinecraftEffectTypes.Poison, duration, { amplifier: 1 });
}

// Spawns a fox over a dog
import { DimensionLocation } from '@minecraft/server';
import { MinecraftEntityTypes } from '@minecraft/vanilla-data';

function spawnAdultHorse(location: DimensionLocation) {
    // Create fox (our quick brown fox)
    const fox = location.dimension.spawnEntity(MinecraftEntityTypes.Fox, {
        x: location.x,
        y: location.y + 2,
        z: location.z,
    });

    fox.addEffect('speed', 10, {
        amplifier: 2,
    });

    // Create wolf (our lazy dog)
    const wolf = location.dimension.spawnEntity(MinecraftEntityTypes.Wolf, location);
    wolf.addEffect('slowness', 10, {
        amplifier: 2,
    });
    wolf.isSneaking = true;
}

addExperience()​

addExperience(amount): number

Parameters​

ParameterTypeDescription
amountnumberAmount of experience to add. Note that this can be negative.
Min/max bounds at -2^24 ~ 2^24

Returns​

number

Returns the current experience of the Player.

Remarks​

Adds/removes experience to/from the Player and returns the current experience of the Player.

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

Throws​

This function can throw errors.

addLevels()​

addLevels(amount): number

Parameters​

ParameterTypeDescription
amountnumberAmount to add to the player. Min/max bounds at -2^24 ~ 2^24

Returns​

number

Returns the current level of the Player.

Remarks​

Adds/removes level to/from the Player and returns the current level of the Player.

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

Throws​

This function can throw errors.

addTag()​

addTag(tag): boolean

Parameters​

ParameterTypeDescription
tagstringContent of the tag to add. The tag must be less than 256
characters.

Returns​

boolean

Returns true if the tag was added successfully. This can fail if the tag already exists on the entity.

Inherited from​

Entity . addTag

Remarks​

Adds a specified tag to an entity.

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

Throws​

This function can throw errors.

applyDamage()​

applyDamage(amount, options?): boolean

Parameters​

ParameterTypeDescription
amountnumberAmount of damage to apply.
options?EntityApplyDamageByProjectileOptions | EntityApplyDamageOptionsAdditional options about the source of damage, which may add
additional effects or spur additional behaviors on this
entity.

Returns​

boolean

Whether the entity takes any damage. This can return false if the entity is invulnerable or if the damage applied is less than or equal to 0.

Inherited from​

Entity . applyDamage

Remarks​

Applies a set of damage to an entity.

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

Throws​

This function can throw errors.

Example​

// A function that applies damage and then heals the entity
import { Entity, EntityComponentTypes, system, world } from '@minecraft/server';

function applyDamageAndHeal(entity: Entity) {
    entity.applyDamage(19); // Many mobs have max damage of 20 so this is a near-death mob

    system.runTimeout(() => {
        const health = entity.getComponent(EntityComponentTypes.Health);
        if (health) {
            world.sendMessage(`Entity health before heal: ${health.currentValue}`);

            health.resetToMaxValue();

            world.sendMessage(`Entity after before heal: ${health.currentValue}`);
        } else {
            console.warn('Entity does not have health component');
        }
    }, 40); // Run in a few seconds (40 ticks)
}

applyImpulse()​

applyImpulse(vector): void

Parameters​

ParameterTypeDescription
vectorVector3Impulse vector.

Returns​

void

Inherited from​

Entity . applyImpulse

Remarks​

Applies impulse vector to the current velocity of the entity.

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

Throws​

This function can throw errors.

Example​

// A function that throws entities up in the air
import { Entity } from '@minecraft/server';

function yeetEntity(entity: Entity) {

    // Zero out the entity's velocity before applying impulse
    entity.clearVelocity();

    // throw the zombie up in the air
    entity.applyImpulse({ x: 0, y: 15, z: 0 });
}

applyKnockback()​

applyKnockback(directionX, directionZ, horizontalStrength, verticalStrength): void

Parameters​

ParameterTypeDescription
directionXnumberX direction in horizontal plane.
directionZnumberZ direction in horizontal plane.
horizontalStrengthnumberKnockback strength for the horizontal vector.
verticalStrengthnumberKnockback strength for the vertical vector.

Returns​

void

Inherited from​

Entity . applyKnockback

Remarks​

Applies impulse vector to the current velocity of the entity.

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

Throws​

This function can throw errors.

Example​

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

function mobParty(targetLocation: DimensionLocation) {
    const mobs = ['creeper', 'skeleton', 'sheep'];

    // create some sample mob data
    for (let i = 0; i < 10; i++) {
        targetLocation.dimension.spawnEntity(mobs[i % mobs.length], targetLocation);
    }

    const eqo: EntityQueryOptions = {
        type: 'skeleton',
    };

    for (const entity of targetLocation.dimension.getEntities(eqo)) {
        entity.applyKnockback(0, 0, 0, 1);
    }
}

clearDynamicProperties()​

clearDynamicProperties(): void

Returns​

void

Inherited from​

Entity . clearDynamicProperties

Remarks​

Clears all dynamic properties that have been set on this entity.

Throws​

This function can throw errors.

clearVelocity()​

clearVelocity(): void

Returns​

void

Inherited from​

Entity . clearVelocity

Remarks​

Sets the current velocity of the Entity to zero. Note that this method may not have an impact on Players.

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

Throws​

This function can throw errors.

Example​

// A function that throws entities up in the air
import { Entity } from '@minecraft/server';

function yeetEntity(entity: Entity) {

    // Zero out the entity's velocity before applying impulse
    entity.clearVelocity();

    // throw the zombie up in the air
    entity.applyImpulse({ x: 0, y: 15, z: 0 });
}

eatItem()​

Beta

eatItem(itemStack): void

Parameters​

ParameterTypeDescription
itemStackItemStackThe item to eat.

Returns​

void

Remarks​

Eats an item, providing the item's hunger and saturation effects to the player. Can only be used on food items.

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

Throws​

Throws if the item is not a food item.

extinguishFire()​

extinguishFire(useEffects?): boolean

Parameters​

ParameterTypeDescription
useEffects?booleanWhether to show any visual effects connected to the
extinguishing.

Returns​

boolean

Returns whether the entity was on fire.

Inherited from​

Entity . extinguishFire

Remarks​

Extinguishes the fire if the entity is on fire. Note that you can call getComponent('minecraft:onfire') and, if present, the entity is on fire.

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

Throws​

This function can throw errors.

Example​

import { world, Entity, EntityComponentTypes, system } from "@minecraft/server";

function setAblaze(entity: Entity) {
    entity.setOnFire(20, true);

    system.runTimeout(() => {
        const onfire = entity.getComponent(EntityComponentTypes.OnFire);
        if (onfire) {
            world.sendMessage(`${onfire.onFireTicksRemaining} fire ticks remaining, extinguishing the entity.`);
        }
        // This will extinguish the entity
        entity.extinguishFire(true);
    }, 30); // Run in 30 ticks or ~1.5 seconds

}

getBlockFromViewDirection()​

getBlockFromViewDirection(options?): BlockRaycastHit

Parameters​

ParameterTypeDescription
options?BlockRaycastOptionsAdditional configuration options for the ray cast.

Returns​

BlockRaycastHit

Returns the first intersecting block from the direction that this entity is looking at.

Inherited from​

Entity . getBlockFromViewDirection

Remarks​

Returns the first intersecting block from the direction that this entity is looking at.

Throws​

This function can throw errors.

getComponent()​

getComponent<T>(componentId): EntityComponentTypeMap[T]

Type parameters​

Type parameter
T extends keyof EntityComponentTypeMap

Parameters​

ParameterTypeDescription
componentIdTThe identifier of the component (e.g., 'minecraft:health').
If no namespace prefix is specified, 'minecraft:' is
assumed. Available component IDs can be found as part of the
EntityComponentTypes enum.

Returns​

EntityComponentTypeMap[T]

Returns the component if it exists on the entity, otherwise undefined.

Inherited from​

Entity . getComponent

Remarks​

Gets a component (that represents additional capabilities) for an entity.

getComponents()​

getComponents(): EntityComponent[]

Returns​

EntityComponent[]

Returns all components that are both present on this entity and supported by the API.

Inherited from​

Entity . getComponents

Remarks​

Returns all components that are both present on this entity and supported by the API.

getDynamicProperty()​

getDynamicProperty(identifier): string | number | boolean | Vector3

Parameters​

ParameterTypeDescription
identifierstringThe property identifier.

Returns​

string | number | boolean | Vector3

Returns the value for the property, or undefined if the property has not been set.

Inherited from​

Entity . getDynamicProperty

Remarks​

Returns a property value.

Throws​

This function can throw errors.

getDynamicPropertyIds()​

getDynamicPropertyIds(): string[]

Returns​

string[]

A string array of the dynamic properties set on this entity.

Inherited from​

Entity . getDynamicPropertyIds

Remarks​

Returns the available set of dynamic property identifiers that have been used on this entity.

Throws​

This function can throw errors.

getDynamicPropertyTotalByteCount()​

getDynamicPropertyTotalByteCount(): number

Returns​

number

Inherited from​

Entity . getDynamicPropertyTotalByteCount

Remarks​

Returns the total size, in bytes, of all the dynamic properties that are currently stored for this entity. This includes the size of both the key and the value. This can be useful for diagnosing performance warning signs - if, for example, an entity has many megabytes of associated dynamic properties, it may be slow to load on various devices.

Throws​

This function can throw errors.

getEffect()​

getEffect(effectType): Effect

Parameters​

ParameterTypeDescription
effectTypestring | EffectTypeThe effect identifier.

Returns​

Effect

Effect object for the specified effect, undefined if the effect is not present, or throws an error if the effect does not exist.

Inherited from​

Entity . getEffect

Remarks​

Returns the effect for the specified EffectType on the entity, undefined if the effect is not present, or throws an error if the effect does not exist.

Throws​

This function can throw errors.

getEffects()​

getEffects(): Effect[]

Returns​

Effect[]

List of effects.

Inherited from​

Entity . getEffects

Remarks​

Returns a set of effects applied to this entity.

Throws​

This function can throw errors.

getEntitiesFromViewDirection()​

getEntitiesFromViewDirection(options?): EntityRaycastHit[]

Parameters​

ParameterTypeDescription
options?EntityRaycastOptionsAdditional configuration options for the ray cast.

Returns​

EntityRaycastHit[]

Returns a set of entities from the direction that this entity is looking at.

Inherited from​

Entity . getEntitiesFromViewDirection

Remarks​

Gets the entities that this entity is looking at by performing a ray cast from the view of this entity.

Throws​

This function can throw errors.

getGameMode()​

Beta

getGameMode(): GameMode

Returns​

GameMode

Throws​

This function can throw errors.

getHeadLocation()​

getHeadLocation(): Vector3

Returns​

Vector3

Returns the current location of the head component of this entity.

Inherited from​

Entity . getHeadLocation

Remarks​

Returns the current location of the head component of this entity.

Throws​

This function can throw errors.

getItemCooldown()​

Beta

getItemCooldown(cooldownCategory): number

Parameters​

ParameterTypeDescription
cooldownCategorystringSpecifies the cooldown category to retrieve the current
cooldown for.

Returns​

number

Remarks​

Gets the current item cooldown time for a particular cooldown category.

Throws​

This function can throw errors.

getProperty()​

getProperty(identifier): string | number | boolean

Parameters​

ParameterTypeDescription
identifierstringThe entity Property identifier.

Returns​

string | number | boolean

Returns the current property value. For enum properties, a string is returned. For float and int properties, a number is returned. For undefined properties, undefined is returned.

Inherited from​

Entity . getProperty

Remarks​

Gets an entity Property value. If the property was set using the setProperty function within the same tick, the updated value will not be reflected until the subsequent tick.

Throws​

Throws if the entity is invalid.

getRotation()​

getRotation(): Vector2

Returns​

Vector2

Returns a Vec2 containing the rotation of this entity (in degrees).

Inherited from​

Entity . getRotation

Remarks​

Returns the current rotation component of this entity.

Throws​

This function can throw errors.

getSpawnPoint()​

getSpawnPoint(): DimensionLocation

Returns​

DimensionLocation

Remarks​

Gets the current spawn point of the player.

Throws​

This function can throw errors.

getTags()​

getTags(): string[]

Returns​

string[]

An array containing all tags as strings.

Inherited from​

Entity . getTags

Remarks​

Returns all tags associated with the entity.

Throws​

This function can throw errors.

getTotalXp()​

getTotalXp(): number

Returns​

number

Remarks​

Gets the total experience of the Player.

Throws​

This function can throw errors.

getVelocity()​

getVelocity(): Vector3

Returns​

Vector3

Returns the current velocity vector of the entity.

Inherited from​

Entity . getVelocity

Remarks​

Returns the current velocity vector of the entity.

Throws​

This function can throw errors.

Example​

// A function that spawns fireworks and logs their velocity after 5 ticks
import { DimensionLocation, system, world } from '@minecraft/server';
import { MinecraftEntityTypes } from '@minecraft/vanilla-data';

function spawnFireworks(location: DimensionLocation) {
    const fireworkRocket = location.dimension.spawnEntity(MinecraftEntityTypes.FireworksRocket, location);

    system.runTimeout(() => {
        const velocity = fireworkRocket.getVelocity();

        world.sendMessage(`Velocity of firework is: ${velocity.x}, ${velocity.y}, ${velocity.z}`);
    }, 5);
}

getViewDirection()​

getViewDirection(): Vector3

Returns​

Vector3

Returns the current view direction of the entity.

Inherited from​

Entity . getViewDirection

Remarks​

Returns the current view direction of the entity.

Throws​

This function can throw errors.

hasComponent()​

hasComponent(componentId): boolean

Parameters​

ParameterTypeDescription
componentIdstringThe identifier of the component (e.g., 'minecraft:rideable')
to retrieve. If no namespace prefix is specified,
'minecraft:' is assumed.

Returns​

boolean

Returns true if the specified component is present on this entity.

Inherited from​

Entity . hasComponent

Remarks​

Returns true if the specified component is present on this entity.

hasTag()​

hasTag(tag): boolean

Parameters​

ParameterTypeDescription
tagstringIdentifier of the tag to test for.

Returns​

boolean

Returns whether an entity has a particular tag.

Inherited from​

Entity . hasTag

Remarks​

Returns whether an entity has a particular tag.

Throws​

This function can throw errors.

isOp()​

Beta

isOp(): boolean

Returns​

boolean

Remarks​

Returns true if this player has operator-level permissions.

Throws​

This function can throw errors.

isValid()​

isValid(): boolean

Returns​

boolean

Whether the entity is valid.

Inherited from​

Entity . isValid

Remarks​

Returns whether the entity can be manipulated by script. A Player is considered valid when it's EntityLifetimeState is set to Loaded.

kill()​

kill(): boolean

Returns​

boolean

Returns true if entity can be killed (even if it is already dead), otherwise it returns false.

Inherited from​

Entity . kill

Remarks​

Kills this entity. The entity will drop loot as normal.

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

Throws​

This function can throw errors.

Example​

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

function mobParty(targetLocation: DimensionLocation) {
    const mobs = ['creeper', 'skeleton', 'sheep'];

    // create some sample mob data
    for (let i = 0; i < 10; i++) {
        const mobTypeId = mobs[i % mobs.length];
        const entity = targetLocation.dimension.spawnEntity(mobTypeId, targetLocation);
        entity.addTag('mobparty.' + mobTypeId);
    }

    const eqo: EntityQueryOptions = {
        tags: ['mobparty.skeleton'],
    };

    for (const entity of targetLocation.dimension.getEntities(eqo)) {
        entity.kill();
    }
}

matches()​

matches(options): boolean

Parameters​

ParameterTypeDescription
optionsEntityQueryOptionsThe query to perform the match against.

Returns​

boolean

Returns true if the entity matches the criteria in the passed in EntityQueryOptions, otherwise it returns false.

Inherited from​

Entity . matches

Remarks​

Matches the entity against the passed in options. Uses the location of the entity for matching if the location is not specified in the passed in EntityQueryOptions.

Throws​

Throws if the query options are misconfigured.

playAnimation()​

playAnimation(animationName, options?): void

Parameters​

ParameterTypeDescription
animationNamestringThe animation identifier. e.g. animation.creeper.swelling
options?PlayAnimationOptionsAdditional options to control the playback and transitions
of the animation.

Returns​

void

Inherited from​

Entity . playAnimation

Remarks​

Cause the entity to play the given animation.

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

Throws​

This function can throw errors.

playMusic()​

playMusic(trackId, musicOptions?): void

Parameters​

ParameterTypeDescription
trackIdstringIdentifier of the music track to play.
musicOptions?MusicOptionsAdditional options for the music track.

Returns​

void

Remarks​

Plays a music track that only this particular player can hear.

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

Throws​

This function can throw errors.

playSound()​

playSound(soundId, soundOptions?): void

Parameters​

ParameterTypeDescription
soundIdstring-
soundOptions?PlayerSoundOptionsAdditional optional options for the sound.

Returns​

void

Remarks​

Plays a sound that only this particular player can hear.

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

Throws​

This function can throw errors.

postClientMessage()​

Beta

postClientMessage(id, value): void

Parameters​

ParameterType
idstring
valuestring

Returns​

void

Remarks​

This is an internal-facing method for posting a system message to downstream clients.

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

Throws​

This function can throw errors.

queueMusic()​

queueMusic(trackId, musicOptions?): void

Parameters​

ParameterTypeDescription
trackIdstringIdentifier of the music track to play.
musicOptions?MusicOptionsAdditional options for the music track.

Returns​

void

Remarks​

Queues an additional music track that only this particular player can hear. If a track is not playing, a music track will play.

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

Throws​

An error will be thrown if volume is less than 0.0. An error will be thrown if fade is less than 0.0.

remove()​

remove(): void

Returns​

void

Inherited from​

Entity . remove

Remarks​

Immediately removes the entity from the world. The removed entity will not perform a death animation or drop loot upon removal.

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

Throws​

This function can throw errors.

removeEffect()​

removeEffect(effectType): boolean

Parameters​

ParameterTypeDescription
effectTypestring | EffectTypeThe effect identifier.

Returns​

boolean

Returns true if the effect has been removed. Returns false if the effect is not found or does not exist.

Inherited from​

Entity . removeEffect

Remarks​

Removes the specified EffectType on the entity, or returns false if the effect is not present.

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

Throws​

This function can throw errors.

removeTag()​

removeTag(tag): boolean

Parameters​

ParameterTypeDescription
tagstringContent of the tag to remove.

Returns​

boolean

Returns whether the tag existed on the entity.

Inherited from​

Entity . removeTag

Remarks​

Removes a specified tag from an entity.

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

Throws​

This function can throw errors.

resetLevel()​

resetLevel(): void

Returns​

void

Remarks​

Resets the level of the player.

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

Throws​

This function can throw errors.

resetProperty()​

resetProperty(identifier): string | number | boolean

Parameters​

ParameterTypeDescription
identifierstringThe Entity Property identifier.

Returns​

string | number | boolean

Returns the default property value. For enum properties, a string is returned. For float and int properties, a number is returned. For undefined properties, undefined is returned.

Inherited from​

Entity . resetProperty

Remarks​

Resets an Entity Property back to its default value, as specified in the Entity's definition. This property change is not applied until the next tick.

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

Throws​

Throws if the entity is invalid.

minecraftcommon.EngineError

Error

runCommand()​

runCommand(commandString): CommandResult

Parameters​

ParameterTypeDescription
commandStringstringThe command string. Note: This should not include a leading
forward slash.

Returns​

CommandResult

A command result containing whether the command was successful.

Inherited from​

Entity . runCommand

Remarks​

Runs a synchronous command on the entity.

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

Throws​

This function can throw errors.

CommandError

Error

runCommandAsync()​

runCommandAsync(commandString): Promise ↗️ <CommandResult>

Parameters​

ParameterTypeDescription
commandStringstringCommand to run. Note that command strings should not start
with slash.

Returns​

Promise ↗️ <CommandResult>

For commands that return data, returns a JSON structure with command response values.

Inherited from​

Entity . runCommandAsync

Remarks​

Runs a particular command asynchronously from the context of this entity. Note that there is a maximum queue of 128 asynchronous commands that can be run in a given tick.

Throws​

This function can throw errors.

sendMessage()​

sendMessage(message): void

Parameters​

ParameterTypeDescription
messagestring | RawMessage | (string | RawMessage)[]The message to be displayed.

Returns​

void

Remarks​

Sends a message to the player.

Throws​

This method can throw if the provided RawMessage is in an invalid format. For example, if an empty name string is provided to score.

Example​

import { Player } from "@minecraft/server";

function sendPlayerMessages(player: Player) {
    // Displays "First or Second"
    const rawMessage = { translate: 'accessibility.list.or.two', with: ['First', 'Second'] };
    player.sendMessage(rawMessage);

    // Displays "Hello, world!"
    player.sendMessage('Hello, world!');

    // Displays "Welcome, Amazing Player 1!"
    player.sendMessage({ translate: 'authentication.welcome', with: ['Amazing Player 1'] });

    // Displays the player's score for objective "obj". Each player will see their own score.
    const rawMessageWithScore = { score: { name: '*', objective: 'obj' } };
    player.sendMessage(rawMessageWithScore);

    // Displays "Apple or Coal"
    const rawMessageWithNestedTranslations = {
        translate: 'accessibility.list.or.two',
        with: { rawtext: [{ translate: 'item.apple.name' }, { translate: 'item.coal.name' }] },
    };
    player.sendMessage(rawMessageWithNestedTranslations);
}

setDynamicProperty()​

setDynamicProperty(identifier, value?): void

Parameters​

ParameterTypeDescription
identifierstringThe property identifier.
value?string | number | boolean | Vector3Data value of the property to set.

Returns​

void

Inherited from​

Entity . setDynamicProperty

Remarks​

Sets a specified property to a value.

Throws​

This function can throw errors.

setGameMode()​

Beta

setGameMode(gameMode?): void

Parameters​

ParameterType
gameMode?GameMode

Returns​

void

Remarks​

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

Throws​

This function can throw errors.

setOnFire()​

setOnFire(seconds, useEffects?): boolean

Parameters​

ParameterTypeDescription
secondsnumberLength of time to set the entity on fire.
useEffects?booleanWhether side-effects should be applied (e.g. thawing freeze)
and other conditions such as rain or fire protection should
be taken into consideration.

Returns​

boolean

Whether the entity was set on fire. This can fail if seconds is less than or equal to zero, the entity is wet or the entity is immune to fire.

Inherited from​

Entity . setOnFire

Remarks​

Sets an entity on fire (if it is not in water or rain). Note that you can call getComponent('minecraft:onfire') and, if present, the entity is on fire.

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

Throws​

This function can throw errors.

Example​

import { world, Entity, EntityComponentTypes, system } from "@minecraft/server";

function setAblaze(entity: Entity) {
    entity.setOnFire(20, true);

    system.runTimeout(() => {
        const onfire = entity.getComponent(EntityComponentTypes.OnFire);
        if (onfire) {
            world.sendMessage(`${onfire.onFireTicksRemaining} fire ticks remaining, extinguishing the entity.`);
        }
        // This will extinguish the entity
        entity.extinguishFire(true);
    }, 30); // Run in 30 ticks or ~1.5 seconds

}

setOp()​

Beta

setOp(isOp): void

Parameters​

ParameterType
isOpboolean

Returns​

void

Remarks​

Will change the specified players permissions, and whether they are operator or not.

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

Throws​

This function can throw errors.

setProperty()​

setProperty(identifier, value): void

Parameters​

ParameterTypeDescription
identifierstringThe Entity Property identifier.
valuestring | number | booleanThe property value. The provided type must be compatible
with the type specified in the entity's definition.

Returns​

void

Inherited from​

Entity . setProperty

Remarks​

Sets an Entity Property to the provided value. This property change is not applied until the next tick.

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

Throws​

Throws if the entity is invalid. Throws if an invalid identifier is provided. Throws if the provided value type does not match the property type. Throws if the provided value is outside the expected range (int, float properties). Throws if the provided string value does not match the set of accepted enum values (enum properties

setRotation()​

setRotation(rotation): void

Parameters​

ParameterTypeDescription
rotationVector2The x and y rotation of the entity (in degrees). For most
mobs, the x rotation controls the head tilt and the y
rotation controls the body rotation.

Returns​

void

Inherited from​

Entity . setRotation

Remarks​

Sets the main rotation of the entity.

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

Throws​

This function can throw errors.

setSpawnPoint()​

setSpawnPoint(spawnPoint?): void

Parameters​

ParameterType
spawnPoint?DimensionLocation

Returns​

void

Remarks​

Sets the current starting spawn point for this particular player.

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

Throws​

This function can throw errors.

Error

LocationOutOfWorldBoundariesError

spawnParticle()​

Beta

spawnParticle(effectName, location, molangVariables?): void

Parameters​

ParameterTypeDescription
effectNamestringIdentifier of the particle to create.
locationVector3The location at which to create the particle emitter.
molangVariables?MolangVariableMapA set of optional, customizable variables that can be
adjusted for this particle.

Returns​

void

Remarks​

Creates a new particle emitter at a specified location in the world. Only visible to the target player.

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

Throws​

This function can throw errors.

Error

LocationInUnloadedChunkError

LocationOutOfWorldBoundariesError

Example​

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

world.afterEvents.playerSpawn.subscribe(event => {
    const targetLocation = event.player.location;
    for (let i = 0; i < 100; i++) {
        const molang = new MolangVariableMap();

        molang.setColorRGB('variable.color', {
            red: Math.random(),
            green: Math.random(),
            blue: Math.random()
        });

        const newLocation: Vector3 = {
            x: targetLocation.x + Math.floor(Math.random() * 8) - 4,
            y: targetLocation.y + Math.floor(Math.random() * 8) - 4,
            z: targetLocation.z + Math.floor(Math.random() * 8) - 4,
        };
        event.player.spawnParticle('minecraft:colored_flame_particle', newLocation, molang);
    }
});

startItemCooldown()​

Beta

startItemCooldown(cooldownCategory, tickDuration): void

Parameters​

ParameterTypeDescription
cooldownCategorystringSpecifies the cooldown category to retrieve the current
cooldown for.
tickDurationnumberDuration in ticks of the item cooldown.

Returns​

void

Remarks​

Sets the item cooldown time for a particular cooldown category.

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

Throws​

This function can throw errors.

stopMusic()​

stopMusic(): void

Returns​

void

Remarks​

Stops any music tracks from playing for this particular player.

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

Throws​

This function can throw errors.

teleport()​

teleport(location, teleportOptions?): void

Parameters​

ParameterTypeDescription
locationVector3New location for the entity.
teleportOptions?TeleportOptionsOptions regarding the teleport operation.

Returns​

void

Inherited from​

Entity . teleport

Remarks​

Teleports the selected entity to a new location

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

Throws​

This function can throw errors.

Example​

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

const overworld = world.getDimension('overworld');
const targetLocation = { x: 0, y: 0, z: 0 };

const pig = overworld.spawnEntity('minecraft:pig', targetLocation);

let inc = 1;
const runId = system.runInterval(() => {
    pig.teleport(
        { x: targetLocation.x + inc / 4, y: targetLocation.y + inc / 4, z: targetLocation.z + inc / 4 },
        {
            facingLocation: targetLocation,
        },
    );

    if (inc > 100) {
        system.clearRun(runId);
    }
    inc++;
}, 4);

triggerEvent()​

triggerEvent(eventName): void

Parameters​

ParameterTypeDescription
eventNamestringName of the entity type event to trigger. If a namespace is
not specified, minecraft: is assumed.

Returns​

void

Inherited from​

Entity . triggerEvent

Remarks​

Triggers an entity type event. For every entity, a number of events are defined in an entities' definition for key entity behaviors; for example, creepers have a minecraft:start_exploding type event.

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

Throws​

If the event is not defined in the definition of the entity, an error will be thrown.

Example​

// A function that spawns a creeper and triggers it to explode immediately
import { DimensionLocation } from '@minecraft/server';
import { MinecraftEntityTypes } from '@minecraft/vanilla-data';

function spawnExplodingCreeper(location: DimensionLocation) {
    const creeper = location.dimension.spawnEntity(MinecraftEntityTypes.Creeper, location);

    creeper.triggerEvent('minecraft:start_exploding_forced');
}

tryTeleport()​

tryTeleport(location, teleportOptions?): boolean

Parameters​

ParameterTypeDescription
locationVector3Location to teleport the entity to.
teleportOptions?TeleportOptionsOptions regarding the teleport operation.

Returns​

boolean

Returns whether the teleport succeeded. This can fail if the destination chunk is unloaded or if the teleport would result in intersecting with blocks.

Inherited from​

Entity . tryTeleport

Remarks​

Attempts to try a teleport, but may not complete the teleport operation (for example, if there are blocks at the destination.)

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

Throws​

This function can throw errors.