06. Creating a Custom Instruction

Besides custom recorders and players, custom instructions may also be created. These instructions can be called by writing CUSTOM <instrname>, where <instrname> is the name of the custom instruction. Custom instructions extend com.thistestuser.cursormacro.instr.custom.CustomModule and are added in the com.thistestuser.cursormacro.instr.custom.CustomInstructions.register() method. The method call to add custom instructions should be Custom.customInstrs.put("CUSTOMINSTR", CustomInstr.class);, if the instruction name is CustomInstr.

Custom instructions must have a default constructor.

Here are the methods that need to be implemented:

initialize(args)

This method is called when the script is compiled and the instruction class is initialized. The args parameter is the entire instruction string split by whitespace, so the array would start with "CUSTOM", follow by the instruction name, followed by any arguments provided. Exceptions like IllegalArgumentException are allowed to be thrown here, which would terminate the compiler.

execute(player, robot)

This method is called when the instruction is executed. The player is the instance of com.thistestuser.cursormacro.player.Player that is running the script. If the instruction presses or unpresses something, Player.registerMouse(press, button) or Player.registerKey(press, button) should be called, where press is true if the button is pressed down and false if released. If the method is expected to have a delay, Player.expectedTime should be incremented. For instructions that do not have an upper bound on execution time, use Player.shouldStop() to determine of the execution should stop.

randomize(random, removeData, rndDelay, maxPercent)

This method is called when the randomizer is applied. The random argument is the random instance (may be null), the removeData argument is whether or not existing randomizer data (offsets) should be removed when the random argument is null, and the last 2 arguments are from the "Random Delay" and "Max Percentage" fields.

This method should return true if the instruction is randomizable in any way (e.g. the instruction contains a delay). The return type should always be the same for each custom instruction (so a custom instruction shouldn't return true sometimes and false sometimes).

Here is the recommended implementation of a randomizable instruction:

if(random == null) {
    if(removeData) {
        <remove generated offsets>
    }
} else {
    <generate offsets>
}

hasStaticRuntime()

This method returns true if the instruction has an expected runtime.

getDelay() and getOffset()

These methods return an integer which when added together is the expected runtime of this instruction. If hasStaticRuntime() returns false these methods can throw an exception. The objective of having a delay and an offset call is to ensure that the randomizer to generate and remove offsets easily without tampering with the base values.

argsAsString()

This method returns the string equivalent of the instruction, starting with the instruction name ("CUSTOM" should not appear). This string must be able to be passed in to initialize(args) without losing any information. For example, if the string (before it was split by whitespace) that was passed in to initialize(args) was CUSTOM CUSTOMINSTR 1 2 3, then argsAsString() should return CUSTOMINSTR 1 2 3.