Cljck

An OS-agnostic Clojure library for automating keyboard and mouse actions.

Cljck provides two distinct ways of automating various actions related to keyboard, mouse, and the visual content on your screen.

This is a regular library, which can be used as you write your own Clojure or Java program to solve specific tasks.
The JAR file resulting from building the library can process script files written in EDN, which expose the most generally useful functions of the library in a way where you don't have to compile any code to write small scripts. You simply pass text files to the JAR on the command line.

You may at this point be left with a few questions. Even if you're not, I took the liberty of making some up.

Why didn't you just use AutoIT?

It's not available on my favorite OS and I didn't want to learn a new language.

Do you expect me to learn your strange DSL?

You can use it as a library to write Clojure/Groovy/Java/etc. programs or you can treat it as an interpreter of a simple DSL. If both options sound unappealing, you're probably not the intended consumer of this product.

Requirements

You will need a Java Runtime Environment of version 1.8. Will it work with Java 1.7? I have no idea. Will it work with Java 1.6? Absolutely not.

If you want to build the project yourself you will need Boot.

Motivation

I need to beat friends and family in Clicker Heroes. This is proving an excellent game for driving progressive enhancements of Cljck, as there's always one more thing you could be automating. Ideally it will eventually be possible to handle everything including ascensions, and I can just leave a laptop playing the game indefinitely until my accumulated Hero Souls make my friends weep with frustrated jealousy.

Library Usage

Just require the project from Clojars.

Note: It's not actually on Clojars yet.

DSL Usage

Assuming you have the executable cljck-x.y.z.jar in your current directory, and have written the script click-the-stuff.edn and placed it in the same directory, just run

java -jar cljck-x.y.z.jar click-the-stuff.edn

in your terminal emulator. Passing multiple files will run all the scripts, interleaving their execution in non-deterministic sequence. This is usually perfectly fine, though, and is precisely how I use it.

DSL API

Each EDN file should contain exactly one top-level element. Why not two? Because right now it will only process the last top-level expression found due to laziness on my part.

Every expression should be a vector starting with a keyword and containing zero or more arguments. The keyword will serve as the name of a function to call, and the remaining arguments will be passed to this function. The keywords and their possible argument arities are as follows:

Keyword	Arguments	Description
`:click`		Clicks the left mouse button.
`:if`	`condition` `if-expression` `else-expression`	Evaluates the condition. If it is true, process the if-expression. If not, process the then-expression.
`:move-to`	`x` `y`	Moves the mouse cursor to position [x, y].
`:pointer-near`	`x` `y` `distance`	Evalutes to true if the mouse cursor is currently withing the given distance of the point [x, y].
`:press`	`key-string`	Presses the keyboard key given by the key string. See Oracle's documentation about the specifics of this format.
`:repeat`	`n` `expression+`	One or more expressions should be supplied. These will be repeated n times in the sequence they appear.
`:repeatedly`	`expression+`	One or more expressions should be supplied. These will be repeated indefinitely in the sequence they appear.
`:scroll-down`	`n`	Scrolls down n ticks of the mouse wheel. You can omit the argument, which will be interpreted as meaning 1 tick.
`:scroll-up`	`n`	Scrolls up n ticks of the mouse wheel. You can omit the argument, which will be interpreted as meaning 1 tick.
`:wait`	`n`	Pauses execution of the script for roughly n miliseconds.
`:when`	`condition` `expression+`	Evalutes the condition. If it is true, processes all expressions following the condition. If not, does nothing.

Example

Here's an example using all the keywords, but not making much sense.

[:repeatedly
 [:if [:pointer-near 100 100 50]
  [:move-to 500 500]
  [:move-to 100 100]]
 [:repeat 100
  [:click]
  [:scroll-down 5]]
 [:when [:pointer-near 500 500 50]
  [:scroll-up]]
 [:wait 1000]]

It reads as follows.

Repeat the following indefinitely:

Is the mouse cursor within 50 pixels of the point [100, 100]?

Yes: Move it to [500, 500]. No: Move it to [100, 100].
Repeat 100 times:
- Click the left mouse button.
- Scroll down 5 ticks.
Is the mouse cursor within 50 pixels of the point [500, 500]?

Yes: Scroll up 1 tick.
Wait for 1000 miliseconds.

emiln / cljck

readme