nut.js/examples/mouse-test/README.md

nut.js Mouse Control

nut.js allows to simulate mouse input by moving the cursor, clicking mouse buttons or performing dragging gestures.

• Configuration
  • autoDelayMs
  • mouseSpeed
• setPosition
• getPosition
• move
  • straightTo
  • centerOf
  • left
  • right
  • up
  • down
• leftClick
• rightClick
• scrollDown
• scrollUp
• scrollLeft
• scrollRight
• drag
• pressButton
• releaseButton

Configuration

The nut.js mouse comes with a config object which allows to configure it's behaviour.

autoDelayMs

mouse.config.autoDelayMs configures the delay between mouse clicks and / or scrolls.

mouseSpeed

mouse.config.mouseSpeed configures mouse movement speed in pixels per second.

setPosition

setPosition takes a Point and moves the mouse cursor to this position instantly.

getPosition

getPosition returns a Promise which resolves to the current cursor Point

move

move is the general purpose method for mouse movement in nut.js. It receives a path given either as Point[] or Promise<Point[]> and a movement function of type (amountOfSteps: number, speedInPixelsPerSecond: number): number[], returns a list of durations in nanoseconds.

mouse.move will follow this path in timesteps provided by the movement function. This way it's possible to fully customize mouse movment behaviour by implementing own functions for path calculation and / or movment timing.

straightTo

straightTo is a movement function which takes a target Point and calculates a path of Point[] leading from the current mouse position to the desired target.

centerOf

centerOf is a helper function which takes a Region and returns the center Point of that region.

centerOf is a great fit for straightTo as it allows us to move to the center of a Region returned by e.g. screen.find.

await mouse.move(straightTo(centerOf(screen.find(...))));

randomPointIn

randomPointIn is another helper function which takes a Region and returns a random Point within that region.

randomPointIn is a great fit for straightTo as it allows us to move to the center of a Region returned by e.g. screen.find.

await mouse.move(straightTo(randomPointIn(screen.find(...))));

left

left is a relative movement function which returns a path moving x pixels to the left of your current mouse position.

await mouse.move(left(10));

right

right is a relative movement function which returns a path moving x pixels to the right of your current mouse position.

await mouse.move(right(10));

up

up is a relative movement function which returns a path moving x pixels up from your current mouse position.

await mouse.move(up(10));

down

down is a relative movement function which returns a path moving x pixels down from your current mouse position.

await mouse.move(down(10));

EasingFunction

EasingFunctions are used to modify movement behaviour. They receive a number expressing the percentage travelled along the path we specified via e.g. straightTo.

When applying an easing function the total speed in pixels with which your cursor will be moving calulates as follows:

const speedInPixels = baseSpeed + easingFunction(idx / amountOfSteps) * baseSpeed 

So you could customize movement speed to move slower on the first half of a path, to then speed up on the second half using this easing function:

const firstSlowThenFast = (percentage) => {
	return percentage <= 0.5 ? -0.75 : 0.75;
}

await mouse.move(left(1000), firstSlowThenFast);

leftClick

leftClick performs a click with the left mouse button at the current cursor position.

rightClick

rightClick performs a click with the right mouse button at the current cursor position.

scrollDown

scrollDown scrolls x "ticks` downwards. Absolute scroll width depends on your system.

scrollUp

scrollUp scrolls x "ticks` upwards. Absolute scroll width depends on your system.

scrollLeft

scrollLeft scrolls x "ticks` to the left. Absolute scroll width depends on your system.

scrollRight

scrollRight scrolls x "ticks` to the right. Absolute scroll width depends on your system.

drag

Similar to 'move', drag move the mouse cursor along a given path.

While moving, it presses and holds the left mouse button, performing a drag gesture.

pressButton

pressButton presses and holds a given mouse button.

releaseButton

releaseButton releases a given mouse button.