Claw-machine-js NPM

ClawJs is a physic-based claw machine that provides various features for customization.

Demo

Check out the live demo here: Live Demo

Installation

npm i claw-machine-js

Features

Fully customizable claw machine parameters (size, speed, etc.)
Support for dynamic ball configurations
TypeScript support for better developer experience

Usage

import { ClawMachineCommands } from 'clawjs/dist/ClawMachine'
import { IInitialBall } from 'clawjs/dist/interfaces/InitialBall'

const initialState: IInitialBall[] = [
	{
		text: 'test',
		ballColor: 'gray',
		ballTextColor: 'yellow',
		icon: react,
	},
]

<ClawMachine alreadyDroppedBalls={[]}
    addToDroppedBalls={(balls) => console.log(balls)}
    ballData={initialState}
/>

Claw Machine Parameters

Prop Name	Type	Default	Required	Description
`ballData`	`Array<Object>`	-	Yes	An array of ball configurations. Each ball object should have `text`, `ballColor`, `ballTextColor`, and optionally `icon`.
`alreadyDroppedBalls`	`Array`	-	Yes	List of balls that have already been dropped from the machine.
`addToDroppedBalls`	`Function`	-	Yes	Callback function triggered when a ball is dropped.
`width`	`Number`	`600`	No	The width of the claw machine in pixels.
`height`	`Number`	`400`	No	The height of the claw machine in pixels.
`ballRadius`	`Number`	`20`	Yes	The radius of each ball in pixels.
`gravity`	`Number`	`0.2`	No	The gravity effect on the balls. Higher values make balls fall faster.
`friction`	`Number`	`0.99`	No	The air resistance that slows the balls’ movement.
`groundFriction`	`Number`	`0.8`	No	The friction between the balls and the ground surface.
`clawSize`	`Number`	`30`	No	The size of the claw's opening in pixels.
`clawWidth`	`Number`	`10`	No	The thickness of the claw's arms.
`dividerLineWidth`	`Number`	`70`	No	The width of the divider line in pixels.
`dividerLineHeight`	`Number`	`140`	No	The height of the divider line in pixels.
`dividerLineThickness`	`Number`	`20`	No	The thickness of the divider line in pixels.
`dividerLineFillColor`	`String`	`gray`	No	The color of the divider line.
`dividerLineBorderColor`	`String`	`gray`	No	The border color of the divider line.
`clawColor`	`String`	`"gray"`	No	The color of the claw.
`clawBoltColor`	`String`	`"black"`	No	The color of the claw's bolts.
`clawStartPositionX`	`Number`	`200`	No	Initial horizontal position of the claw when it is raised.
`clawStartPositionY`	`Number`	`40`	No	Initial vertical position of the claw when it is raised.
`clawStartOpenAngle`	`Number`	`0`	No	Initial open Angle of the Claw.
`clawSpeedX`	`Number`	`2`	No	The speed of the claw moving horizontally (X-axis).
`clawSpeedY`	`Number`	`1.1`	No	The speed of the claw moving vertically (Y-axis).
`clawOpenSpeed`	`Number`	`1`	No	The speed of the claw opening.

Initial Ball Parameters

Prop Name	Type	Default	Required	Description
`text`	`String`	-	Yes	Text displayed inside the ball if no icon is provided.
`icon`	`String`	ball text	No	The file path or URL to an icon image displayed inside the ball.
`radius`	`Number`	global ball radius	No	Radius of the ball, in pixels.
`startX`	`Number`	random	No	Initial X-coordinate position of the ball on the canvas.
`startY`	`Number`	random	No	Initial Y-coordinate position of the ball on the canvas.
`startXMomentum`	`Number`	random	No	Initial horizontal momentum (velocity) of the ball.
`startYMomentum`	`Number`	random	No	Initial vertical momentum (velocity) of the ball.
`imageHeight`	`Number`	ball size	No	Height of the image inside the ball.
`imageWidth`	`Number`	ball size	No	Width of the image inside the ball.
`ballColor`	`String`	`red`	No	Color of the ball.
`ballTextFontSize`	`Number`	ball size	No	Font size of the text inside the ball.
`ballTextColor`	`String`	`white`	No	Text color of the text inside the ball.
`ballTextAlign`	`center` or `left` or `right`	`center`	No	Vertical alignment of the text inside the ball.
`ballTextBaseline`	`middle` or `top` or `bottom`	`middle`	No	Horizontal alignment of the text inside the ball.

Claw Control Functions

It is also possible to control the claw with a number of functions.

import { ClawMachineCommands } from 'clawjs/dist/ClawMachine'
import { IInitialBall } from 'clawjs/dist/interfaces/InitialBall'

const clawMachineRef = useRef<ClawMachineCommands>(null)
const initialState: IInitialBall[] = [
	{
		text: 'test',
		ballColor: 'gray',
		ballTextColor: 'yellow',
		icon: react,
	},
]

const handleMoveClawRight = async () => {
	if (clawMachineRef.current) {
		clawMachineRef.current.moveClawRight()
	}
}

<ClawMachine alreadyDroppedBalls={[]}
    ref={clawMachineRef}
    addToDroppedBalls={(balls) => console.log(balls)}
    ballData={initialState}
/>
<button onMouseDown={() => handleMoveClawRight()}>Move Right</button>

Functions

`moveClaw`

Return Type: Promise<void>
Parameters:
- x (number): The desired x-coordinate for the claw.
- y (number): The desired y-coordinate for the claw.
- angle (number): The desired angle for the claw's open/closed state.
- immediateReturn (boolean, optional): If true, the claw closes if it touches a ball and throws it to the exit area.
Description: Moves the claw to a specified position. Resolves the promise once the position is reached.

`moveClawRight`

Return Type: void
Parameters: None
Description: Moves the claw to the right at a set speed (dx) until stopMoving() is called.

`moveClawLeft`

Return Type: void
Parameters: None
Description: Moves the claw to the left at a set speed (dx) until stopMoving() is called.

`stopMoving`

Return Type: void
Parameters: None
Description: Stops any ongoing movement initiated by moveClawRight() or moveClawLeft().

`moveClawDown`

Return Type: Promise<void>
Parameters:
- clawDropDelay (number, optional): The delay in milliseconds between the claw reaching the drop position and its reset. Defaults to 500ms.
Description: Moves the claw downward and attempts to grab a ball. Resolves the promise once the claw operation completes.