@minecraft/server 2.11.0-rc.1.26.60-preview.28 → 2.11.0-rc.1.26.60-preview.29

package/index.d.ts

@@ -21214,6 +21214,13 @@ export class StartupEvent {
      *
      */
     readonly itemComponentRegistry: ItemComponentRegistry;
+    /**
+     * @rc
+     * @remarks
+     * @privilege early-execution-readable - This property can be read in early-execution mode.
+     *
+     */
+    readonly worldClockRegistry: WorldClockRegistry;
 }
 
 /**
@@ -22121,6 +22128,45 @@ export class TickingAreaManager {
     removeTickingArea(identifier: string | TickingArea): void;
 }
 
+/**
+ * @rc
+ * A named point in time on a world clock that can occur once
+ * or periodically.
+ */
+export class TimeMarker {
+    private constructor();
+    /**
+     * @remarks
+     * The identifier that represents this time marker.
+     *
+     */
+    readonly name: string;
+    /**
+     * @remarks
+     * The interval (in ticks) at which the time marker repeats. If
+     * not specified, the time marker will only occur once.
+     *
+     * @throws
+     * WorldClockInvalidTimeMarkerError: If the time marker is
+     * invalid.
+     *
+     * {@link WorldClockInvalidTimeMarkerError}
+     */
+    readonly period?: number;
+    /**
+     * @remarks
+     * The time (in ticks) that the time marker occurs at on a
+     * world clock.
+     *
+     * @throws
+     * WorldClockInvalidTimeMarkerError: If the time marker is
+     * invalid.
+     *
+     * {@link WorldClockInvalidTimeMarkerError}
+     */
+    readonly time: number;
+}
+
 /**
  * Represents a trigger for firing an event.
  */
@@ -22589,6 +22635,22 @@ export class World {
      * {@link minecraftcommon.InvalidArgumentError}
      */
     getAllPlayers(): Player[];
+    /**
+     * @rc
+     * @remarks
+     * Retrieves a world clock by its name.
+     *
+     * @param name
+     * The name of the world clock to retrieve.
+     * @returns
+     * The {@link WorldClock} with the given name.
+     * @throws
+     * WorldClockNotFoundError: If the world clock with the given
+     * name does not exist.
+     *
+     * {@link WorldClockNotFoundError}
+     */
+    getClock(name: string): WorldClock;
     /**
      * @remarks
      * Returns the current day.
@@ -23509,6 +23571,47 @@ export class WorldAfterEvents {
      *
      */
     readonly weatherChange: WeatherChangeAfterEventSignal;
+    /**
+     * @rc
+     * @remarks
+     * This event fires when a {@link WorldClock} is paused.
+     *
+     * @privilege early-execution-readable - This property can be read in early-execution mode.
+     *
+     */
+    readonly worldClockOnPaused: WorldClockOnPausedAfterEventSignal;
+    /**
+     * @rc
+     * @remarks
+     * This event fires when a {@link WorldClock} is resumed.
+     *
+     * @privilege early-execution-readable - This property can be read in early-execution mode.
+     *
+     */
+    readonly worldClockOnResumed: WorldClockOnResumedAfterEventSignal;
+    /**
+     * @rc
+     * @remarks
+     * This event fires when the time of a {@link WorldClock} hits
+     * a {@link TimeMarker} on the clock. This can happen during a
+     * regular level tick or when the time is set.
+     *
+     * @privilege early-execution-readable - This property can be read in early-execution mode.
+     *
+     */
+    readonly worldClockOnTimeMarker: WorldClockOnTimeMarkerAfterEventSignal;
+    /**
+     * @rc
+     * @remarks
+     * This event fires when a {@link WorldClock} time is changed.
+     * This can happen when the time is directly set through
+     * scripts or commands or when the clock reaches the maximum
+     * time and restarts.
+     *
+     * @privilege early-execution-readable - This property can be read in early-execution mode.
+     *
+     */
+    readonly worldClockOnTimeModified: WorldClockOnTimeModifiedAfterEventSignal;
     /**
      * @remarks
      * @privilege early-execution-readable - This property can be read in early-execution mode.
@@ -23633,6 +23736,451 @@ export class WorldBeforeEvents {
      *
      */
     readonly weatherChange: WeatherChangeBeforeEventSignal;
+    /**
+     * @rc
+     * @remarks
+     * This event fires when a {@link WorldClock} reaches its
+     * maximum time and is about to restart.
+     *
+     * @privilege early-execution-readable - This property can be read in early-execution mode.
+     *
+     */
+    readonly worldClockOnRestart: WorldClockOnRestartBeforeEventSignal;
+}
+
+/**
+ * @rc
+ * A class that represents a particular clock within a world.
+ */
+export class WorldClock {
+    private constructor();
+    /**
+     * @remarks
+     * Retrieves or sets whether the world clock is currently
+     * paused.
+     *
+     * @privilege restricted-execution-read-only - This property can't be edited in restricted-execution mode.
+     *
+     */
+    isPaused: boolean;
+    /**
+     * @remarks
+     * The identifier that represents this world clock.
+     *
+     */
+    readonly name: string;
+    /**
+     * @remarks
+     * Retrieves or sets the current time (in ticks) of the world
+     * clock.
+     *
+     * @privilege restricted-execution-read-only - This property can't be edited in restricted-execution mode.
+     *
+     * Minimum Value: 0
+     */
+    time: number;
+    /**
+     * @remarks
+     * Retrieves the current time markers of the world clock.
+     *
+     */
+    readonly timeMarkers: TimeMarker[];
+    /**
+     * @remarks
+     * Adds a new time marker to the world clock.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @param timeMarkerOptions
+     * Options for creating a time marker.
+     * @throws This function can throw errors.
+     *
+     * {@link WorldClockAddTimeMarkerError}
+     */
+    addTimeMarker(timeMarkerOptions: TimeMarkerOptions): void;
+    /**
+     * @remarks
+     * Removes an existing time marker from the world clock.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @param timeMarker
+     * The time marker or time marker name to remove.
+     * @throws
+     * WorldClockTimeMarkerNotFoundError: If the time marker does
+     * not exist on the world clock.
+     * WorldClockRemoveMinecraftTimeMarkerError: If the time marker
+     * uses the 'minecraft' namespace.
+     *
+     * {@link WorldClockRemoveMinecraftTimeMarkerError}
+     *
+     * {@link WorldClockTimeMarkerNotFoundError}
+     */
+    removeTimeMarker(timeMarker: string | TimeMarker): void;
+    /**
+     * @remarks
+     * Rewinds the world clock's time to the previous occurrence of
+     * the specified time marker.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @param timeMarker
+     * The time marker or time marker name to rewind the world
+     * clock's time to.
+     * @throws
+     * WorldClockTimeMarkerNotFoundError: If the time marker does
+     * not exist on the world clock.
+     * WorldClockRewindError: If the world clock's current time is
+     * before the time marker's first occurrence.
+     *
+     * {@link WorldClockRewindError}
+     *
+     * {@link WorldClockTimeMarkerNotFoundError}
+     */
+    rewindTo(timeMarker: string | TimeMarker): void;
+    /**
+     * @remarks
+     * Sets the world clock's time to the specified time marker.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @param timeMarker
+     * The time marker or time marker name to set the world clock's
+     * time to.
+     * @throws
+     * WorldClockTimeMarkerNotFoundError: If the time marker does
+     * not exist on the world clock.
+     *
+     * {@link WorldClockTimeMarkerNotFoundError}
+     */
+    set(timeMarker: string | TimeMarker): void;
+    /**
+     * @remarks
+     * Skips the world clock's time to the next occurrence of the
+     * specified time marker.
+     * If the next occurrence overflows the world clock's time, the
+     * time is reset to the first occurrence.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @param timeMarker
+     * The time marker or time marker name to skip the world
+     * clock's time to.
+     * @throws
+     * WorldClockTimeMarkerNotFoundError: If the time marker does
+     * not exist on the world clock.
+     *
+     * {@link WorldClockTimeMarkerNotFoundError}
+     */
+    skipTo(timeMarker: string | TimeMarker): void;
+}
+
+/**
+ * @rc
+ * Contains information related to a {@link WorldClock} being
+ * paused.
+ */
+export class WorldClockOnPausedAfterEvent {
+    private constructor();
+    /**
+     * @remarks
+     * The world clock that was paused.
+     *
+     */
+    readonly clock: WorldClock;
+}
+
+/**
+ * @rc
+ * Manages callbacks that are connected to a {@link WorldClock}
+ * being paused.
+ */
+export class WorldClockOnPausedAfterEventSignal {
+    private constructor();
+    /**
+     * @remarks
+     * Adds a callback that will be called when a world clock is
+     * paused.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     */
+    subscribe(
+        callback: (arg0: WorldClockOnPausedAfterEvent) => void,
+        options?: WorldClockEventOptions,
+    ): (arg0: WorldClockOnPausedAfterEvent) => void;
+    /**
+     * @remarks
+     * Removes a callback from being called when a world clock is
+     * paused.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     */
+    unsubscribe(callback: (arg0: WorldClockOnPausedAfterEvent) => void): void;
+}
+
+/**
+ * @rc
+ * Contains information related to a {@link WorldClock}
+ * restarting.
+ */
+export class WorldClockOnRestartBeforeEvent {
+    private constructor();
+    /**
+     * @remarks
+     * If set to true, cancels the world clock restart event. This
+     * will keep the world clock at the maximum time value and
+     * prevent it from ticking forward.
+     *
+     */
+    cancel: boolean;
+    /**
+     * @remarks
+     * The world clock that is restarting.
+     *
+     */
+    readonly clock: WorldClock;
+    /**
+     * @remarks
+     * The time that the world clock will be set to after it
+     * restarts. If not set, the world clock will be set to 0.
+     *
+     * Minimum Value: 0
+     */
+    newTime: number;
+}
+
+/**
+ * @rc
+ * Manages callbacks that are connected to a {@link WorldClock}
+ * restarting.
+ */
+export class WorldClockOnRestartBeforeEventSignal {
+    private constructor();
+    /**
+     * @remarks
+     * Adds a callback that will be called when a world clock is
+     * restarting.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     * @param callback
+     * This closure is called with restricted-execution privilege.
+     * @returns
+     * Closure that is called with restricted-execution privilege.
+     */
+    subscribe(
+        callback: (arg0: WorldClockOnRestartBeforeEvent) => void,
+        options?: WorldClockEventOptions,
+    ): (arg0: WorldClockOnRestartBeforeEvent) => void;
+    /**
+     * @remarks
+     * Removes a callback from being called when a world clock is
+     * restarting.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     * @param callback
+     * This closure is called with restricted-execution privilege.
+     */
+    unsubscribe(callback: (arg0: WorldClockOnRestartBeforeEvent) => void): void;
+}
+
+/**
+ * @rc
+ * Contains information related to a {@link WorldClock} being
+ * resumed.
+ */
+export class WorldClockOnResumedAfterEvent {
+    private constructor();
+    /**
+     * @remarks
+     * The world clock that was resumed.
+     *
+     */
+    readonly clock: WorldClock;
+}
+
+/**
+ * @rc
+ * Manages callbacks that are connected to a {@link WorldClock}
+ * being resumed.
+ */
+export class WorldClockOnResumedAfterEventSignal {
+    private constructor();
+    /**
+     * @remarks
+     * Adds a callback that will be called when a world clock is
+     * resumed.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     */
+    subscribe(
+        callback: (arg0: WorldClockOnResumedAfterEvent) => void,
+        options?: WorldClockEventOptions,
+    ): (arg0: WorldClockOnResumedAfterEvent) => void;
+    /**
+     * @remarks
+     * Removes a callback from being called when a world clock is
+     * resumed.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     */
+    unsubscribe(callback: (arg0: WorldClockOnResumedAfterEvent) => void): void;
+}
+
+/**
+ * @rc
+ * Contains information related to when the time of a
+ * {@link WorldClock} hits a {@link TimeMarker}.
+ */
+export class WorldClockOnTimeMarkerAfterEvent {
+    private constructor();
+    /**
+     * @remarks
+     * The world clock that hit a time marker.
+     *
+     */
+    readonly clock: WorldClock;
+    /**
+     * @remarks
+     * The time marker that was hit by the world clock.
+     *
+     */
+    readonly timeMarker: TimeMarker;
+}
+
+/**
+ * @rc
+ * Manages callbacks that are connected to when the time of a
+ * {@link WorldClock} hits a {@link TimeMarker}.
+ */
+export class WorldClockOnTimeMarkerAfterEventSignal {
+    private constructor();
+    /**
+     * @remarks
+     * Adds a callback that will be called when a world clock's
+     * time hits a time marker.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     */
+    subscribe(
+        callback: (arg0: WorldClockOnTimeMarkerAfterEvent) => void,
+        options?: WorldClockTimeMarkerEventOptions,
+    ): (arg0: WorldClockOnTimeMarkerAfterEvent) => void;
+    /**
+     * @remarks
+     * Removes a callback from being called when a world clock's
+     * time hits a time marker.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     */
+    unsubscribe(callback: (arg0: WorldClockOnTimeMarkerAfterEvent) => void): void;
+}
+
+/**
+ * @rc
+ * Contains information related to changes to the time of a
+ * {@link WorldClock}.
+ */
+export class WorldClockOnTimeModifiedAfterEvent {
+    private constructor();
+    /**
+     * @remarks
+     * The world clock that had its time modified.
+     *
+     */
+    readonly clock: WorldClock;
+}
+
+/**
+ * @rc
+ * Manages callbacks that are connected to changes to the time
+ * of a {@link WorldClock}.
+ */
+export class WorldClockOnTimeModifiedAfterEventSignal {
+    private constructor();
+    /**
+     * @remarks
+     * Adds a callback that will be called when a world clock's
+     * time is modified.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     */
+    subscribe(
+        callback: (arg0: WorldClockOnTimeModifiedAfterEvent) => void,
+        options?: WorldClockEventOptions,
+    ): (arg0: WorldClockOnTimeModifiedAfterEvent) => void;
+    /**
+     * @remarks
+     * Removes a callback from being called when a world clock's
+     * time is modified.
+     *
+     * @privilege no-restricted-execution - This function can't be called in restricted-execution mode.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     */
+    unsubscribe(callback: (arg0: WorldClockOnTimeModifiedAfterEvent) => void): void;
+}
+
+/**
+ * @rc
+ * Provides the functionality for registering custom world
+ * clocks. World clocks can only be registered during the
+ * system startup event.
+ */
+export class WorldClockRegistry {
+    private constructor();
+    /**
+     * @remarks
+     * Registers a new custom world clock. Must be called during
+     * the system startup event.
+     *
+     * @privilege early-execution-allowed - This function can be called in early-execution mode.
+     *
+     * @param name
+     * The name that represents this world clock. Must have a
+     * namespace and use only valid identifier characters. (e.g.,
+     * 'mypack:my_clock').
+     * @param registrationOptions
+     * Additional options for registering a world clock, such as
+     * including time markers at registration time.
+     * @throws This function can throw errors.
+     *
+     * {@link WorldClockInvalidRegistryError}
+     *
+     * {@link WorldClockRegistrationError}
+     *
+     * {@link WorldClockReloadNewWorldClockError}
+     *
+     * {@link WorldClockReloadTimeMarkerError}
+     */
+    registerClock(name: string, registrationOptions?: WorldClockRegistrationOptions): void;
 }
 
 export class WorldLoadAfterEvent {
@@ -26646,6 +27194,37 @@ export interface TickingAreaOptions {
     to: Vector3;
 }
 
+/**
+ * @rc
+ * Options for creating time markers for world clocks.
+ */
+export interface TimeMarkerOptions {
+    /**
+     * @remarks
+     * The name that the time marker will have. Must have a
+     * namespace and use only valid identifier characters. (e.g.,
+     * 'mypack:my_time_marker').
+     *
+     */
+    name: string;
+    /**
+     * @remarks
+     * The optional repeat period (in ticks) that the time marker
+     * will have. If not specified, the time marker will only occur
+     * once.
+     *
+     * Minimum Value: 0
+     */
+    period?: number;
+    /**
+     * @remarks
+     * The time (in ticks) that the time marker will occur at.
+     *
+     * Minimum Value: 0
+     */
+    time: number;
+}
+
 /**
  * Contains additional options for displaying a title and
  * optional subtitle.
@@ -26783,6 +27362,57 @@ export interface WaypointTextureSelector {
     textureBoundsList: WaypointTextureBounds[];
 }
 
+/**
+ * @rc
+ * Contains parameters for world clock events that filters out
+ * which events are passed to the provided callback.
+ */
+export interface WorldClockEventOptions {
+    /**
+     * @remarks
+     * The name of the clock that this event should fire for.
+     *
+     */
+    clock: string;
+}
+
+/**
+ * @rc
+ * Contains additional options for registering world clocks.
+ */
+export interface WorldClockRegistrationOptions {
+    /**
+     * @remarks
+     * Set of options to include time markers during world clock
+     * registration.
+     *
+     */
+    timeMarkers?: TimeMarkerOptions[];
+}
+
+/**
+ * @rc
+ * Contains parameters for world clock time marker events that
+ * filters out which events are passed to the provided
+ * callback.
+ */
+export interface WorldClockTimeMarkerEventOptions {
+    /**
+     * @remarks
+     * The name of the world clock that this event should fire for.
+     *
+     */
+    clock: string;
+    /**
+     * @remarks
+     * The name of the time marker that this event should fire for.
+     * If undefined, the event will fire for all time markers on
+     * the world clock.
+     *
+     */
+    timeMarker?: string;
+}
+
 /**
  * Contains additional options for a playSound occurrence.
  */
@@ -27248,6 +27878,111 @@ export class UnloadedChunksError extends Error {
     private constructor();
 }
 
+/**
+ * @rc
+ * Error thrown by {@link WorldClock.addTimeMarker} when
+ * failing to add a time marker to a world clock.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class WorldClockAddTimeMarkerError extends Error {
+    private constructor();
+}
+
+/**
+ * @rc
+ * Thrown when trying to register a world clock outside of the
+ * system startup event.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class WorldClockInvalidRegistryError extends Error {
+    private constructor();
+}
+
+/**
+ * @rc
+ * Error thrown when a time marker is invalid. This can occur
+ * when trying to access data on a time marker that has been
+ * removed.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class WorldClockInvalidTimeMarkerError extends Error {
+    private constructor();
+}
+
+/**
+ * @rc
+ * Error thrown when a world clock is not found in the world
+ * clock registry.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class WorldClockNotFoundError extends Error {
+    private constructor();
+}
+
+/**
+ * @rc
+ * Error thrown by {@link WorldClockRegistry.registerClock}
+ * when failing to register a world clock.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class WorldClockRegistrationError extends Error {
+    private constructor();
+}
+
+/**
+ * @rc
+ * Thrown after using the /reload command when trying to
+ * register a world clock that was not previously registered.
+ * New world clocks cannot be added during a reload.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class WorldClockReloadNewWorldClockError extends Error {
+    private constructor();
+}
+
+/**
+ * @rc
+ * Error thrown after using the /reload command when trying to
+ * re-register an existing world clock with an invalid time
+ * marker.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class WorldClockReloadTimeMarkerError extends Error {
+    private constructor();
+}
+
+/**
+ * @rc
+ * Error thrown by {@link WorldClock.removeTimeMarker} when
+ * trying to remove a time marker with the 'minecraft'
+ * namespace from a world clock.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class WorldClockRemoveMinecraftTimeMarkerError extends Error {
+    private constructor();
+}
+
+/**
+ * @rc
+ * Error thrown by {@link WorldClock.rewindTo} when the world
+ * clock's time is already before the time marker's first
+ * occurrence.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class WorldClockRewindError extends Error {
+    private constructor();
+}
+
+/**
+ * @rc
+ * Error thrown when performing actions on a world clock with a
+ * time marker that does not exist.
+ */
+// @ts-ignore Class inheritance allowed for native defined classes
+export class WorldClockTimeMarkerNotFoundError extends Error {
+    private constructor();
+}
+
 export const HudElementsCount = 13;
 export const HudVisibilityCount = 2;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minecraft/server",
-  "version": "2.11.0-rc.1.26.60-preview.28",
+  "version": "2.11.0-rc.1.26.60-preview.29",
   "description": "",
   "contributors": [
     {
@@ -14,7 +14,7 @@
   ],
   "peerDependencies": {
     "@minecraft/common": "^1.2.0",
-    "@minecraft/vanilla-data": ">=1.20.70 || 1.26.60-preview.28"
+    "@minecraft/vanilla-data": ">=1.20.70 || 1.26.60-preview.29"
   },
   "license": "MIT"
 }