gameforge/dist/index.d.mts

Lightweight HTML5 boilerplate for quick 2D game prototyping

import { Ticker, AnimatedSprite, Texture, Sprite, Container, DisplayObjectEvents, Color, Point } from 'pixi.js';
import * as pixi_js from 'pixi.js';
export { pixi_js as Pixi };
import * as sound from '@pixi/sound';
export { sound as PixiSound };
export { default as WebFontLoader } from 'webfontloader';
import { ArgumentMap } from 'eventemitter3';

type Transition = (ratio: number) => number;
declare const Transitions: {
    linear: Transition;
    easeIn: Transition;
    easeOut: Transition;
    easeInOut: Transition;
};

/**
 * Configuration object for the Tween class.
 */
type TweenConfig<T> = {
    /**
     * The target object.
     */
    target: T;
    /**
     * Duration of the tween in milliseconds.
     */
    duration: number;
    /**
     * Delay in milliseconds before the tween starts.
     */
    delay: number;
    /**
     * Easing/transition function.
     */
    transition: Transition;
    /**
     * Callback when tween finishes.
     */
    onComplete: () => void;
    /**
     * PixiJS's Ticker used for updates.
     */
    ticker: Ticker;
};
/**
 * A generic tweening class that animates numeric properties
 * of an object over time using PixiJS's Ticker.
 */
declare class Tween<T> {
    private _target;
    private _duration;
    private _delay;
    private _transition;
    private _onComplete;
    private readonly _ticker;
    private readonly _startValues;
    private readonly _endValues;
    private _elapsedTime;
    private _isComplete;
    /**
     * Gets the object being animated by the tween.
     */
    get target(): T;
    /**
     * Gets the duration of the tween.
     */
    get duration(): number;
    /**
     * Gets the delay before the tween starts.
     */
    get delay(): number;
    /**
     * Gets the easing/transtion function of the tween.
     */
    get transition(): Transition;
    /**
     * Indicates whether the tween has finished playing.
     */
    get isComplete(): boolean;
    /**
     * Creates a new Tween instance with optional configuration.
     *
     * @param config The tween's configuration.
     */
    constructor(config?: Partial<TweenConfig<T>>);
    /**
     * Sets the target object to be animated by the tween.
     *
     * @param target The object to animate.
     * @returns The current Tween instance for chaining.
     */
    setTarget(target: T): this;
    /**
     * Sets the total duration of the tween.
     *
     * @param duration Duration in milliseconds.
     * @returns The current Tween instance for chaining.
     */
    setDuration(duration: number): this;
    /**
     * Sets the delay before the tween starts.
     *
     * @param delay Delay in milliseconds.
     * @returns The current Tween instance for chaining.
     */
    setDelay(delay: number): this;
    /**
     * Sets the easing/transition function of the tween.
     *
     * @param transition The easing/transition function.
     * @returns The current Tween instance for chaining.
     */
    setTransition(transition: Transition): this;
    /**
     * Sets a callback of the tween.
     *
     * @param onComplete A function to call when the tween finishes
     * @returns The current Tween instance for chaining.
     */
    onComplete(onComplete: () => void): this;
    /**
     * Adds an animation for a specific numeric property of the target.
     *
     * @param property The property key to animate.
     * @param endValue The final value for the property.
     */
    animate<K extends keyof T>(property: K, endValue: number): this;
    /**
     * Starts the tween animation.
     */
    play<K extends keyof T>(): void;
    /**
     * Stops the tween immediately, sets target properties to end values,
     * and calls the completion callback.
     */
    stop<K extends keyof T>(): void;
    /**
     * Update function called on every ticker frame.
     * Handles time progression, easing, and property interpolation.
     */
    private readonly update;
    /**
     * Merges user-provided configuration with defaults.
     *
     * @param config The user-provided configuration.
     * @returns The merged configuration.
     */
    private static parseConfig;
}

declare enum SceneEvent {
    EVENT = "sceneevent"
}

/**
 * A simple button implementation based on `Pixi.AnimatedSprite`.
 */
declare class Button extends AnimatedSprite {
    /**
     * Creates a new Button instance with the given textures.
     *
     * @param textures The textures to be used for the button.
     */
    constructor(...textures: Texture[]);
    /**
     * Disables the button, preventing it from receiving pointer events.
     *
     * @param hide If set to `true`, the button will also be hidden.
     *             Defaults to `false`, meaning the button stays visible.
     */
    disable(hide?: boolean): void;
    /**
     * Enables the button, allowing it to receive pointer events
     * and making it visible.
     */
    enable(): void;
}

/**
 * A simple panel implementation based on `Pixi.Sprite`.
 */
declare class Panel extends Sprite {
    /**
     * Creates a new Panel instance.
     *
     * @param texture The texture to be used for the panel's background.
     */
    constructor(texture?: Texture);
    /**
     * Disables the panel, preventing it from receiving pointer events.
     *
     * @param hide If set to `true`, the panel will also be hidden.
     *             Defaults to `false`, meaning the panel stays visible.
     */
    disable(hide?: boolean): void;
    /**
     * Enables the panel, allowing it to receive pointer events
     * and making it visible.
     */
    enable(): void;
}

/**
 * A simple scene implementation based on `Pixi.Container`.
 */
declare class Scene extends Container {
    /**
     * Creates a new Scene instance with the given name.
     *
     * @param name The name of the scene.
     */
    constructor(name: string);
    /**
     * @override
     * Add a listener for a given event.
     * Supports the custom SceneEvent.CHANGE.
     */
    on(event: keyof DisplayObjectEvents | SceneEvent.EVENT, fn: (...args: any) => void, context?: any): this;
    /**
     * @override
     * Calls each of the listeners registered for a given event.
     * Supports the custom SceneEvent.CHANGE.
     */
    emit<T extends keyof DisplayObjectEvents>(event: T | SceneEvent.EVENT, ...args: ArgumentMap<DisplayObjectEvents>[Extract<T, keyof DisplayObjectEvents>]): boolean;
    /**
     * Lifecycle method called when the scene is entered.
     */
    onEnter(): void;
    /**
     * Lifecycle method called when the scene is exited.
     */
    onExit(): void;
}

/**
 * Manages scenes within a Pixi stage.
 */
declare class SceneManager {
    private readonly _stage;
    private readonly _scenes;
    private _current?;
    /**
     * Creates a new SceneManager instance.
     *
     * @param stage The root display container of the application.
     */
    constructor(stage: Container);
    /**
     * Adds a scene to the manager and the stage.
     *
     * @param scene The scene instance to add.
     */
    addScene(scene: Scene): void;
    /**
     * Switches the current active scene to the one with the given name.
     *
     * @param name The name of the scene to activate.
     */
    setScene(name: string): void;
}

declare class Binder {
    protected _prev: Binder;
    protected _next: Binder;
    /**
     * Gets the previous Binder in the chain.
     */
    get prev(): Binder;
    /**
     * Gets the next Binder in the chain.
     */
    get next(): Binder;
    /**
     * Creates a new Binder instance.
     *
     * Each Binder stats as a self-referencing circular node
     * (`prev = this`, `next = this`);
     */
    constructor();
    /**
     * Binds the given Binder right after this one in the chain.
     *
     * @param next The Binder to insert after the current one.
     */
    bind(next: Binder): void;
    /**
     * Unbinds this Binder instance from the chain.
     */
    unbind(): void;
}

declare class Item<T> extends Binder {
    protected _data: T;
    /**
     * Gets the data stored in this item.
     */
    get data(): T;
    /**
     * Creates a new Item instance with the given data.
     *
     * @param data The data to store in this item.
     */
    constructor(data: T);
    /**
     * Converts a value or an Item into an Item instance.
     *
     * If the given value is already an Item, it is returned unchanged.
     * Otherwise, a new Item is created to wrap the value.
     *
     * @param value Either a raw value of type K or an Item<K>.
     * @returns An Item<K> instance.
     */
    static parse<K>(value: K | Item<K>): Item<K>;
}

/**
 * Represends a generic doubly-linked list.
 */
declare class List<T> {
    private readonly _head;
    private readonly _tail;
    private _length;
    /**
     * Gets the first element in the list,
     * or `undefined` if the list is empty.
     */
    get first(): Item<T> | undefined;
    /**
     * Gets the last element in the list,
     * or `undefined` if the list is empty.
     */
    get last(): Item<T> | undefined;
    /**
     * Gets the number of elements in the list.
     */
    get length(): number;
    /**
     * Creates a new empty List<T> instance.
     */
    constructor();
    /**
     * Inserts a new element at the beginning of the list.
     *
     * @param element The element to insert.
     * @returns The created Item wrapping the element.
     */
    unshift(element: T): Item<T>;
    /**
     * Inserts a new element to the end of the list.
     *
     * @param element The element to insert.
     * @returns The created Item wrapping the element.
     */
    push(element: T): Item<T>;
    /**
     * Removes and returns the first element of the list.
     *
     * @returns The removed Item, or `undefined` if the list is empty.
     */
    shift(): Item<T> | undefined;
    /**
     * Removes and returns the last element of the list.
     *
     * @returns The removed Item, or `undefined` if the list is empty.
     */
    pop(): Item<T> | undefined;
    /**
     * Removes all elements from the list.
     */
    clear(): void;
    /**
     * Finds the first item whose stored value mathes the given element.
     *
     * @param element The value to search for.
     * @returns The matching Item, or `undefined` if not found.
     */
    find(element: T): Item<T> | undefined;
    /**
     * Determines whether the list contains the specified element.
     *
     * @param element The value to check for.
     * @returns True if the element is found, otherwise false.
     */
    contains(element: T): boolean;
    /**
     * Performs the specified action for each element in a list.
     *
     * @param callbackfn A function that accepts up to three arguments. forEach calls
     * the callbackfn function one time for each element in the list.
     * @param thisArg An object to which the this keyword can refer in the
     * callbackfn function. If thisArg is omitted, undefined is used as the
     * this value.
     */
    forEach(callbackfn: (value: T, i: number, list: List<T>) => void, thisArg?: any): void;
    /**
     * Calls a defined callback function on each element of a list, and returns
     * a list that contains the results.
     *
     * @param callbackfn A function that accepts up to three arguments. The map
     * method calls the callbackfn function one time for each element in the list.
     * @param thisArg An object to which the this keyword can refer in the
     * callbackfn function. If thisArg is omitted, undefined is used as the this
     * value.
     */
    map<U>(callbackfn: (value: T, index: number, list: List<T>) => U, thisArg?: any): List<U>;
    /**
     * Returns an iterator over the list items.
     */
    [Symbol.iterator](): IterableIterator<Item<T>>;
    private link;
    private unlink;
}

/**
 * Linear interpolation between two `Pixi.Color` objects.
 *
 * @param start The start color.
 * @param end The end color.
 * @param t The interpolation factor between [0, 1].
 * @param result A `PIXI.Color` object to store the result.
 * @returns The interpolated color.
 */
declare function interpolate(start: Color, end: Color, t: number, result?: Color): Color;

declare const ColorUtil_interpolate: typeof interpolate;
declare namespace ColorUtil {
  export { ColorUtil_interpolate as interpolate };
}

/**
 * Rounds a number to a specified number of deciamal places.
 *
 * @param value The number to round.
 * @param decimals How many decimal places to keep.
 * @returns The rounded number.
 */
declare function round(value: number, decimals?: number): number;
/**
 * Clamps a number within the specified range.
 *
 * @param value The number to clamp.
 * @param min The lower bound of the range.
 * @param max The upper bound of the range.
 * @returns The clamped value.
 */
declare function clamp(value: number, min?: number, max?: number): number;
/**
 * Linear interpolation between two numbers.
 *
 * @param start The start value.
 * @param end The end value.
 * @param t The interpolation factor.
 * @returns The interpolated value.
 */
declare function lerp$1(start: number, end: number, t: number): number;
/**
 * Quadratic interpolation between two numbers.
 *
 * Formula: [Quadratic Bézier curves](https://en.wikipedia.org/wiki/B%C3%A9zier_curve#Quadratic_B%C3%A9zier_curves)
 *
 * @param start The start value.
 * @param control The control value.
 * @param end The end value.
 * @param t The interpolation factor.
 * @returns The interpolated value.
 */
declare function qerp$1(start: number, control: number, end: number, t: number): number;
/**
 * Randomly shuffles the elements of an array in place using the
 * [Fisher–Yates algorithm](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle).
 *
 * @param array The array to shuffle.
 * @returns The same array, shuffled in place.
 */
declare function shuffle<T>(array: T[]): T[];

declare const MathUtil_clamp: typeof clamp;
declare const MathUtil_round: typeof round;
declare const MathUtil_shuffle: typeof shuffle;
declare namespace MathUtil {
  export { MathUtil_clamp as clamp, lerp$1 as lerp, qerp$1 as qerp, MathUtil_round as round, MathUtil_shuffle as shuffle };
}

/**
 * Linear interpolation between two `PIXI.Point` objects.
 *
 * @param start The start point.
 * @param end The end point.
 * @param t The interpolation factor.
 * @param result A `PIXI.Point` object to store the result.
 * @returns A new `PIXI.Point` representing the interpolated position.
 */
declare function lerp(start: Point, end: Point, t: number, result?: Point): Point;
/**
 * Quadratic interpolation between two `PIXI.Point` objects.
 *
 * @param start The start point.
 * @param control The control point.
 * @param end The end point.
 * @param t The interpolation factor.
 * @param result A `PIXI.Point` object to store the result.
 * @returns A new `PIXI.Point` representing the interpolated position.
 */
declare function qerp(start: Point, control: Point, end: Point, t: number, result?: Point): Point;
/**
 * Calculates the Euclidean distance between two `PIXI.Point` objects.
 *
 * @param a The first point.
 * @param b The second point.
 * @returns The distance between the two points.
 */
declare function distance(a: Point, b: Point): number;

declare const PointUtil_distance: typeof distance;
declare const PointUtil_lerp: typeof lerp;
declare const PointUtil_qerp: typeof qerp;
declare namespace PointUtil {
  export { PointUtil_distance as distance, PointUtil_lerp as lerp, PointUtil_qerp as qerp };
}

export { Binder, Button, ColorUtil, Item, List, MathUtil, Panel, PointUtil, Scene, SceneEvent, SceneManager, type Transition, Transitions, Tween, type TweenConfig };