@minecraft/server 1.18.0 → 1.19.0-rc.1.21.80-preview.26

package/README.md

@@ -2,6 +2,8 @@
 
 Contains many types related to manipulating a Minecraft world, including entities, blocks, dimensions, and more.
 
+## **NOTE: This version of this module is still in pre-release.  It may change or it may be removed in future releases.**
+
 See full documentation for this module here:
 
-https://learn.microsoft.com/en-us/minecraft/creator/scriptapi/minecraft/server/minecraft-server
+https://learn.microsoft.com/en-us/minecraft/creator/legacyscriptapi/minecraft/server-1xx/minecraft-server

package/index.d.ts

@@ -7,6 +7,7 @@
    Copyright (c) Microsoft Corporation.
    ***************************************************************************** */
 /**
+ * @preview
  * @packageDocumentation
  * Contains many types related to manipulating a Minecraft
  * world, including entities, blocks, dimensions, and more.
@@ -15,7 +16,7 @@
  * ```json
  * {
  *   "module_name": "@minecraft/server",
- *   "version": "1.18.0"
+ *   "version": "1.19.0"
  * }
  * ```
  *
@@ -126,6 +127,38 @@ export enum CustomComponentNameErrorReason {
     DisallowedNamespace = 2,
 }
 
+/**
+ * @rc
+ * An enumeration for the various difficulty levels of
+ * Minecraft.
+ */
+export enum Difficulty {
+    /**
+     * @remarks
+     * Easy difficulty level.
+     *
+     */
+    Easy = 'Easy',
+    /**
+     * @remarks
+     * Hard difficulty level.
+     *
+     */
+    Hard = 'Hard',
+    /**
+     * @remarks
+     * Normal difficulty level.
+     *
+     */
+    Normal = 'Normal',
+    /**
+     * @remarks
+     * Peaceful difficulty level.
+     *
+     */
+    Peaceful = 'Peaceful',
+}
+
 /**
  * A general purpose relative direction enumeration.
  */
@@ -5403,6 +5436,58 @@ export class Dimension {
      * @throws This function can throw errors.
      */
     getTopmostBlock(locationXZ: VectorXZ, minHeight?: number): Block | undefined;
+    /**
+     * @rc
+     * @remarks
+     * Places the given feature into the dimension at the specified
+     * location.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param featureName
+     * The string identifier for the feature.
+     * @param location
+     * Location to place the feature.
+     * @param shouldThrow
+     * Specifies if the function call will throw an error if the
+     * feature could not be placed.
+     * Note: The function call will always throw an error if using
+     * an unknown feature name or trying to place in a unloaded
+     * chunk.
+     * @throws
+     * An error will be thrown if the feature name is invalid.
+     * An error will be thrown if the location is in an unloaded
+     * chunk.
+     *
+     * {@link Error}
+     *
+     * {@link minecraftcommon.InvalidArgumentError}
+     *
+     * {@link LocationInUnloadedChunkError}
+     */
+    placeFeature(featureName: string, location: Vector3, shouldThrow?: boolean): boolean;
+    /**
+     * @rc
+     * @remarks
+     * Places the given feature rule into the dimension at the
+     * specified location.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param featureRuleName
+     * The string identifier for the feature rule.
+     * @param location
+     * Location to place the feature rule.
+     * @throws
+     * An error will be thrown if the feature rule name is invalid.
+     * An error will be thrown if the location is in an unloaded
+     * chunk.
+     *
+     * {@link minecraftcommon.InvalidArgumentError}
+     *
+     * {@link LocationInUnloadedChunkError}
+     */
+    placeFeatureRule(featureRuleName: string, location: Vector3): boolean;
     /**
      * @remarks
      * Plays a sound for all players.
@@ -11039,8 +11124,9 @@ export class ItemStack {
      * @param componentId
      * The identifier of the component (e.g., 'minecraft:food'). If
      * no namespace prefix is specified, 'minecraft:' is assumed.
-     * Available component IDs can be found as part of the {@link
-     * ItemComponentTypes} enum.
+     * Available component IDs are those in the {@link
+     * ItemComponentTypes} enum and custom component IDs registered
+     * with the {@link ItemComponentRegistry}.
      * @returns
      * Returns the component if it exists on the item stack,
      * otherwise undefined.
@@ -12393,6 +12479,22 @@ export class Player extends Entity {
      * @throws This function can throw errors.
      */
     addLevels(amount: number): number;
+    /**
+     * @rc
+     * @remarks
+     * For this player, removes all overrides of any Entity
+     * Properties on the target Entity. This change is not applied
+     * until the next tick and will not apply to other players.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param targetEntity
+     * The Entity whose Entity Property overrides are being
+     * cleared.
+     * @throws
+     * Throws if the entity is invalid.
+     */
+    clearPropertyOverridesForEntity(targetEntity: Entity): void;
     /**
      * @remarks
      * Retrieves the active gamemode for this player, if specified.
@@ -12496,6 +12598,26 @@ export class Player extends Entity {
      *
      */
     queueMusic(trackId: string, musicOptions?: MusicOptions): void;
+    /**
+     * @rc
+     * @remarks
+     * For this player, removes the override on an Entity Property.
+     * This change is not applied until the next tick and will not
+     * apply to other players.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param targetEntity
+     * The Entity whose Entity Property override is being removed.
+     * @param identifier
+     * The Entity Property identifier.
+     * @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.
+     */
+    removePropertyOverrideForEntity(targetEntity: Entity, identifier: string): void;
     /**
      * @remarks
      * Resets the level of the player.
@@ -12515,6 +12637,10 @@ export class Player extends Entity {
      * This method can throw if the provided {@link RawMessage} is
      * in an invalid format. For example, if an empty `name` string
      * is provided to `score`.
+     *
+     * {@link InvalidEntityError}
+     *
+     * {@link RawMessageError}
      * @example nestedTranslation.ts
      * ```typescript
      * import { world, DimensionLocation } from "@minecraft/server";
@@ -12602,6 +12728,34 @@ export class Player extends Entity {
      * @throws This function can throw errors.
      */
     setGameMode(gameMode?: GameMode): void;
+    /**
+     * @rc
+     * @remarks
+     * For this player, overrides an Entity Property on the target
+     * Entity to the provided value. This property must be client
+     * synced. This change is not applied until the next tick and
+     * will not apply to other players.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param targetEntity
+     * The Entity whose Entity Property is being overriden.
+     * @param identifier
+     * The Entity Property identifier.
+     * @param value
+     * The override value. The provided type must be compatible
+     * with the type specified in the entity's definition.
+     * @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)
+     */
+    setPropertyOverrideForEntity(targetEntity: Entity, identifier: string, value: boolean | number | string): void;
     /**
      * @remarks
      * Sets the current starting spawn point for this particular
@@ -14420,6 +14574,8 @@ export class ScreenDisplay {
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
+     *
+     * {@link InvalidEntityError}
      */
     getHiddenHudElements(): HudElement[];
     /**
@@ -14427,6 +14583,8 @@ export class ScreenDisplay {
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
+     *
+     * {@link InvalidEntityError}
      */
     hideAllExcept(hudElements?: HudElement[]): void;
     /**
@@ -14434,6 +14592,8 @@ export class ScreenDisplay {
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
+     *
+     * {@link InvalidEntityError}
      */
     isForcedHidden(hudElement: HudElement): boolean;
     /**
@@ -14446,10 +14606,14 @@ export class ScreenDisplay {
      */
     isValid(): boolean;
     /**
+     * @deprecated This function is deprecated and will be removed in 2.0.0.
+     *
      * @remarks
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
+     *
+     * {@link InvalidEntityError}
      */
     resetHudElements(): void;
     /**
@@ -14462,6 +14626,10 @@ export class ScreenDisplay {
      * @param text
      * New value for the action bar text.
      * @throws This function can throw errors.
+     *
+     * {@link InvalidEntityError}
+     *
+     * {@link RawMessageError}
      */
     setActionBar(text: (RawMessage | string)[] | RawMessage | string): void;
     /**
@@ -14477,6 +14645,8 @@ export class ScreenDisplay {
      * @param hudElements
      * Optional list of HUD elements to configure visibility for.
      * @throws This function can throw errors.
+     *
+     * {@link InvalidEntityError}
      */
     setHudVisibility(visible: HudVisibility, hudElements?: HudElement[]): void;
     /**
@@ -14489,6 +14659,12 @@ export class ScreenDisplay {
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
+     *
+     * {@link minecraftcommon.ArgumentOutOfBoundsError}
+     *
+     * {@link InvalidEntityError}
+     *
+     * {@link RawMessageError}
      * @example setTitle.ts
      * ```typescript
      * import { world, DimensionLocation } from "@minecraft/server";
@@ -14554,6 +14730,10 @@ export class ScreenDisplay {
      * This function can't be called in read-only mode.
      *
      * @throws This function can throw errors.
+     *
+     * {@link InvalidEntityError}
+     *
+     * {@link RawMessageError}
      * @example countdown.ts
      * ```typescript
      * import { world, system, DimensionLocation } from "@minecraft/server";
@@ -15658,6 +15838,15 @@ export class World {
      * not fixed and will be determined by surrounding blocks.
      */
     getDefaultSpawnLocation(): Vector3;
+    /**
+     * @rc
+     * @remarks
+     * Gets the difficulty from the world.
+     *
+     * @returns
+     * Returns the world difficulty.
+     */
+    getDifficulty(): Difficulty;
     /**
      * @remarks
      * Returns a dimension object.
@@ -15945,6 +16134,17 @@ export class World {
      * {@link LocationOutOfWorldBoundariesError}
      */
     setDefaultSpawnLocation(spawnLocation: Vector3): void;
+    /**
+     * @rc
+     * @remarks
+     * Sets the worlds difficulty.
+     *
+     * This function can't be called in read-only mode.
+     *
+     * @param difficulty
+     * The difficulty we want to set the world to.
+     */
+    setDifficulty(difficulty: Difficulty): void;
     /**
      * @remarks
      * Sets a specified property to a value.
@@ -16654,6 +16854,40 @@ export class WorldInitializeBeforeEventSignal {
     unsubscribe(callback: (arg0: WorldInitializeBeforeEvent) => void): void;
 }
 
+/**
+ * @rc
+ * A BlockBoundingBox is an interface to an object which
+ * represents an AABB aligned rectangle.
+ * The BlockBoundingBox assumes that it was created in a valid
+ * state (min <= max) but cannot guarantee it (unless it was
+ * created using the associated {@link
+ * @minecraft/server.BlockBoundingBoxUtils} utility functions.
+ * The min/max coordinates represent the diametrically opposite
+ * corners of the rectangle.
+ * The BlockBoundingBox is not a representation of blocks - it
+ * has no association with any type, it is just a mathematical
+ * construct - so a rectangle with
+ * ( 0,0,0 ) -> ( 0,0,0 )
+ * has a size of ( 0,0,0 ) (unlike the very similar {@link
+ * BlockVolume} object)
+ */
+export interface BlockBoundingBox {
+    /**
+     * @remarks
+     * A {@link Vector3} that represents the largest corner of the
+     * rectangle
+     *
+     */
+    max: Vector3;
+    /**
+     * @remarks
+     * A {@link Vector3} that represents the smallest corner of the
+     * rectangle
+     *
+     */
+    min: Vector3;
+}
+
 /**
  * Contains a set of events that will be raised for a block.
  * This object must be bound using the BlockRegistry.
@@ -18723,6 +18957,11 @@ export class NamespaceNameError extends Error {
     reason: NamespaceNameErrorReason;
 }
 
+// @ts-ignore Class inheritance allowed for native defined classes
+export class RawMessageError extends Error {
+    private constructor();
+}
+
 /**
  * Error thrown when the specified area contains one or more
  * unloaded chunks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minecraft/server",
-  "version": "1.18.0",
+  "version": "1.19.0-rc.1.21.80-preview.26",
   "description": "",
   "contributors": [
     {