@7h3laughingman/foundry-types 13.351.0

package/src/client/helpers/media/image-helper.d.mts

@@ -0,0 +1,116 @@
+import { ImageFilePath } from "./../../../common/constants.mjs";
+
+/**
+ * A helper class to provide common functionality for working with Image objects
+ */
+export default class ImageHelper {
+    /**
+     * Create thumbnail preview for a provided image path.
+     * @param src               The URL or display object of the texture to render to a thumbnail
+     * @param options           Additional named options passed to the compositeCanvasTexture function
+     * @param [options.width]   The desired width of the resulting thumbnail
+     * @param [options.height]  The desired height of the resulting thumbnail
+     * @param [options.tx]      A horizontal transformation to apply to the provided source
+     * @param [options.ty]      A vertical transformation to apply to the provided source
+     * @param [options.center]  Whether to center the object within the thumbnail
+     * @param [options.format]  The desired output image format
+     * @param [options.quality] The desired output image quality
+     * @returns The parsed and converted thumbnail data
+     */
+    static createThumbnail(
+        src: string | PIXI.DisplayObject,
+        options: {
+            width?: number;
+            height?: number;
+            tx?: number;
+            ty?: number;
+            center?: boolean;
+            format: string;
+            quality: number;
+        },
+    ): Promise<object>;
+
+    /**
+     * Test whether a source file has a supported image extension type
+     * @param src      A requested image source path
+     * @returns       Does the filename end with a valid image extension?
+     */
+    static hasImageExtension(src: string): src is ImageFilePath;
+
+    /**
+     * Composite a canvas object by rendering it to a single texture
+     *
+     * @param object            The object to render to a texture
+     * @param options           Options which configure the resulting texture
+     * @param [options.width]   The desired width of the output texture
+     * @param [options.height]  The desired height of the output texture
+     * @param [options.tx]      A horizontal translation to apply to the object
+     * @param [options.ty]      A vertical translation to apply to the object
+     * @param [options.center]  Center the texture in the rendered frame?
+     *
+     * @returns The composite Texture object
+     */
+    static compositeCanvasTexture(
+        object: PIXI.DisplayObject,
+        options?: { width?: number; height?: number; tx?: number; ty?: number; center?: boolean },
+    ): PIXI.Texture;
+
+    /**
+     * Extract a texture to a base64 PNG string
+     * @param texture           The texture object to extract
+     * @param options
+     * @param [options.format]  Image format, e.g. "image/jpeg" or "image/webp".
+     * @param [options.quality] JPEG or WEBP compression from 0 to 1. Default is 0.92.
+     * @returns A base64 png string of the texture
+     */
+    static textureToImage(texture: PIXI.Texture, options?: { format: string; quality: number }): Promise<string>;
+
+    /**
+     * Asynchronously convert a DisplayObject container to base64 using Canvas#toBlob and FileReader
+     * @param target    A PIXI display object to convert
+     * @param type      The requested mime type of the output, default is image/png
+     * @param quality   A number between 0 and 1 for image quality if image/jpeg or image/webp
+     * @returns A processed base64 string
+     */
+    static pixiToBase64(target: PIXI.DisplayObject, type: string, quality: number): Promise<string>;
+
+    /**
+     * Asynchronously convert a canvas element to base64.
+     * @param {HTMLCanvasElement} canvas
+     * @param [type="image/png"]
+     * @param quality
+     * @returns The base64 string of the canvas.
+     */
+    static canvasToBase64(canvas: HTMLCanvasElement, type: string, quality?: number): Promise<string>;
+
+    /**
+     * Upload a base64 image string to a persisted data storage location
+     * @param base64                    The base64 string
+     * @param fileName                  The file name to upload
+     * @param filePath                  The file path where the file should be uploaded
+     * @param options                   Additional options which affect uploading
+     * @param [options.storage=data]    The data storage location to which the file should be uploaded
+     * @param [options.type]            The MIME type of the file being uploaded
+     * @param [options.notify=true]     Display a UI notification when the upload is processed.
+     * @returns A promise which resolves to the FilePicker upload response
+     */
+    static uploadBase64(base64: string, fileName: string, filePath: string, options?: { storage?: string; type?: string; notify?: boolean }): Promise<object>;
+
+    /**
+     * Create a canvas element containing the pixel data.
+     * @param pixels            Buffer used to create the image data.
+     * @param width             Buffered image width.
+     * @param height            Buffered image height.
+     * @param options
+     * @param [options.element] The element to use.
+     * @param [options.ew]      Specified width for the element (default to buffer image width).
+     * @param [options.eh]      Specified height for the element (default to buffer image height).
+     * @returns
+     */
+    static pixelsToCanvas(
+        pixels: Uint8ClampedArray,
+        width: number,
+        height: number,
+        options?: { element?: HTMLCanvasElement; ew?: number; eh?: number },
+    ): HTMLCanvasElement;
+}

package/src/client/helpers/media/video-helper.d.mts

@@ -0,0 +1,113 @@
+import { ImageFileExtension, VideoFilePath } from "./../../../common/constants.mjs";
+import SpriteMesh from "./../../canvas/containers/elements/sprite-mesh.mjs";
+
+/**
+ * A helper class to provide common functionality for working with HTML5 video objects
+ * A singleton instance of this class is available as ``game.video``
+ */
+export default class VideoHelper {
+    constructor();
+
+    /**
+     * A user gesture must be registered before video playback can begin.
+     * This Set records the video elements which await such a gesture.
+     */
+    pending: Set<HTMLVideoElement>;
+
+    /** A mapping of base64 video thumbnail images */
+    thumbs: Map<string, string>;
+
+    /** A flag for whether video playback is currently locked by awaiting a user gesture */
+    locked: boolean;
+
+    /* -------------------------------------------- */
+    /*  Methods                                     */
+    /* -------------------------------------------- */
+
+    /**
+     * Return the HTML element which provides the source for a loaded texture.
+     * @param mesh The rendered mesh
+     * @returns The source HTML element
+     */
+    getSourceElement(mesh: PIXI.Sprite | SpriteMesh): HTMLImageElement | HTMLVideoElement | null;
+
+    /**
+     * Get the video element source corresponding to a Sprite or SpriteMesh.
+     * @param object The PIXI source
+     * @returns The source video element or null
+     */
+    getVideoSource(object: PIXI.Sprite | SpriteMesh | PIXI.Texture): HTMLVideoElement | null;
+
+    /**
+     * Clone a video texture so that it can be played independently of the original base texture.
+     * @param {HTMLVideoElement} source     The video element source
+     * @returns {Promise<PIXI.Texture>}     An unlinked PIXI.Texture which can be played independently
+     */
+    cloneTexture(source: HTMLVideoElement): Promise<PIXI.Texture>;
+
+    /**
+     * Check if a source has a video extension.
+     * @param src The source.
+     * @returns If the source has a video extension or not.
+     */
+    static hasVideoExtension(src: string): src is VideoFilePath;
+
+    /**
+     * Play a single video source
+     * If playback is not yet enabled, add the video to the pending queue
+     * @param video        The VIDEO element to play
+     * @param [options={}] Additional options for modifying video playback
+     * @param [options.playing] Should the video be playing? Otherwise, it will be paused
+     * @param [options.loop]    Should the video loop?
+     * @param [options.offset]  A specific timestamp between 0 and the video duration to begin playback
+     * @param [options.volume]  Desired volume level of the video's audio channel (if any)
+     */
+    play(video: HTMLVideoElement, options?: VideoPlayOptions): Promise<void>;
+
+    /**
+     * Stop a single video source
+     * @param video The VIDEO element to stop
+     */
+    stop(video: HTMLVideoElement): void;
+
+    /**
+     * Register an event listener to await the first mousemove gesture and begin playback once observed
+     * A user interaction must involve a mouse click or keypress.
+     * Listen for any of these events, and handle the first observed gesture.
+     */
+    awaitFirstGesture(): void;
+
+    /**
+     * Handle the first observed user gesture
+     * We need a slight delay because unfortunately Chrome is stupid and doesn't always acknowledge the gesture fast enough.
+     * @param event The mouse-move event which enables playback
+     */
+    protected _onFirstGesture(event: Event): void;
+
+    /**
+     * Create and cache a static thumbnail to use for the video.
+     * The thumbnail is cached using the video file path or URL.
+     * @param src     The source video URL
+     * @param options Thumbnail creation options, including width and height
+     * @return The created and cached base64 thumbnail image, or a placeholder image if the canvas is
+     *         disabled and no thumbnail can be generated.
+     */
+    createThumbnail(src: string, options: CreateThumbnailOptions): Promise<string>;
+}
+
+interface VideoPlayOptions {
+    playing?: boolean;
+    loop?: boolean;
+    offset?: number;
+    volume?: number;
+}
+
+interface CreateThumbnailOptions {
+    width: number;
+    height: number;
+    tx?: number;
+    ty?: number;
+    center?: boolean;
+    format?: ImageFileExtension;
+    quality?: number;
+}

package/src/client/helpers/socket-interface.d.mts

@@ -0,0 +1,14 @@
+import { SocketResponse } from "./../../common/_types.mjs";
+
+/**
+ * A standardized way socket messages are dispatched and their responses are handled
+ */
+export default class SocketInterface {
+    /**
+     * Send a socket request to all other clients and handle their responses.
+     * @param eventName The socket event name being handled
+     * @param request Request data provided to the Socket event
+     * @returns A Promise which resolves to the SocketResponse
+     */
+    static dispatch(eventName: string, request: object): Promise<SocketResponse>;
+}

package/src/client/helpers/time.d.mts

@@ -0,0 +1,92 @@
+import { CalendarData, TimeComponents } from "./../data/_module.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 {@link Game#time}
+ */
+export default class GameTime {
+    constructor();
+
+    /* -------------------------------------------- */
+    /*  Properties                                  */
+    /* -------------------------------------------- */
+
+    /**
+     * The calendar instance for in-world timekeeping.
+     */
+    get calendar(): CalendarData;
+
+    /**
+     * The "Earth" calendar instance for IRL timekeeping.
+     */
+    get earthCalendar(): CalendarData;
+
+    /**
+     * 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.
+     * @type {}
+     */
+    get components(): TimeComponents;
+
+    /**
+     * The average one-way latency between client and server in milliseconds.
+     */
+    get averageLatency(): number;
+
+    /* -------------------------------------------- */
+    /*  Methods                                     */
+    /* -------------------------------------------- */
+
+    /**
+     * 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: TimeComponents | number, options?: object): 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: TimeComponents | number, options?: object): Promise<number>;
+
+    /* -------------------------------------------- */
+    /*  Synchronization and Update Methods          */
+    /* -------------------------------------------- */
+
+    /**
+     * Synchronize the local client game time with the official time kept by the server
+     */
+    sync(): Promise<this>;
+
+    /* -------------------------------------------- */
+    /*  Event Handlers and Callbacks                */
+    /* -------------------------------------------- */
+
+    /**
+     * 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: object, userId: string): void;
+}

package/src/client/helpers/workers.d.mts

@@ -0,0 +1,92 @@
+interface WorkerTask {
+    /** An incrementing task ID used to reference task progress */
+    taskId?: number;
+    /** The task action being performed, from WorkerManager.WORKER_TASK_ACTIONS */
+    action: (typeof WorkerManager.WORKER_TASK_ACTIONS)[keyof typeof WorkerManager.WORKER_TASK_ACTIONS];
+}
+
+interface AsyncWorkerOptions extends WorkerOptions {
+    /** Should the worker run in debug mode? */
+    debug?: boolean;
+    /** Should the worker automatically load the primitives library? */
+    loadPrimitives?: boolean;
+    /** Should the worker operates in script modes? Optional scripts. */
+    scripts?: string[];
+}
+
+/**
+ * An asynchronous web Worker which can load user-defined functions and await execution using Promises.
+ */
+export class AsyncWorker extends Worker {
+    /**
+     * @param name    The worker name to be initialized
+     * @param options Worker initialization options
+     */
+    constructor(name: string, options?: AsyncWorkerOptions);
+
+    /**
+     * A path reference to the JavaScript file which provides companion worker-side functionality.
+     */
+    static WORKER_HARNESS_JS: string;
+
+    /**
+     * A Promise which resolves once the Worker is ready to accept tasks
+     */
+    get ready(): Promise<void>;
+
+    /* -------------------------------------------- */
+    /*  Task Management                             */
+    /* -------------------------------------------- */
+
+    /**
+     * Load a function onto a given Worker.
+     * The function must be a pure function with no external dependencies or requirements on global scope.
+     * @param functionName The name of the function to load
+     * @param functionRef  A reference to the function that should be loaded
+     * @returns A Promise which resolves once the Worker has loaded the function.
+     */
+    loadFunction(functionName: string, functionRef: Function): Promise<unknown>;
+
+    /**
+     * Execute a task on a specific Worker.
+     * @param functionName The named function to execute on the worker. This function must first have been loaded.
+     * @param args An array of parameters with which to call the requested function
+     * @param transfer An array of transferable objects which are transferred to the worker thread.
+     *                 See https://developer.mozilla.org/en-US/docs/Glossary/Transferable_objects
+     * @returns A Promise which resolves with the returned result of the function once complete.
+     */
+    executeFunction(functionName: string, args?: unknown[], transfer?: object[]): Promise<unknown>;
+}
+
+/**
+ * A client-side class responsible for managing a set of web workers.
+ * This interface is accessed as a singleton instance via game.workers.
+ * @see Game#workers
+ */
+export class WorkerManager extends Map<string, AsyncWorker> {
+    constructor();
+
+    /**
+     * Supported worker task actions
+     */
+    static WORKER_TASK_ACTIONS: Readonly<{ INIT: "init"; LOAD: "load"; EXECUTE: "execute" }>;
+
+    /* -------------------------------------------- */
+    /*  Worker Management                           */
+    /* -------------------------------------------- */
+
+    /**
+     * Create a new named Worker.
+     * @param name   The named Worker to create
+     * @param config Worker configuration parameters passed to the AsyncWorker constructor
+     * @returns The created AsyncWorker which is ready to accept tasks
+     */
+    createWorker(name: string, config?: AsyncWorkerOptions): Promise<AsyncWorker>;
+
+    /**
+     * Retire a current Worker, terminating it immediately.
+     * @see Worker#terminate
+     * @param name The named worker to terminate
+     */
+    retireWorker(name: string): void;
+}

package/src/client/nue/_module.d.mts

@@ -0,0 +1,13 @@
+/** @module nue */
+
+import Tour from "./tour.mjs";
+import * as tours from "./tours/_module.mjs";
+
+export { default as NewUserExperienceManager } from "./nue-manager.mjs";
+export { default as ToursCollection } from "./tours-collection.mjs";
+export { Tour, tours };
+
+/**
+ * Register core Tours.
+ */
+export function registerTours(): Promise<void>;

package/src/client/nue/nue-manager.d.mts

@@ -0,0 +1,13 @@
+/**
+ * Responsible for managing the New User Experience workflows.
+ * @see {@link foundry.Game#nue}
+ */
+export default class NewUserExperienceManager {
+    constructor();
+
+    /**
+     * Initialize the new user experience.
+     * Currently, this generates some chat messages with hints for getting started if we detect this is a new world.
+     */
+    initialize(): void;
+}