@minecraft/server 1.2.0-rc.1.20.0-preview.21 → 1.2.0-rc.1.20.0-preview.22

package/index.d.ts

@@ -16,11 +16,48 @@
  * ```json
  * {
  *   "module_name": "@minecraft/server",
- *   "version": "1.3.0-internal.1.20.0-preview.21"
+ *   "version": "1.3.0-internal.1.20.0-preview.22"
  * }
  * ```
  *
  */
+/**
+ * @beta
+ */
+export enum EntityDamageCause {
+    anvil = 'anvil',
+    blockExplosion = 'blockExplosion',
+    charging = 'charging',
+    contact = 'contact',
+    drowning = 'drowning',
+    entityAttack = 'entityAttack',
+    entityExplosion = 'entityExplosion',
+    fall = 'fall',
+    fallingBlock = 'fallingBlock',
+    fire = 'fire',
+    fireTick = 'fireTick',
+    fireworks = 'fireworks',
+    flyIntoWall = 'flyIntoWall',
+    freezing = 'freezing',
+    lava = 'lava',
+    lightning = 'lightning',
+    magic = 'magic',
+    magma = 'magma',
+    none = 'none',
+    override = 'override',
+    piston = 'piston',
+    projectile = 'projectile',
+    stalactite = 'stalactite',
+    stalagmite = 'stalagmite',
+    starve = 'starve',
+    suffocation = 'suffocation',
+    suicide = 'suicide',
+    temperature = 'temperature',
+    thorns = 'thorns',
+    'void' = 'void',
+    wither = 'wither',
+}
+
 /**
  * @beta
  * Represents a game mode for the current world experience.
@@ -60,6 +97,16 @@ export enum GameMode {
      */
     survival = 'survival',
 }
+
+/**
+ * @beta
+ */
+export enum ItemLockMode {
+    inventory = 'inventory',
+    none = 'none',
+    slot = 'slot',
+}
+
 /**
  * @beta
  * Represents a block in a dimension. A block represents a
@@ -122,6 +169,23 @@ export class Block {
      */
     setPermutation(permutation: BlockPermutation): void;
 }
+
+/**
+ * @beta
+ * Represents the inventory of a block in the world. Used with
+ * blocks like chests.
+ */
+export class BlockInventoryComponent {
+    protected constructor();
+    /**
+     * @remarks
+     * The container which holds an {@link ItemStack}.
+     *
+     * @throws This property can throw when used.
+     */
+    readonly container: Container;
+}
+
 /**
  * @beta
  * Contains the combination of type {@link BlockType} and
@@ -153,6 +217,7 @@ export class BlockPermutation {
      */
     static resolve(blockName: string, states?: Record<string, boolean | number | string>): BlockPermutation;
 }
+
 /**
  * Contains return data on the result of a command execution.
  */
@@ -167,6 +232,178 @@ export class CommandResult {
      */
     readonly successCount: number;
 }
+
+/**
+ * @beta
+ * Represents a container that can hold sets of items. Used
+ * with entities such as Players, Chest Minecarts, Llamas, and
+ * more.
+ */
+export class Container {
+    protected constructor();
+    /**
+     * @remarks
+     * Count of the slots in the container that are empty.
+     *
+     * @throws
+     * Throws if the container is invalid.
+     */
+    readonly emptySlotsCount: number;
+    /**
+     * @remarks
+     * The number of slots in this container. For example, a
+     * standard single-block chest has a size of 27. Note, a
+     * player's inventory container contains a total of 36 slots, 9
+     * hotbar slots plus 27 inventory slots.
+     *
+     * @throws
+     * Throws if the container is invalid.
+     */
+    readonly size: number;
+    /**
+     * @remarks
+     * Adds an item to the container. The item is placed in the
+     * first available slot(s) and can be stacked with existing
+     * items of the same type. Note, use {@link Container.setItem}
+     * if you wish to set the item in a particular slot.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param itemStack
+     * The stack of items to add.
+     * @throws This function can throw errors.
+     */
+    addItem(itemStack: ItemStack): ItemStack;
+    /**
+     * @remarks
+     * Clears all inventory items in the container.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @throws
+     * Throws if the container is invalid.
+     */
+    clearAll(): void;
+    /**
+     * @remarks
+     * Gets an {@link ItemStack} of the item at the specified slot.
+     * If the slot is empty, returns `undefined`. This method does
+     * not change or clear the contents of the specified slot. To
+     * get a reference to a particular slot, see {@link
+     * Container.getSlot}.
+     *
+     * @param slot
+     * Zero-based index of the slot to retrieve items from.
+     * @throws
+     * Throws if the container is invalid or if the `slot` index is
+     * out of bounds.
+     * @example getItem.ts
+     * ```typescript
+     *        // Get a copy of the first item in the player's hotbar
+     *        const inventory = player.getComponent("inventory") as EntityInventoryComponent;
+     *        const itemStack = inventory.container.getItem(0);
+     *
+     * ```
+     */
+    getItem(slot: number): ItemStack | undefined;
+    /**
+     * @remarks
+     * Moves an item from one slot to another, potentially across
+     * containers.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param fromSlot
+     * Zero-based index of the slot to transfer an item from, on
+     * this container.
+     * @param toSlot
+     * Zero-based index of the slot to transfer an item to, on
+     * `toContainer`.
+     * @param toContainer
+     * Target container to transfer to. Note this can be the same
+     * container as the source.
+     * @throws
+     * Throws if either this container or `toContainer` are invalid
+     * or if the `fromSlot` or `toSlot` indices out of bounds.
+     * @example moveItem.ts
+     * ```typescript
+     *        // Move an item from the first slot of fromPlayer's inventory to the fifth slot of toPlayer's inventory
+     *        const fromInventory = fromPlayer.getComponent('inventory') as EntityInventoryComponent;
+     *        const toInventory = toPlayer.getComponent('inventory') as EntityInventoryComponent;
+     *        fromInventory.container.moveItem(0, 4, toInventory.container);
+     *
+     * ```
+     */
+    moveItem(fromSlot: number, toSlot: number, toContainer: Container): void;
+    /**
+     * @remarks
+     * Sets an item stack within a particular slot.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param slot
+     * Zero-based index of the slot to set an item at.
+     * @param itemStack
+     * Stack of items to place within the specified slot. Setting
+     * `itemStack` to undefined will clear the slot.
+     * @throws
+     * Throws if the container is invalid or if the `slot` index is
+     * out of bounds.
+     */
+    setItem(slot: number, itemStack?: ItemStack): void;
+    /**
+     * @remarks
+     * Swaps items between two different slots within containers.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param slot
+     * Zero-based index of the slot to swap from this container.
+     * @param otherSlot
+     * Zero-based index of the slot to swap with.
+     * @param otherContainer
+     * Target container to swap with. Note this can be the same
+     * container as this source.
+     * @throws
+     * Throws if either this container or `otherContainer` are
+     * invalid or if the `slot` or `otherSlot` are out of bounds.
+     * @example swapItems.ts
+     * ```typescript
+     *        // Swaps an item between slots 0 and 4 in the player's inventory
+     *        const inventory = fromPlayer.getComponent('inventory') as EntityInventoryComponent;
+     *        inventory.container.swapItems(0, 4, inventory);
+     *
+     * ```
+     */
+    swapItems(slot: number, otherSlot: number, otherContainer: Container): void;
+    /**
+     * @remarks
+     * Moves an item from one slot to another container, or to the
+     * first available slot in the same container.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param fromSlot
+     * Zero-based index of the slot to transfer an item from, on
+     * this container.
+     * @param toContainer
+     * Target container to transfer to. Note this can be the same
+     * container as the source.
+     * @throws
+     * Throws if either this container or `toContainer` are invalid
+     * or if the `fromSlot` or `toSlot` indices out of bounds.
+     * @example transferItem.ts
+     * ```typescript
+     *        // Transfer an item from the first slot of fromPlayer's inventory to toPlayer's inventory
+     *        const fromInventory = fromPlayer.getComponent('inventory') as EntityInventoryComponent;
+     *        const toInventory = toPlayer.getComponent('inventory') as EntityInventoryComponent;
+     *        fromInventory.container.transferItem(0, toInventory.container);
+     *
+     * ```
+     */
+    transferItem(fromSlot: number, toContainer: Container): ItemStack;
+}
+
 /**
  * A class that represents a particular dimension (e.g., The
  * End) within a world.
@@ -192,7 +429,7 @@ export class Dimension {
      * Block at the specified location.
      * @throws This function can throw errors.
      */
-    getBlock(location: Vector3): Block;
+    getBlock(location: Vector3): Block | undefined;
     /**
      * @beta
      * @remarks
@@ -251,6 +488,14 @@ export class Dimension {
      * @throws This function can throw errors.
      */
     getPlayers(options?: EntityQueryOptions): Player[];
+    /**
+     * @beta
+     * @remarks
+     * This function can't be called in read-only mode.
+     *
+     * @throws This function can throw errors.
+     */
+    runCommand(commandString: string): CommandResult;
     /**
      * @remarks
      * Runs a particular command asynchronously from the context of
@@ -268,6 +513,7 @@ export class Dimension {
      */
     runCommandAsync(commandString: string): Promise<CommandResult>;
 }
+
 /**
  * Represents the state of an entity (a mob, the player, or
  * other moving objects like minecarts) in the world.
@@ -317,6 +563,77 @@ export class Entity {
      * @throws This property can throw when used.
      */
     readonly typeId: string;
+    /**
+     * @beta
+     * @remarks
+     * Adds a specified tag to an entity.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param tag
+     * Content of the tag to add.
+     * @throws This function can throw errors.
+     */
+    addTag(tag: string): boolean;
+    /**
+     * @beta
+     * @remarks
+     * Applies a set of damage to an entity.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param amount
+     * Amount of damage to apply.
+     * @param options
+     * Additional options about the source of damage, which may add
+     * additional effects or spur additional behaviors on this
+     * entity.
+     * @throws This function can throw errors.
+     */
+    applyDamage(amount: number, options?: EntityApplyDamageByProjectileOptions | EntityApplyDamageOptions): boolean;
+    /**
+     * @beta
+     * @remarks
+     * Applies impulse vector to the current velocity of the
+     * entity.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param vector
+     * Impulse vector.
+     * @throws This function can throw errors.
+     */
+    applyImpulse(vector: Vector3): void;
+    /**
+     * @beta
+     * @remarks
+     * Applies impulse vector to the current velocity of the
+     * entity.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param directionX
+     * X direction in horizontal plane.
+     * @param directionZ
+     * Z direction in horizontal plane.
+     * @param horizontalStrength
+     * Knockback strength for the horizontal vector.
+     * @param verticalStrength
+     * Knockback strength for the vertical vector.
+     * @throws This function can throw errors.
+     */
+    applyKnockback(directionX: number, directionZ: number, horizontalStrength: number, verticalStrength: number): void;
+    /**
+     * @beta
+     * @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.
+     */
+    clearVelocity(): void;
     /**
      * @beta
      * @remarks
@@ -326,6 +643,14 @@ export class Entity {
      * @throws This function can throw errors.
      */
     getHeadLocation(): Vector3;
+    /**
+     * @beta
+     * @remarks
+     * Returns all tags associated with an entity.
+     *
+     * @throws This function can throw errors.
+     */
+    getTags(): string[];
     /**
      * @beta
      * @remarks
@@ -342,6 +667,49 @@ export class Entity {
      * @throws This function can throw errors.
      */
     getViewDirection(): Vector3;
+    /**
+     * @beta
+     * @remarks
+     * Tests whether an entity has a particular tag.
+     *
+     * @param tag
+     * Identifier of the tag to test for.
+     * @throws This function can throw errors.
+     */
+    hasTag(tag: string): boolean;
+    /**
+     * @beta
+     * @remarks
+     * Kills this entity. The entity will drop loot as normal.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @returns
+     * Returns true if entity can be killed (even if it is already
+     * dead), otherwise it returns false.
+     * @throws This function can throw errors.
+     */
+    kill(): boolean;
+    /**
+     * @beta
+     * @remarks
+     * Removes a specified tag from an entity.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param tag
+     * Content of the tag to remove.
+     * @throws This function can throw errors.
+     */
+    removeTag(tag: string): boolean;
+    /**
+     * @beta
+     * @remarks
+     * This function can't be called in read-only mode.
+     *
+     * @throws This function can throw errors.
+     */
+    runCommand(commandString: string): CommandResult;
     /**
      * @remarks
      * Runs a particular command asynchronously from the context of
@@ -358,6 +726,245 @@ export class Entity {
      */
     runCommandAsync(commandString: string): Promise<CommandResult>;
 }
+
+/**
+ * @beta
+ * Defines this entity's inventory properties.
+ */
+export class EntityInventoryComponent {
+    protected constructor();
+    /**
+     * @remarks
+     * Number of slots that this entity can gain per extra
+     * strength.
+     *
+     * @throws This property can throw when used.
+     */
+    readonly additionalSlotsPerStrength: number;
+    /**
+     * @remarks
+     * If true, the contents of this inventory can be removed by a
+     * hopper.
+     *
+     * @throws This property can throw when used.
+     */
+    readonly canBeSiphonedFrom: boolean;
+    /**
+     * @remarks
+     * Defines the container for this entity.
+     *
+     * @throws This property can throw when used.
+     */
+    readonly container: Container;
+    /**
+     * @remarks
+     * Type of container this entity has.
+     *
+     * @throws This property can throw when used.
+     */
+    readonly containerType: string;
+    /**
+     * @remarks
+     * Number of slots the container has.
+     *
+     * @throws This property can throw when used.
+     */
+    readonly inventorySize: number;
+    /**
+     * @remarks
+     * If true, the entity will not drop it's inventory on death.
+     *
+     * @throws This property can throw when used.
+     */
+    readonly 'private': boolean;
+    /**
+     * @remarks
+     * If true, the entity's inventory can only be accessed by its
+     * owner or itself.
+     *
+     * @throws This property can throw when used.
+     */
+    readonly restrictToOwner: boolean;
+}
+
+/**
+ * @beta
+ * If added onto the entity, this indicates that the entity
+ * represents a free-floating item in the world. Lets you
+ * retrieve the actual item stack contents via the itemStack
+ * property.
+ */
+export class EntityItemComponent {
+    protected constructor();
+    /**
+     * @remarks
+     * Item stack represented by this entity in the world.
+     *
+     * @throws This property can throw when used.
+     */
+    readonly itemStack: ItemStack;
+}
+
+/**
+ * @beta
+ * Base class for item components.
+ */
+export class ItemComponent {
+    protected constructor();
+}
+
+/**
+ * @beta
+ * Defines a collection of items.
+ */
+export class ItemStack {
+    /**
+     * @remarks
+     * Number of the items in the stack. Valid values range between
+     * 1-255. The provided value will be clamped to the item's
+     * maximum stack size.
+     *
+     * @throws
+     * Throws if the value is outside the range of 1-255.
+     */
+    readonly amount: number;
+    /**
+     * @remarks
+     * Returns whether the item is stackable. An item is considered
+     * stackable if the item's maximum stack size is greater than 1
+     * and the item does not contain any custom data or properties.
+     *
+     */
+    readonly isStackable: boolean;
+    /**
+     * @remarks
+     * Gets or sets whether the item is kept on death.
+     *
+     */
+    readonly keepOnDeath: boolean;
+    /**
+     * @remarks
+     * Gets or sets the item's lock mode. The default value is
+     * `ItemLockMode.none`.
+     *
+     */
+    readonly lockMode: ItemLockMode;
+    /**
+     * @remarks
+     * The maximum stack size. This value varies depending on the
+     * type of item. For example, torches have a maximum stack size
+     * of 64, while eggs have a maximum stack size of 16.
+     *
+     */
+    readonly maxAmount: number;
+    /**
+     * @remarks
+     * Given name of this stack of items. The name tag is displayed
+     * when hovering over the item. Setting the name tag to an
+     * empty string or `undefined` will remove the name tag.
+     *
+     * @throws
+     * Throws if the length exceeds 255 characters.
+     */
+    readonly nameTag?: string;
+    /**
+     * @remarks
+     * The type of the item.
+     *
+     */
+    readonly 'type': ItemType;
+    /**
+     * @remarks
+     * Identifier of the type of items for the stack. If a
+     * namespace is not specified, 'minecraft:' is assumed.
+     * Examples include 'wheat' or 'apple'.
+     *
+     */
+    readonly typeId: string;
+    /**
+     * @remarks
+     * Creates a new instance of a stack of items for use in the
+     * world.
+     *
+     * @param itemType
+     * Type of item to create. See the {@link MinecraftItemTypes}
+     * enumeration for a list of standard item types in Minecraft
+     * experiences.
+     * @param amount
+     * Number of items to place in the stack, between 1-255. The
+     * provided value will be clamped to the item's maximum stack
+     * size. Note that certain items can only have one item in the
+     * stack.
+     * @throws
+     * Throws if `itemType` is invalid, or if `amount` is outside
+     * the range of 1-255.
+     */
+    constructor(itemType: ItemType | string, amount?: number);
+    /**
+     * @remarks
+     * Gets a component (that represents additional capabilities)
+     * for an item stack.
+     *
+     * @param componentId
+     * The identifier of the component (e.g., 'minecraft:food') to
+     * retrieve. If no namespace prefix is specified, 'minecraft:'
+     * is assumed. If the component is not present on the item
+     * stack, undefined is returned.
+     * @example durability.ts
+     * ```typescript
+     *        // Get the maximum durability of a custom sword item
+     *        const itemStack = new ItemStack("custom:sword");
+     *        const durability = itemStack.getComponent("minecraft:durability") as ItemDurabilityComponent;
+     *        const maxDurability = durability.maxDurability;
+     *
+     * ```
+     */
+    getComponent(componentId: string): ItemComponent | undefined;
+    /**
+     * @remarks
+     * Returns all components that are both present on this item
+     * stack and supported by the API.
+     *
+     */
+    getComponents(): ItemComponent[];
+    /**
+     * @remarks
+     * Returns true if the specified component is present on this
+     * item stack.
+     *
+     * @param componentId
+     * The identifier of the component (e.g., 'minecraft:food') to
+     * retrieve. If no namespace prefix is specified, 'minecraft:'
+     * is assumed.
+     */
+    hasComponent(componentId: string): boolean;
+    /**
+     * @remarks
+     * Returns whether this item stack can be stacked with the
+     * given `itemStack`. This is determined by comparing the item
+     * type and any custom data and properties associated with the
+     * item stacks. The amount of each item stack is not taken into
+     * consideration.
+     *
+     */
+    isStackableWith(itemStack: ItemStack): boolean;
+}
+
+/**
+ * @beta
+ * Represents the type of an item - for example, Wool.
+ */
+export class ItemType {
+    protected constructor();
+    /**
+     * @remarks
+     * Returns the identifier of the item type - for example,
+     * 'minecraft:apple'.
+     *
+     */
+    readonly id: string;
+}
+
 /**
  * A collection of default Minecraft dimension types.
  */
@@ -397,6 +1004,7 @@ export class MinecraftDimensionTypes {
      */
     static readonly theEnd = 'minecraft:the_end';
 }
+
 /**
  * Represents a player within the world.
  */
@@ -409,6 +1017,20 @@ export class Player extends Entity {
      * @throws This property can throw when used.
      */
     readonly name: string;
+    /**
+     * @beta
+     * @remarks
+     * Plays a sound that only this particular player can hear.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param soundID
+     * Identifier of the sound to play.
+     * @param soundOptions
+     * Additional optional options for the sound.
+     * @throws This function can throw errors.
+     */
+    playSound(soundID: string, soundOptions?: PlayerSoundOptions): void;
     /**
      * @beta
      * @remarks
@@ -453,6 +1075,7 @@ export class Player extends Entity {
      */
     sendMessage(message: (RawMessage | string)[] | RawMessage | string): void;
 }
+
 /**
  * A class that provides system-level events and functions.
  */
@@ -518,6 +1141,7 @@ export class System {
      */
     runTimeout(callback: () => void, tickDelay?: number): number;
 }
+
 /**
  * A class that wraps the state of a world - a set of
  * dimensions and the environment of Minecraft.
@@ -555,6 +1179,37 @@ export class World {
      * @throws This function can throw errors.
      */
     getPlayers(options?: EntityQueryOptions): Player[];
+    /**
+     * @beta
+     * @remarks
+     * Plays a particular music track for all players.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @throws This function can throw errors.
+     */
+    playMusic(trackID: string, musicOptions?: MusicOptions): void;
+    /**
+     * @beta
+     * @remarks
+     * Plays a sound for all players.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @throws This function can throw errors.
+     */
+    playSound(soundID: string, location: Vector3, soundOptions?: WorldSoundOptions): void;
+    /**
+     * @beta
+     * @remarks
+     * Queues an additional music track for players. If a track is
+     * not playing, a music track will play.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @throws This function can throw errors.
+     */
+    queueMusic(trackID: string, musicOptions?: MusicOptions): void;
     /**
      * @beta
      * @remarks
@@ -598,7 +1253,33 @@ export class World {
      * ```
      */
     sendMessage(message: (RawMessage | string)[] | RawMessage | string): void;
+    /**
+     * @beta
+     * @remarks
+     * Stops any music tracks from playing.
+     *
+     * This function can't be called in read-only mode.
+     *
+     */
+    stopMusic(): void;
+}
+
+/**
+ * @beta
+ */
+export interface EntityApplyDamageByProjectileOptions {
+    damagingEntity?: Entity;
+    damagingProjectile: Entity;
+}
+
+/**
+ * @beta
+ */
+export interface EntityApplyDamageOptions {
+    cause: EntityDamageCause;
+    damagingEntity?: Entity;
 }
+
 /**
  * @beta
  * Contains options for selecting entities within an area.
@@ -761,6 +1442,7 @@ export interface EntityQueryOptions {
      */
     type?: string;
 }
+
 /**
  * @beta
  * Contains additional options for filtering players based on
@@ -795,6 +1477,42 @@ export interface EntityQueryScoreOptions {
      */
     objective?: string;
 }
+
+/**
+ * @beta
+ * Additional configuration options for {@link
+ * World.playMusic}/{@link World.queueMusic} methods.
+ */
+export interface MusicOptions {
+    /**
+     * @remarks
+     * Specifies a fade overlap for music at the end of play.
+     *
+     */
+    fade?: number;
+    /**
+     * @remarks
+     * If set to true, this music track will play repeatedly.
+     *
+     */
+    loop?: boolean;
+    /**
+     * @remarks
+     * Relative volume level of the music.
+     *
+     */
+    volume?: number;
+}
+
+/**
+ * @beta
+ */
+export interface PlayerSoundOptions {
+    location?: Vector3;
+    pitch?: number;
+    volume?: number;
+}
+
 /**
  * @beta
  */
@@ -805,6 +1523,7 @@ export interface RawMessage {
     translate?: string;
     with?: string[] | RawMessage;
 }
+
 /**
  * @beta
  */
@@ -812,6 +1531,7 @@ export interface RawMessageScore {
     name?: string;
     objective?: string;
 }
+
 /**
  * @beta
  * Contains a description of a vector.
@@ -836,6 +1556,15 @@ export interface Vector3 {
      */
     z: number;
 }
+
+/**
+ * @beta
+ */
+export interface WorldSoundOptions {
+    pitch?: number;
+    volume?: number;
+}
+
 /**
  * @remarks
  * A class that provides system-level events and functions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minecraft/server",
-  "version": "1.2.0-rc.1.20.0-preview.21",
+  "version": "1.2.0-rc.1.20.0-preview.22",
   "description": "",
   "contributors": [
     {