react-incremental-library/dist/index.d.ts

A React library for incremental, idle, and clicker games. Build high-performance, engaging experiences with minimal setup.

interface GameLoopOptions {
    tickRate?: number;
    startPaused?: boolean;
    maxTickTime?: number;
    catchupThreshold?: number;
    onTick?: (delta: number) => void;
    debugMode?: boolean;
}
interface GameLoopReturn {
    tick: number;
    deltaTime: number;
    isPaused: boolean;
    fps: number;
    togglePause: () => void;
    pause: () => void;
    resume: () => void;
    resetTick: () => void;
}
declare function useGameLoop(options?: GameLoopOptions): GameLoopReturn;

type UpgradeStatic = {
    cost: number;
    onUpgrade: () => void;
    onBuy: () => void;
    onBuyAll: () => void;
    onBuyCustom: (amount: number) => void;
    onSell: () => void;
    onSellAll: () => void;
    onSellCustom: (amount: number) => void;
};
type UpgradeSellable = {
    isSellable: true;
};
type UpgradeNonSellable = {
    isSellable: false;
};

interface UseTickProps {
    interval: number;
    onTick: () => void;
    startImmediately?: boolean;
}

type Notation = 'compact' | 'standard' | 'scientific' | 'engineering';

type UseTickPropsWithEnabled = Omit<UseTickProps, 'onTick'> & {
    callback: () => void;
    enabled?: boolean;
};
declare const useTick: ({ interval, callback, enabled, }: UseTickPropsWithEnabled) => void;

interface UseAutoIncrementProps {
    interval: number;
    increaseBy: number;
    onPause?: () => void;
    onResume?: () => void;
    onAutoIncrement?: (amount: number) => void;
    options?: {
        startPaused?: boolean;
    };
}
/**
 * Hook to automatically increase currency by `increaseBy` every `interval` ms.
 *
 * @param {UseAutoIncrementProps} props
 * @param {number} props.interval - The interval in milliseconds.
 * @param {number} props.increaseBy - The amount to increase the currency by each interval.
 * @param {object} [props.options] - Additional configuration.
 * @param {boolean} [props.options.startPaused] - If true, starts in a paused state.
 * @param {Function} [props.onPause] - Called when the timer is paused.
 * @param {Function} [props.onResume] - Called when the timer is resumed.
 * @param {Function} [props.onAutoIncrement] - Called when the timer increments the currency.
 * @returns {{ pause: () => boolean, resume: () => void, isPaused: boolean }}
 *   An object with control methods and the paused state.
 */
declare const useAutoIncrement: ({ interval, increaseBy, onPause, onResume, onAutoIncrement, options, }: UseAutoIncrementProps) => {
    pause: () => boolean;
    resume: () => void;
    isPaused: boolean;
};

interface UseIdleProgressProps {
    resourcePerSecond: number;
}
declare const useIdleProgress: ({ resourcePerSecond, }: UseIdleProgressProps) => {
    idleGain: number;
};

declare const useOfflineProgress: () => {
    maxOfflineTime: number;
    offlineMultiplier: number;
    setMaxOfflineTime: (time: number) => void;
    setOfflineMultiplier: (multiplier: number) => void;
    registerOfflineCallback: (callback: (elapsedTime: number) => void) => void;
};

interface UseAchievementProps {
    name: string;
    condition: boolean;
    onUnlock?: () => void;
    progress?: number;
    progressCurrent?: number;
    progressTarget?: number;
    category?: string;
    description?: string;
    icon?: string;
    hidden?: boolean;
}
declare const useAchievement: ({ name, condition, onUnlock, progress, progressCurrent, progressTarget, category, description, icon, hidden, }: UseAchievementProps) => {
    unlocked: boolean;
    progress: number;
    category: string;
    description: string;
    icon: string | undefined;
    hidden: boolean;
};

interface Achievement {
    name: string;
    condition: boolean;
    onUnlock?: () => void;
    category?: string;
    description?: string;
    icon?: string;
    hidden?: boolean;
    progress?: number;
    progressTarget?: number;
    progressCurrent?: number;
}
interface UseAchievementsOptions {
    persistenceKey?: string;
    onAchievementUnlocked?: (achievementName: string) => void;
}
interface UseAchievementsReturn {
    allAchievements: {
        name: string;
        unlocked: boolean;
        category: string;
        description: string;
        icon?: string;
        hidden: boolean;
        progress: number;
    }[];
    getAchievement: (name: string) => {
        name: string;
        unlocked: boolean;
        category: string;
        description: string;
        icon?: string;
        hidden: boolean;
        progress: number;
    };
    getAchievementsByCategory: (category: string) => {
        name: string;
        unlocked: boolean;
        category: string;
        description: string;
        icon?: string;
        hidden: boolean;
        progress: number;
    }[];
    categories: string[];
    completionPercentage: number;
}
declare const useAchievements: (achievementsList: Achievement[], options?: UseAchievementsOptions) => UseAchievementsReturn;

declare const usePrestige: () => {
    prestigePoints: number;
    prestigeMultiplier: number;
    prestigeThreshold: number;
    canPrestige: boolean;
    prestige: () => void;
    setPrestigeThreshold: (threshold: number) => void;
    registerResetCallback: (callback: () => void) => void;
    reset: () => void;
};

type UseUpgradeProps = UpgradeStatic & (UpgradeSellable | UpgradeNonSellable);
declare const useUpgrade: (props: UseUpgradeProps) => {
    handleUpgrade: () => void;
    handleBuy: () => void;
    handleBuyAll: () => void;
    handleBuyCustom: (amount: number) => void;
    handleSell: () => void;
    handleSellAll: () => void;
    handleSellCustom: (amount: number) => void;
    owned: number;
};

interface UseCooldownProps {
    duration: number;
    autoReset?: boolean;
}
declare const useCooldown: ({ duration, autoReset, }: UseCooldownProps) => {
    isCoolingDown: boolean;
    remainingTime: number;
    startCooldown: () => void;
    resetCooldown: () => void;
};

interface UseCurrencyOptions {
    /**
     * Custom formatter for currency display
     * @param value The currency value to format
     * @returns Formatted string representation of the currency
     */
    formatter?: (value: number) => string;
    /**
     * Number of decimal places to display
     * @default 2
     */
    precision?: number;
    /**
     * Initial currency name
     */
    initialName?: string;
}
/**
 * Hook for managing game currency with formatting options
 * @param options Configuration options for the currency
 * @returns Currency state and methods
 */
declare const useCurrency: (options?: UseCurrencyOptions) => {
    currency: number;
    increase: (by: number) => void;
    decrease: (by: number) => void;
    currencyName: string;
    reset: () => void;
    setCurrencyName: (name: string) => void;
    setPrecision: (precision: number) => void;
    setFormat: (formatter: ((value: number) => string) | undefined) => void;
    getFormatted: () => string;
    getValue: () => number;
    setMaxValue: (max: number | undefined) => void;
    setMinValue: (min: number | undefined) => void;
};

interface Producer {
    id: string;
    name: string;
    baseCost: number;
    baseProduction: number;
    costScaling: number;
    count: number;
    dependencies?: {
        producerId: string;
        requiredCount: number;
    }[];
}

declare const useProduction: () => {
    addProducer: (producer: Omit<Producer, "count">) => void;
    buyProducer: (producerId: string) => boolean;
    updateProduction: (deltaTime: number) => void;
    getProducerCost: (producerId: string) => number;
    getProducerProduction: (producerId: string) => number;
    canBuyProducer: (producerId: string) => boolean;
    reset: () => void;
    producers: Record<string, Producer>;
    lastUpdate: number;
};

interface UseResourceCapProps {
    initialValue: number;
    max: number;
}
declare const useResourceCap: ({ initialValue, max }: UseResourceCapProps) => {
    resource: number;
    addResource: (amount: number) => void;
    removeResource: (amount: number) => void;
};

interface UseMultiplierProps {
    baseValue: number;
    initialMultiplier?: number;
}
declare const useMultiplier: ({ baseValue, initialMultiplier, }: UseMultiplierProps) => {
    multiplier: number;
    applyMultiplier: () => number;
    increaseMultiplier: (by: number) => void;
    resetMultiplier: () => void;
};

interface UseClickerProps {
    initialValue?: number;
    onClick?: (newValue: number) => void;
}
declare const useClicker: ({ initialValue, onClick }: UseClickerProps) => {
    count: number;
    handleClick: () => void;
};

type HotKeyType = 'keydown' | 'keyup';
type KeyCombination = string[];
interface UseHotKeyProps {
    /** Single key or combination of keys that trigger the callback */
    keys: string | KeyCombination;
    /** Function to call when the hotkey is triggered */
    callback: (event: KeyboardEvent) => void;
    /** Type of keyboard event to listen for */
    eventType?: HotKeyType;
    /** Whether to prevent the default browser behavior */
    preventDefault?: boolean;
    /** Whether to stop the event propagation */
    stopPropagation?: boolean;
    /** Whether the hotkey is currently disabled */
    disabled?: boolean;
    /** Minimum time (in ms) between callback executions */
    debounceMs?: number;
    /** Whether keys must be pressed in the exact order specified */
    requireExactOrder?: boolean;
    /** Whether to allow key repeat events */
    allowRepeat?: boolean;
}

declare const useHotKey: ({ keys, callback, eventType, preventDefault, stopPropagation, disabled, debounceMs, requireExactOrder, allowRepeat }: UseHotKeyProps) => null;

declare const useNotation: (number: string | number, notation: Notation, locale?: string) => string | number;

declare const useLoadSaveGame: <T>() => T;

interface UseSaveGameProps<T> {
    data: T;
    onSave?: () => void;
    onDiscard?: () => void;
}

declare const useSaveGame: <T>(props: UseSaveGameProps<T>) => {
    data: T;
};

export { useAchievement, useAchievements, useAutoIncrement, useClicker, useCooldown, useCurrency, useGameLoop, useHotKey, useIdleProgress, useLoadSaveGame, useMultiplier, useNotation, useOfflineProgress, usePrestige, useProduction, useResourceCap, useSaveGame, useTick, useUpgrade };
export type { Achievement, UseAchievementProps, UseAchievementsOptions, UseAchievementsReturn };