@minecraft/server 2.0.0-beta.1.21.80-preview.26 → 2.0.0-beta.1.21.80-preview.28

package/index.d.ts

@@ -238,6 +238,20 @@ export enum CustomCommandErrorReason {
      *
      */
     AlreadyRegistered = 'AlreadyRegistered',
+    /**
+     * @remarks
+     * Custom Command references an enum that has not been
+     * registered.
+     *
+     */
+    EnumDependencyMissing = 'EnumDependencyMissing',
+    /**
+     * @remarks
+     * Supplied Custom Command namespace does not match previous
+     * registrations for this add-on.
+     *
+     */
+    NamespaceMismatch = 'NamespaceMismatch',
     /**
      * @remarks
      * Too many command parameters defined in CustomCommand.
@@ -262,17 +276,69 @@ export enum CustomCommandErrorReason {
 
 /**
  * @beta
+ * The types of paramaters accepted by a custom command.
  */
 export enum CustomCommandParamType {
+    /**
+     * @remarks
+     * Command boolean parameter expecting true or false as input.
+     *
+     */
     Boolean = 0,
+    /**
+     * @remarks
+     * Command integer parameter.
+     *
+     */
     Integer = 1,
+    /**
+     * @remarks
+     * Command float parameter.
+     *
+     */
     Float = 2,
+    /**
+     * @remarks
+     * Command string parameter.
+     *
+     */
     String = 3,
+    /**
+     * @remarks
+     * Command entity selector parameter.
+     *
+     */
     EntitySelector = 4,
+    /**
+     * @remarks
+     * Command player selector parameter.
+     *
+     */
     PlayerSelector = 5,
+    /**
+     * @remarks
+     * Command location parameter.
+     *
+     */
     Location = 6,
+    /**
+     * @remarks
+     * Command block type parameter expecting a Minecraft block.
+     *
+     */
     BlockType = 7,
+    /**
+     * @remarks
+     * Command item name parameter.
+     *
+     */
     ItemType = 8,
+    /**
+     * @remarks
+     * Command enum parameter.
+     *
+     */
+    Enum = 9,
 }
 
 /**
@@ -670,13 +736,6 @@ export enum EntityComponentTypes {
      *
      */
     FrictionModifier = 'minecraft:friction_modifier',
-    /**
-     * @remarks
-     * Sets the offset from the ground that the entity is actually
-     * at.
-     *
-     */
-    GroundOffset = 'minecraft:ground_offset',
     /**
      * @remarks
      * Defines the interactions with this entity for healing it.
@@ -2555,7 +2614,7 @@ export enum WeatherType {
 
 export type BlockComponentReturnType<T extends string> = T extends keyof BlockComponentTypeMap
     ? BlockComponentTypeMap[T]
-    : BlockComponent;
+    : BlockCustomComponentInstance;
 
 export type BlockComponentTypeMap = {
     destruction_particles: BlockDestructionParticlesComponent;
@@ -2605,7 +2664,6 @@ export type EntityComponentTypeMap = {
     floats_in_liquid: EntityFloatsInLiquidComponent;
     flying_speed: EntityFlyingSpeedComponent;
     friction_modifier: EntityFrictionModifierComponent;
-    ground_offset: EntityGroundOffsetComponent;
     healable: EntityHealableComponent;
     health: EntityHealthComponent;
     inventory: EntityInventoryComponent;
@@ -2640,7 +2698,6 @@ export type EntityComponentTypeMap = {
     'minecraft:floats_in_liquid': EntityFloatsInLiquidComponent;
     'minecraft:flying_speed': EntityFlyingSpeedComponent;
     'minecraft:friction_modifier': EntityFrictionModifierComponent;
-    'minecraft:ground_offset': EntityGroundOffsetComponent;
     'minecraft:healable': EntityHealableComponent;
     'minecraft:health': EntityHealthComponent;
     'minecraft:inventory': EntityInventoryComponent;
@@ -2777,8 +2834,6 @@ export class AimAssistCategory {
      * getBlockPriorities.
      *
      * @throws This property can throw when used.
-     *
-     * {@link Error}
      */
     readonly defaultBlockPriority: number;
     /**
@@ -2787,8 +2842,6 @@ export class AimAssistCategory {
      * in getEntityPriorities.
      *
      * @throws This property can throw when used.
-     *
-     * {@link Error}
      */
     readonly defaultEntityPriority: number;
     /**
@@ -2805,8 +2858,6 @@ export class AimAssistCategory {
      * The record mapping block Ids to their priority settings.
      * Larger numbers have greater priority.
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     getBlockPriorities(): Record<string, number>;
     /**
@@ -2817,8 +2868,6 @@ export class AimAssistCategory {
      * The record mapping entity Ids to their priority settings.
      * Larger numbers have greater priority.
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     getEntityPriorities(): Record<string, number>;
 }
@@ -2920,8 +2969,6 @@ export class AimAssistPreset {
      * provided to setItemSettings.
      *
      * @throws This property can throw when used.
-     *
-     * {@link Error}
      */
     readonly defaultItemSettings?: string;
     /**
@@ -2929,8 +2976,6 @@ export class AimAssistPreset {
      * Optional. Aim-assist category Id used for an empty hand.
      *
      * @throws This property can throw when used.
-     *
-     * {@link Error}
      */
     readonly handSettings?: string;
     /**
@@ -2947,8 +2992,6 @@ export class AimAssistPreset {
      * @returns
      * The array of block/entity Ids.
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     getExcludedTargets(): string[];
     /**
@@ -2958,8 +3001,6 @@ export class AimAssistPreset {
      * @returns
      * The record mapping item Ids to aim-assist category Ids.
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     getItemSettings(): Record<string, string>;
     /**
@@ -2970,8 +3011,6 @@ export class AimAssistPreset {
      * @returns
      * The array of item Ids.
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     getLiquidTargetingItems(): string[];
 }
@@ -3373,6 +3412,7 @@ export class Block {
      *
      * @param steps
      * Number of steps above to step before returning.
+     * Defaults to: 1
      * @throws This function can throw errors.
      *
      * {@link LocationInUnloadedChunkError}
@@ -3387,6 +3427,7 @@ export class Block {
      *
      * @param steps
      * Number of steps below to step before returning.
+     * Defaults to: 1
      * @throws This function can throw errors.
      *
      * {@link LocationInUnloadedChunkError}
@@ -3475,6 +3516,7 @@ export class Block {
      *
      * @param steps
      * Number of steps to the east to step before returning.
+     * Defaults to: 1
      * @throws This function can throw errors.
      *
      * {@link LocationInUnloadedChunkError}
@@ -3491,8 +3533,9 @@ export class Block {
      * @param componentId
      * The identifier of the component (e.g.,
      * 'minecraft:inventory'). If no namespace prefix is specified,
-     * 'minecraft:' is assumed. Available component IDs can be
-     * found as part of the {@link BlockComponentTypes} enum.
+     * 'minecraft:' is assumed. Available component IDs are those
+     * in the {@link BlockComponentTypes} enum and custom component
+     * IDs registered with the {@link BlockComponentRegistry}.
      * @returns
      * Returns the component if it exists on the block, otherwise
      * undefined.
@@ -3511,9 +3554,11 @@ export class Block {
      * @param amount
      * Number of instances of this block to place in the item
      * stack.
+     * Defaults to: 1
      * @param withData
      * Whether additional data facets of the item stack are
      * included.
+     * Defaults to: false
      * @returns
      * An itemStack with the specified amount of items and data.
      * Returns undefined if block type is incompatible.
@@ -3674,6 +3719,7 @@ export class Block {
      *
      * @param steps
      * Number of steps to the north to step before returning.
+     * Defaults to: 1
      * @throws This function can throw errors.
      *
      * {@link LocationInUnloadedChunkError}
@@ -3759,6 +3805,7 @@ export class Block {
      *
      * @param steps
      * Number of steps to the south to step before returning.
+     * Defaults to: 1
      * @throws This function can throw errors.
      *
      * {@link LocationInUnloadedChunkError}
@@ -3794,6 +3841,7 @@ export class Block {
      *
      * @param steps
      * Number of steps to the west to step before returning.
+     * Defaults to: 1
      * @throws This function can throw errors.
      *
      * {@link LocationInUnloadedChunkError}
@@ -4141,6 +4189,15 @@ export class BlockComponentTickEvent extends BlockEvent {
     private constructor();
 }
 
+/**
+ * @beta
+ * An instance of a custom component on a block.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class BlockCustomComponentInstance extends BlockComponent {
+    private constructor();
+}
+
 /**
  * @beta
  * Represents the particles that appear when the block is
@@ -4154,8 +4211,6 @@ export class BlockDestructionParticlesComponent extends BlockComponent {
      * Name of the texture used for the particles.
      *
      * @throws This property can throw when used.
-     *
-     * {@link Error}
      */
     readonly texture: string;
     /**
@@ -4163,8 +4218,6 @@ export class BlockDestructionParticlesComponent extends BlockComponent {
      * Type of tint applied to the particles.
      *
      * @throws This property can throw when used.
-     *
-     * {@link Error}
      */
     readonly tintMethod: TintMethod;
     static readonly componentId = 'minecraft:destruction_particles';
@@ -4274,8 +4327,6 @@ export class BlockFluidContainerComponent extends BlockComponent {
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     addDye(dye: ItemType): void;
     /**
@@ -4285,8 +4336,6 @@ export class BlockFluidContainerComponent extends BlockComponent {
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     getFluidType(): FluidType;
     /**
@@ -4296,8 +4345,6 @@ export class BlockFluidContainerComponent extends BlockComponent {
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     setFluidType(fluidType: FluidType): void;
     /**
@@ -4308,8 +4355,6 @@ export class BlockFluidContainerComponent extends BlockComponent {
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     setPotion(itemStack: ItemStack): void;
 }
@@ -4419,8 +4464,6 @@ export class BlockMapColorComponent extends BlockComponent {
      * Base map color defined for that block.
      *
      * @throws This property can throw when used.
-     *
-     * {@link Error}
      */
     readonly color: RGBA;
     /**
@@ -4435,8 +4478,6 @@ export class BlockMapColorComponent extends BlockComponent {
      * Type of tint applied to the color.
      *
      * @throws This property can throw when used.
-     *
-     * {@link Error}
      */
     readonly tintMethod: TintMethod;
     static readonly componentId = 'minecraft:map_color';
@@ -4491,8 +4532,6 @@ export class BlockPermutation {
      * @returns
      * Whether this block is removed when touched by liquid.
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     canBeDestroyedByLiquidSpread(liquidType: LiquidType): boolean;
     /**
@@ -4505,8 +4544,6 @@ export class BlockPermutation {
      * @returns
      * Whether this block can have a liquid placed over it.
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     canContainLiquid(liquidType: LiquidType): boolean;
     /**
@@ -4528,6 +4565,7 @@ export class BlockPermutation {
      * @param amount
      * Number of instances of this block to place in the prototype
      * item stack.
+     * Defaults to: 1
      */
     getItemStack(amount?: number): ItemStack | undefined;
     /**
@@ -4582,8 +4620,6 @@ export class BlockPermutation {
      * @returns
      * Whether this block stops liquid from flowing.
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     isLiquidBlocking(liquidType: LiquidType): boolean;
     /**
@@ -4597,8 +4633,6 @@ export class BlockPermutation {
      * Whether this block is removed and spawns its item when
      * touched by liquid.
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     liquidSpreadCausesSpawn(liquidType: LiquidType): boolean;
     /**
@@ -4785,6 +4819,8 @@ export class BlockRecordPlayerComponent extends BlockComponent {
      *
      * This function can't be called in read-only mode.
      *
+     * @param startPlaying
+     * Defaults to: true
      * @throws This function can throw errors.
      */
     setRecord(recordItemType?: ItemType | string, startPlaying?: boolean): void;
@@ -4925,6 +4961,7 @@ export class BlockSignComponent extends BlockComponent {
      * The side of the sign to read the message from. If not
      * provided, this will return the message from the front side
      * of the sign.
+     * Defaults to: 0
      * @throws This function can throw errors.
      */
     getRawText(side?: SignSide): RawText | undefined;
@@ -4937,6 +4974,7 @@ export class BlockSignComponent extends BlockComponent {
      * The side of the sign to read the message from. If not
      * provided, this will return the message from the front side
      * of the sign.
+     * Defaults to: 0
      * @throws This function can throw errors.
      */
     getText(side?: SignSide): string | undefined;
@@ -4948,6 +4986,7 @@ export class BlockSignComponent extends BlockComponent {
      * @param side
      * The side of the sign to read the dye from. If not provided,
      * this will return the dye on the front side of the sign.
+     * Defaults to: 0
      * @throws This function can throw errors.
      */
     getTextDyeColor(side?: SignSide): DyeColor | undefined;
@@ -4967,6 +5006,7 @@ export class BlockSignComponent extends BlockComponent {
      * The side of the sign the message will be set on. If not
      * provided, the message will be set on the front side of the
      * sign.
+     * Defaults to: 0
      * @throws
      * Throws if the provided message is greater than 512
      * characters in length.
@@ -4981,10 +5021,12 @@ export class BlockSignComponent extends BlockComponent {
      * @param color
      * The dye color to apply to the sign or undefined to clear the
      * dye on the sign.
+     * Defaults to: null
      * @param side
      * The side of the sign the color will be set on. If not
      * provided, the color will be set on the front side of the
      * sign.
+     * Defaults to: 0
      * @throws This function can throw errors.
      */
     setTextDyeColor(color?: DyeColor, side?: SignSide): void;
@@ -6676,6 +6718,23 @@ export class CustomCommandRegistry {
         customCommand: CustomCommand,
         callback: (origin: CustomCommandOrigin, ...args: any[]) => CustomCommandResult | undefined,
     ): void;
+    /**
+     * @remarks
+     * Registers a custom command enum.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * This function can be called in early-execution mode.
+     *
+     * @throws This function can throw errors.
+     *
+     * {@link CustomCommandError}
+     *
+     * {@link minecraftcommon.EngineError}
+     *
+     * {@link NamespaceNameError}
+     */
+    registerEnum(name: string, values: string[]): void;
 }
 
 /**
@@ -6789,6 +6848,7 @@ export class Dimension {
      * or all of the block volume is outside of the loaded chunks.
      * Will only check the block locations that are within the
      * loaded chunks in the volume.
+     * Defaults to: false
      * @returns
      * Returns true if at least one block in the volume satisfies
      * the filter, false otherwise.
@@ -6983,6 +7043,7 @@ export class Dimension {
      * or all of the block volume is outside of the loaded chunks.
      * Will only check the block locations that are within the
      * loaded chunks in the volume.
+     * Defaults to: false
      * @returns
      * Returns the ListBlockVolume that contains all the block
      * locations that satisfied the block filter.
@@ -7151,6 +7212,7 @@ export class Dimension {
      * Note: The function call will always throw an error if using
      * an unknown feature name or trying to place in a unloaded
      * chunk.
+     * Defaults to: false
      * @throws
      * An error will be thrown if the feature name is invalid.
      * An error will be thrown if the location is in an unloaded
@@ -7302,20 +7364,24 @@ export class Dimension {
      * Newly created entity at the specified location.
      * @throws This function can throw errors.
      *
+     * {@link Error}
+     *
+     * {@link minecraftcommon.InvalidArgumentError}
+     *
      * {@link LocationInUnloadedChunkError}
      *
      * {@link LocationOutOfWorldBoundariesError}
      * @example spawnAdultHorse.ts
      * ```typescript
-     * import { DimensionLocation } from "@minecraft/server";
-     * import { Vector3Utils } from "@minecraft/math";
+     * import { DimensionLocation } from '@minecraft/server';
+     * import { Vector3Utils } from '@minecraft/math';
      *
      * function spawnAdultHorse(log: (message: string, status?: number) => void, targetLocation: DimensionLocation) {
-     *   log("Create a horse and triggering the ageable_grow_up event, ensuring the horse is created as an adult");
-     *   targetLocation.dimension.spawnEntity(
-     *     "minecraft:horse<minecraft:ageable_grow_up>",
-     *     Vector3Utils.add(targetLocation, { x: 0, y: 1, z: 0 })
-     *   );
+     *     log('Create a horse and triggering the ageable_grow_up event, ensuring the horse is created as an adult');
+     *     targetLocation.dimension.spawnEntity(
+     *         'minecraft:horse<minecraft:ageable_grow_up>',
+     *         Vector3Utils.add(targetLocation, { x: 0, y: 1, z: 0 })
+     *     );
      * }
      * ```
      * @example quickFoxLazyDog.ts
@@ -8153,6 +8219,7 @@ export class Entity {
      * @param useEffects
      * Whether to show any visual effects connected to the
      * extinguishing.
+     * Defaults to: true
      * @returns
      * Returns whether the entity was on fire.
      * @throws This function can throw errors.
@@ -8561,7 +8628,7 @@ export class Entity {
      *
      * {@link CommandError}
      *
-     * {@link Error}
+     * {@link InvalidEntityError}
      */
     runCommand(commandString: string): CommandResult;
     /**
@@ -8600,6 +8667,7 @@ export class Entity {
      * Whether side-effects should be applied (e.g. thawing freeze)
      * and other conditions such as rain or fire protection should
      * be taken into consideration.
+     * Defaults to: true
      * @returns
      * 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
@@ -9336,26 +9404,6 @@ export class EntityFrictionModifierComponent extends EntityComponent {
     static readonly componentId = 'minecraft:friction_modifier';
 }
 
-/**
- * Sets the offset from the ground that the entity is actually
- * at.
- */
-// @ts-ignore Class inheritance allowed for native defined classes
-export class EntityGroundOffsetComponent extends EntityComponent {
-    private constructor();
-    /**
-     * @remarks
-     * Value of this particular ground offset. Note that this value
-     * is effectively read only; setting the ground offset value
-     * will not have an impact on the related entity.
-     *
-     * This property can't be edited in read-only mode.
-     *
-     */
-    value: number;
-    static readonly componentId = 'minecraft:ground_offset';
-}
-
 /**
  * Defines the interactions with this entity for healing it.
  */
@@ -12217,8 +12265,6 @@ export class ItemCompostableComponent extends ItemComponent {
      *
      * @throws
      * Throws if value outside the range [1 - 100]
-     *
-     * {@link Error}
      */
     readonly compostingChance: number;
     static readonly componentId = 'minecraft:compostable';
@@ -12351,6 +12397,7 @@ export class ItemDurabilityComponent extends ItemComponent {
      * Unbreaking factor to consider in factoring the damage
      * chance. Incoming unbreaking parameter must be within the
      * range [0, 3].
+     * Defaults to: 0
      * @throws This function can throw errors.
      */
     getDamageChance(unbreakingEnchantmentLevel?: number): number;
@@ -12387,8 +12434,6 @@ export class ItemDyeableComponent extends ItemComponent {
      * Returns the default color of the item.
      *
      * @throws This property can throw when used.
-     *
-     * {@link Error}
      */
     readonly defaultColor?: RGB;
     static readonly componentId = 'minecraft:dyeable';
@@ -12863,6 +12908,7 @@ export class ItemStack {
      * provided value will be clamped to the item's maximum stack
      * size. Note that certain items can only have one item in the
      * stack.
+     * Defaults to: 1
      * @throws
      * Throws if `itemType` is invalid, or if `amount` is outside
      * the range of 1-255.
@@ -13986,8 +14032,6 @@ export class Player extends Entity {
      * Contains the player's device information.
      *
      * @throws This property can throw when used.
-     *
-     * {@link Error}
      */
     readonly clientSystemInfo: ClientSystemInfo;
     /**
@@ -15129,8 +15173,6 @@ export class PlayerInputPermissions {
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
-     *
-     * {@link Error}
      */
     isPermissionCategoryEnabled(permissionCategory: InputPermissionCategory): boolean;
     /**
@@ -17022,6 +17064,7 @@ export class Structure {
      * @param saveMode
      * Determines how the Structure should be saved. Defaults to
      * saving to the world.
+     * Defaults to: 1
      * @returns
      * Returns the newly created structure.
      * @throws
@@ -17058,9 +17101,11 @@ export class Structure {
      * The block location relative to the Structure's origin.
      * @param blockPermutation
      * The BlockPermutation to set.
+     * Defaults to: null
      * @param waterlogged
      * Specifies whether the block should be waterlogged. Air and
      * undefined blocks cannot be waterlogged.
+     * Defaults to: false
      * @throws
      * Throws if the type of block is StructureVoid.
      * Throws if the block is undefined and waterlogged is set to
@@ -17099,6 +17144,7 @@ export class StructureManager {
      * @param saveMode
      * How the Structure should be saved upon creation. Defaults to
      * StructureSaveMode.Memory.
+     * Defaults to: 0
      * @returns
      * Returns the newly created Structure.
      * @throws
@@ -17216,7 +17262,7 @@ export class StructureManager {
         options?: StructurePlaceOptions,
     ): void;
     /**
-     * @beta
+     * @rc
      * @remarks
      * Places a partial jigsaw structure in the world. This is
      * useful for debugging connections between jigsaw blocks.
@@ -17260,7 +17306,7 @@ export class StructureManager {
         options?: JigsawPlaceOptions,
     ): BlockBoundingBox;
     /**
-     * @beta
+     * @rc
      * @remarks
      * Places a jigsaw structure in the world.
      *
@@ -20435,7 +20481,7 @@ export interface ItemCustomComponent {
 }
 
 /**
- * @beta
+ * @rc
  * Provides additional options for {@link
  * StructureManager.placeJigsaw}.
  */
@@ -20457,7 +20503,7 @@ export interface JigsawPlaceOptions {
 }
 
 /**
- * @beta
+ * @rc
  * Provides additional options for {@link
  * StructureManager.placeJigsawStructure}.
  */
@@ -20946,10 +20992,31 @@ export interface ScriptEventMessageFilterOptions {
 
 /**
  * @beta
+ * Contains additional options for spawning an Entity.
  */
 export interface SpawnEntityOptions {
+    /**
+     * @remarks
+     * Optional boolean which determines if this entity should
+     * persist in the game world. Persistence prevents the entity
+     * from automatically despawning.
+     *
+     */
     initialPersistence?: boolean;
+    /**
+     * @remarks
+     * Optional initial rotation, in degrees, to set on the entity
+     * when it spawns.
+     *
+     */
     initialRotation?: number;
+    /**
+     * @remarks
+     * Optional spawn event to send to the entity after it is
+     * spawned.
+     *
+     */
+    spawnEvent?: string;
 }
 
 /**
@@ -21436,7 +21503,7 @@ export class NamespaceNameError extends Error {
 }
 
 /**
- * @beta
+ * @rc
  */
 // @ts-ignore Class inheritance allowed for native defined classes
 export class PlaceJigsawError extends Error {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minecraft/server",
-  "version": "2.0.0-beta.1.21.80-preview.26",
+  "version": "2.0.0-beta.1.21.80-preview.28",
   "description": "",
   "contributors": [
     {