fvtt-types/src/foundry/client/helpers/time.d.mts

TypeScript type definitions for Foundry VTT

import type { Identity } from "#utils";
import type CalendarData from "#client/data/calendar.mjs";

/**
 * A singleton class at which keeps the official Server and World time stamps.
 * Uses a basic implementation of https://www.geeksforgeeks.org/cristians-algorithm/ for synchronization.
 * @see {@linkcode foundry.Game.time | Game#time}
 */
declare class GameTime {
  constructor();

  /**
   * The amount of time to delay before re-syncing the official server time.
   * @defaultValue `1000 * 60 * 5`
   */
  static SYNC_INTERVAL_MS: number;

  /** The calendar instance for in-world timekeeping. */
  get calendar(): CalendarData<CalendarData.TimeComponents>;

  /** The "Earth" calendar instance for IRL timekeeping. */
  get earthCalendar(): CalendarData<CalendarData.TimeComponents>;

  /** The current server time based on the last synchronization point and the approximated one-way latency. */
  get serverTime(): number;

  /** The current World time expressed in seconds. */
  get worldTime(): number;

  /** The current World time expressed as components. */
  get components(): CalendarData.TimeComponents;

  /** The average one-way latency between client and server in milliseconds. */
  get averageLatency(): number;

  /**
   * Initialize a calendar configuration.
   * This is called once automatically upon construction, but can be called manually if `CONFIG.time` changes.
   */
  initializeCalendar(): void;

  /**
   * Advance or rewind the world time according to a delta amount expressed either in seconds or as components.
   * @param delta   - The number of seconds to advance (or rewind if negative) by
   * @param options - Additional options passed to `game.settings.set`
   * @returns The new game time
   */
  advance(
    delta: CalendarData.PartialTimeComponents | number,
    options?: foundry.helpers.ClientSettings.SetOptions,
  ): Promise<number>;

  /**
   * Directly set the world time to a certain value expressed either in seconds or as components.
   * @param time    - The desired world time
   * @param options - Additional options passed to `game.settings.set`
   * @returns The new game time
   */
  set(
    time: CalendarData.PartialTimeComponents | number,
    options?: foundry.helpers.ClientSettings.SetOptions,
  ): Promise<number>;

  /** Synchronize the local client game time with the official time kept by the server */
  sync(): Promise<this>;

  /**
   * Handle follow-up actions when the official World time is changed
   * @param worldTime - The new canonical World time.
   * @param options   - Options passed from the requesting client where the change was made
   * @param userId    - The ID of the User who advanced the time
   */
  onUpdateWorldTime(worldTime: number, options: Setting.Database.UpdateOperation, userId: string): void;

  #GameTime: true;
}

declare namespace GameTime {
  interface Any extends AnyGameTime {}
  interface AnyConstructor extends Identity<typeof AnyGameTime> {}
}

export default GameTime;

declare abstract class AnyGameTime extends GameTime {
  constructor(...args: never);
}