claw-machine-js/dist/ClawMachine.d.ts

A physics based claw-machine simulation

import { default as React } from 'react';
import { IBall } from './interfaces/Ball.ts';
import { IInitialBall } from './interfaces/InitialBall.ts';
/**
 * Props for the ClawMachine component.
 */
interface IClawMachineProps {
    /**
     * Data for each ball to be displayed in the claw machine.
     * Each item should represent an individual skill or ball item.
     */
    readonly ballData: IInitialBall[];
    /**
     * Width of the canvas in pixels. Defaults to `600`.
     */
    readonly width?: number;
    /**
     * Height of the canvas in pixels. Defaults to `400`.
     */
    readonly height?: number;
    /**
     * Gravity affecting the balls in the claw machine.
     * This controls how fast balls fall. Defaults to `0.2`.
     */
    readonly gravity?: number;
    /**
     * Friction applied to the balls' movement, slowing them down gradually.
     * Defaults to `0.99`.
     */
    readonly friction?: number;
    /**
     * Friction when balls contact the ground. Helps simulate realistic movement.
     * Defaults to `0.8`.
     */
    readonly groundFriction?: number;
    /**
     * Size of the claw in pixels. Controls how large the claw appears.
     * Defaults to `30`.
     */
    readonly clawSize?: number;
    /**
     * Width of the divider line in pixels.
     * Defaults to `70`.
     */
    readonly dividerLineWidth?: number;
    /**
     * Height of the divider line opening at the top in pixels.
     * Defaults to `140`.
     */
    readonly dividerLineHeight?: number;
    /**
     * Thickness of the divider line in pixels.
     * Defaults to `20`.
     */
    readonly dividerLineThickness?: number;
    /**
     * Fill color of the divider line.
     * Defaults to `gray`.
     */
    readonly dividerLineFillColor?: string;
    /**
     * Border color of the divider line.
     * Defaults to `gray`.
     */
    readonly dividerLineBorderColor?: string;
    /**
     * Width of the claw arms in pixels.
     * Controls the visual width of each claw arm. Defaults to `10`.
     */
    readonly clawWidth?: number;
    /**
     * Initial horizontal position of the claw when it is raised.
     * Defaults to `200`.
     */
    readonly clawStartPositionX?: number;
    /**
     * Initial vertical position of the claw when it is raised.
     * Defaults to `40`.
     */
    readonly clawStartPositionY?: number;
    /**
     * Initial open Angle of the Claw.
     * Defaults to `0`.
     */
    readonly clawStartOpenAngle?: number;
    /**
     * Horizontal speed of the claw during movement.
     * Defaults to `2`.
     */
    readonly clawSpeedX?: number;
    /**
     * Vertical speed of the claw during movement.
     * Defaults to `1.1`.
     */
    readonly clawSpeedY?: number;
    /**
     * Opening speed  of the claw.
     * Defaults to `1`.
     */
    readonly clawOpenSpeed?: number;
    /**
     * Color of the claw
     * Defaults to `gray`.
     */
    readonly clawColor?: string;
    /**
     * Color of the bolt holding the claw together
     * Defaults to `black`.
     */
    readonly clawBoltColor?: string;
    /**
     * Radius of each ball in pixels. Defaults to `20`.
     */
    readonly ballRadius?: number;
    /**
     * List of balls that have already been dropped.
     * Allows tracking of dropped balls across component re-renders.
     */
    readonly alreadyDroppedBalls: IBall[];
    /**
     * Callback function to add new balls to the dropped balls list.
     * used to remove some balls from the initial balls list
     *
     * @param balls - Array of balls that were dropped
     */
    readonly addToDroppedBalls: (balls: IBall[]) => void;
}
/**
 * API for controlling the ClawMachine component.
 */
export interface ClawMachineCommands {
    /**
     * Moves the claw to a specific position and resolves a Promise when the position is reached.
     *
     * **Parameters:**
     * - `x`: The desired x-coordinate for the claw.
     * - `y`: The desired y-coordinate for the claw.
     * - `angle`: The desired angle for the claw's open/closed state (e.g., 0 for closed, 45 for half-open).
     * - `immediateReturn` (optional): If `true`, the claw immediately returns to the starting position after reaching the target. Defaults to `false`.
     *
     * @param x - The desired x-coordinate for the claw.
     * @param y - The desired y-coordinate for the claw.
     * @param angle - The desired angle for the claw's open/closed state.
     * @param immediateReturn - (Optional) If true, the claw closes if it touches a ball and throws it to the exit area.
     * @returns A Promise that resolves when the claw reaches the specified position.
     */
    moveClaw: (x: number, y: number, angle: number, immediateReturn?: boolean) => Promise<void>;
    /**
     * Moves the claw to the right by the claw dx speed as long as stopMoving is not called
     */
    moveClawRight: () => void;
    /**
     * Moves the claw to the left by the claw dx speed as long as stopMoving is not called
     */
    moveClawLeft: () => void;
    /**
     * Stops the current claw Movement triggered by moveClawRight() or moveClawLeft()
     */
    stopMoving: () => void;
    /**
     * Moves the claw down and tries to grab a ball
     * @param clawDropDelay - Delay in ms that happens between reaching the drop position and the claw reset. Defaults to 500ms
     */
    moveClawDown: (clawDropDelay?: number) => Promise<void>;
}
export declare const ClawMachine: React.MemoExoticComponent<React.ForwardRefExoticComponent<IClawMachineProps & React.RefAttributes<ClawMachineCommands>>>;
export {};