@minecraft/server 2.10.0-beta.1.26.40-preview.26 → 2.10.0-beta.1.26.40-preview.30

package/index.d.ts

@@ -220,6 +220,34 @@ export enum CameraShakeType {
     Rotational = 'Rotational',
 }
 
+/**
+ * @beta
+ * An enumeration for the clone modes used when cloning blocks.
+ */
+export enum CloneMode {
+    /**
+     * @remarks
+     * Clones the blocks from the source region to the destination,
+     * leaving the source intact.
+     *
+     */
+    Copy = 0,
+    /**
+     * @remarks
+     * Clones the blocks from the source region to the destination,
+     * allowing the source and destination regions to overlap.
+     *
+     */
+    ForceCopy = 1,
+    /**
+     * @remarks
+     * Clones the blocks from the source region to the destination
+     * and replaces the source region with air.
+     *
+     */
+    Move = 2,
+}
+
 /**
  * The required permission level to execute the custom command.
  */
@@ -5238,7 +5266,7 @@ export class BlockCustomComponentInstance extends BlockComponent {
  * pack, per block entity in their dynamic properties storage.
  * @example rememberPlayerInteraction.ts
  * ```typescript
- * import { system } from '@minecraft/server-wrapper';
+ * import { system } from '@minecraft/server-v2';
  *
  * system.beforeEvents.startup.subscribe(initEvent => {
  *   initEvent.blockComponentRegistry.registerCustomComponent('scripting_demo_pack:block_entity_onPlayerInteract', {
@@ -8376,6 +8404,72 @@ export class Dimension {
      *
      */
     readonly localizationKey: string;
+    /**
+     * @rc
+     * @remarks
+     * Calculates the location of the closest biome of a particular
+     * type from the world seed. Note that
+     * calculateClosestBiomeFromSeed can be an expensive operation,
+     * so avoid using many of these calls within a particular tick.
+     * The result is derived purely from the world generation
+     * algorithm and the world seed, so the returned location may
+     * not reflect the actual current terrain if biomes have been
+     * modified after generation.
+     *
+     * @param pos
+     * Starting location to look for a biome to find.
+     * @param biomeToFind
+     * Identifier of the biome to look for.
+     * @param options
+     * Additional selection criteria for a biome search.
+     * @returns
+     * Returns a location of the biome, or undefined if a biome
+     * could not be found.
+     * @throws This function can throw errors.
+     *
+     * {@link minecraftcommon.EngineError}
+     *
+     * {@link Error}
+     */
+    calculateClosestBiomeFromSeed(
+        pos: Vector3,
+        biomeToFind: BiomeType | string,
+        options?: BiomeSearchOptions,
+    ): Vector3 | undefined;
+    /**
+     * @beta
+     * @remarks
+     * Clones a region of blocks from one area of the dimension to
+     * another.
+     *
+     * This function can't be called in restricted-execution mode.
+     *
+     * @param beginLocation
+     * The lower northwest starting corner of the area to clone
+     * from.
+     * @param endLocation
+     * The upper southeast ending corner of the area to clone from.
+     * @param destination
+     * The lower northwest starting corner of the area to clone to.
+     * @param cloneMode
+     * Specifies how the cloned blocks should be placed at the
+     * destination.
+     * @param filter
+     * An optional block filter used to include only matching
+     * blocks from the source area.
+     * @throws This function can throw errors.
+     *
+     * {@link Error}
+     *
+     * {@link LocationOutOfWorldBoundariesError}
+     */
+    cloneBlocks(
+        beginLocation: Vector3,
+        endLocation: Vector3,
+        destination: Vector3,
+        cloneMode: CloneMode,
+        filter?: BlockFilter,
+    ): void;
     /**
      * @remarks
      * Checks if an area contains the specified biomes. If the area
@@ -8532,30 +8626,6 @@ export class Dimension {
         block: BlockPermutation | BlockType | string,
         options?: BlockFillOptions,
     ): ListBlockVolume;
-    /**
-     * @beta
-     * @remarks
-     * Finds the location of the closest biome of a particular
-     * type. Note that the findClosestBiome operation can take some
-     * time to complete, so avoid using many of these calls within
-     * a particular tick.
-     *
-     * @param pos
-     * Starting location to look for a biome to find.
-     * @param biomeToFind
-     * Identifier of the biome to look for.
-     * @param options
-     * Additional selection criteria for a biome search.
-     * @returns
-     * Returns a location of the biome, or undefined if a biome
-     * could not be found.
-     * @throws This function can throw errors.
-     *
-     * {@link minecraftcommon.EngineError}
-     *
-     * {@link Error}
-     */
-    findClosestBiome(pos: Vector3, biomeToFind: BiomeType | string, options?: BiomeSearchOptions): Vector3 | undefined;
     /**
      * @remarks
      * Returns the biome type at the specified location.
@@ -17481,7 +17551,7 @@ export class LootingEnchantFunction extends LootItemFunction {
 export class LootItem extends LootPoolEntry {
     private constructor();
     /**
-     * @beta
+     * @rc
      */
     readonly conditions: LootItemCondition[];
     readonly functions: LootItemFunction[];
@@ -18536,7 +18606,7 @@ export class Player extends Entity {
      * }
      * ```
      */
-    playSound(soundId: string, soundOptions?: PlayerSoundOptions): SoundInstance;
+    playSound(soundId: SoundDefinition | string, soundOptions?: PlayerSoundOptions): SoundInstance;
     /**
      * @beta
      * @remarks
@@ -20925,6 +20995,18 @@ export class PrimitiveShapesManager {
      * {@link PrimitiveShapeError}
      */
     addText(text: TextPrimitive, dimension?: Dimension): void;
+    /**
+     * @beta
+     * @remarks
+     * Fetches and queries all primitive shapes stored in the
+     * manager and returns the results as an array of shape
+     * handles.
+     *
+     * @param options
+     * Optional options for querying existing shapes to narrow down
+     * the results.
+     */
+    getShapes(options?: PrimitiveShapeQueryOptions): PrimitiveShape[];
     /**
      * @remarks
      * Removes all text primitives from the world.
@@ -22256,6 +22338,73 @@ export class SoundCompletedAfterEventSignal {
     unsubscribe(callback: (arg0: SoundCompletedAfterEvent) => void): void;
 }
 
+/**
+ * @beta
+ * Static metadata about a sound declared in a
+ * sound_definitions.json file.
+ */
+export class SoundDefinition {
+    private constructor();
+    /**
+     * @remarks
+     * Duration metadata declared for this sound. Undefined when
+     * the sound definition does not specify a duration.
+     *
+     */
+    readonly durationInfo?: SoundDefinitionDurationInfo;
+    /**
+     * @remarks
+     * Music metadata declared for this sound. Undefined when the
+     * sound definition does not specify a music_info block.
+     *
+     */
+    readonly musicInfo?: SoundDefinitionMusicInfo;
+    /**
+     * @remarks
+     * Identifier of the sound event this definition declares, in
+     * the form 'namespace:name'.
+     *
+     */
+    readonly soundEventId: string;
+    /**
+     * @remarks
+     * Tag metadata declared for this sound, as a record mapping
+     * each tag name to its declared values. A tag declared with a
+     * single string value is exposed as a single-element array.
+     * Undefined when the sound definition does not specify any
+     * tags.
+     *
+     */
+    readonly tags?: Record<string, string[]>;
+}
+
+/**
+ * @beta
+ * Provides read-only access to the sound definitions loaded
+ * for the current world.
+ */
+export class SoundDefinitionRegistry {
+    private constructor();
+    /**
+     * @remarks
+     * Returns the sound definitions in the registry, optionally
+     * narrowed by a filter.
+     *
+     * @param filter
+     * Optional filter applied to each definition. When omitted,
+     * every definition is returned.
+     * @returns
+     * All sound definitions matching the filter, or every sound
+     * definition when no filter is supplied.
+     * @throws
+     * An error will be thrown if filter.minDuration is greater
+     * than filter.maxDuration.
+     *
+     * {@link minecraftcommon.InvalidArgumentError}
+     */
+    getDefinitions(filter?: SoundDefinitionFilter): SoundDefinition[];
+}
+
 /**
  * @beta
  * Provides duration and playback information for a sound whose
@@ -22277,13 +22426,14 @@ export class SoundDurationInfo {
     readonly isActive: boolean;
     /**
      * @remarks
-     * Returns the elapsed playback time of the sound, in seconds,
-     * since it started playing.
+     * Returns the current playback position within the sound, in
+     * seconds, measured from the beginning of the sound.
      *
      * This function can't be called in restricted-execution mode.
      *
      * @returns
-     * Elapsed playback time in seconds.
+     * Current playback position in seconds, measured from the
+     * beginning of the sound.
      */
     getPlaybackPosition(): number;
 }
@@ -22373,7 +22523,12 @@ export class SoundInstance {
      *
      * @param seconds
      * Position to seek to in seconds. Must be non-negative.
-     * Minimum value: 0
+     * Bounds: [0, 107374184]
+     * @throws
+     * Throws if `seconds` is negative, or if the sound has a known
+     * duration and `seconds` is greater than that duration.
+     *
+     * {@link minecraftcommon.ArgumentOutOfBoundsError}
      */
     seekTo(seconds: number): void;
     /**
@@ -23876,6 +24031,14 @@ export class World {
      *
      */
     readonly seed: string;
+    /**
+     * @beta
+     * @remarks
+     * Provides read-only access to the sound definitions loaded
+     * for this world.
+     *
+     */
+    readonly soundDefinitionRegistry: SoundDefinitionRegistry;
     /**
      * @remarks
      * Returns the manager for {@link Structure} related APIs.
@@ -25142,7 +25305,7 @@ export interface BiomeFilter {
 }
 
 /**
- * @beta
+ * @rc
  * Contains additional options for searches for the
  * dimension.findNearestBiome API.
  */
@@ -27363,6 +27526,43 @@ export interface PlayerVisibilityRules extends EntityVisibilityRules {
     showSpectatorToSpectator?: boolean;
 }
 
+/**
+ * @beta
+ * Contains optional filters that control which primitive
+ * shapes are returned from a primitive shapes query.
+ */
+export interface PrimitiveShapeQueryOptions {
+    /**
+     * @remarks
+     * If specified, only returns shapes attached to this entity.
+     *
+     */
+    attachedTo?: Entity;
+    /**
+     * @remarks
+     * Adds a seed location to the query that is used in
+     * conjunction with distance properties.
+     *
+     */
+    location?: Vector3;
+    /**
+     * @remarks
+     * If specified, only includes shapes that are less than this
+     * distance away from the location specified in the location
+     * property.
+     *
+     */
+    maxDistance?: number;
+    /**
+     * @remarks
+     * If specified, only includes shapes that are at least this
+     * distance away from the location specified in the location
+     * property.
+     *
+     */
+    minDistance?: number;
+}
+
 /**
  * Key frame that holds the progress of the camera animation.
  */
@@ -27684,6 +27884,136 @@ export interface ScriptEventMessageFilterOptions {
     namespaces: string[];
 }
 
+/**
+ * @beta
+ * Duration metadata declared in a sound definition.
+ */
+export interface SoundDefinitionDurationInfo {
+    /**
+     * @remarks
+     * Total duration of the sound in seconds, as declared in the
+     * sound definition.
+     *
+     */
+    duration: number;
+}
+
+/**
+ * @beta
+ * Criteria used to narrow a set of sound definitions. Each
+ * field is optional and applies its constraint only when
+ * defined; a definition must satisfy every defined field to
+ * pass.
+ */
+export interface SoundDefinitionFilter {
+    /**
+     * @remarks
+     * Artist names to match against the definition's
+     * music_info.artist. Comparison is case-insensitive. When
+     * defined as a non-empty array, a definition passes only when
+     * its declared artist matches one of the supplied values. When
+     * undefined, no constraint on artist is applied.
+     *
+     */
+    artists?: string[];
+    /**
+     * @remarks
+     * Genres to match against the definition's music_info.genres.
+     * Comparison is case-insensitive. When defined as a non-empty
+     * array, a definition passes only when at least one of its
+     * declared genres matches one of the supplied values. When
+     * undefined, no constraint on genres is applied.
+     *
+     */
+    genres?: string[];
+    /**
+     * @remarks
+     * Upper bound in seconds, inclusive. When defined, definitions
+     * with a longer duration and definitions without a declared
+     * duration are excluded. When undefined, no upper bound is
+     * applied.
+     *
+     */
+    maxDuration?: number;
+    /**
+     * @remarks
+     * Lower bound in seconds, inclusive. When defined, definitions
+     * with a shorter duration and definitions without a declared
+     * duration are excluded. When undefined, no lower bound is
+     * applied.
+     *
+     */
+    minDuration?: number;
+    /**
+     * @remarks
+     * Moods to match against the definition's music_info.moods.
+     * Comparison is case-insensitive. When defined as a non-empty
+     * array, a definition passes only when at least one of its
+     * declared moods matches one of the supplied values. When
+     * undefined, no constraint on moods is applied.
+     *
+     */
+    moods?: string[];
+    /**
+     * @remarks
+     * Tag constraints to match against the definition's tags.
+     * Comparisons of tag names and values are case-insensitive.
+     * When defined as a non-empty record, a definition passes only
+     * when, for each entry with a non-empty value array, the tag
+     * name is present on the definition with at least one matching
+     * value. When undefined, no constraint on tags is applied.
+     *
+     */
+    tags?: Record<string, string[]>;
+    /**
+     * @remarks
+     * Titles to match against the definition's music_info.title.
+     * Comparison is case-insensitive. When defined as a non-empty
+     * array, a definition passes only when its declared title
+     * matches one of the supplied values. When undefined, no
+     * constraint on title is applied.
+     *
+     */
+    titles?: string[];
+}
+
+/**
+ * @beta
+ * Music metadata declared on a sound definition. Each field is
+ * optional and is undefined when the sound definition does not
+ * declare a value for it.
+ */
+export interface SoundDefinitionMusicInfo {
+    /**
+     * @remarks
+     * Artist declared for this sound. Undefined when no artist was
+     * declared.
+     *
+     */
+    artist?: string;
+    /**
+     * @remarks
+     * Genres declared for this sound. Undefined when no genres
+     * were declared.
+     *
+     */
+    genres?: string[];
+    /**
+     * @remarks
+     * Moods declared for this sound. Undefined when no moods were
+     * declared.
+     *
+     */
+    moods?: string[];
+    /**
+     * @remarks
+     * Title declared for this sound. Undefined when no title was
+     * declared.
+     *
+     */
+    title?: string;
+}
+
 /**
  * Contains additional options for spawning an Entity.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minecraft/server",
-  "version": "2.10.0-beta.1.26.40-preview.26",
+  "version": "2.10.0-beta.1.26.40-preview.30",
   "description": "",
   "contributors": [
     {
@@ -14,7 +14,7 @@
   ],
   "peerDependencies": {
     "@minecraft/common": "^1.2.0",
-    "@minecraft/vanilla-data": ">=1.20.70 || 1.26.40-preview.26"
+    "@minecraft/vanilla-data": ">=1.20.70 || 1.26.40-preview.30"
   },
   "license": "MIT"
 }