-
Notifications
You must be signed in to change notification settings - Fork 2
Scripting Reference
The functions prefixed with "ls" (short for "LUA script", which makes more sense in the C++ code, as opposed to the actual macros where everything is lua script...) generally operate on the Automato window, so lsGetWindowSize() gets the width and height of the Automato window.
The functions prefixed with "sr" (short for Screen Reader) generally operate on the automated application's window, so srGetWindowSize() gets the width and height of the game window.
The functions with neither an sr or ls prefix are lua-script library functions (probably from the common scripts) or LUA intrinsics.
- Note that you MUST call srReadScreen to update the screen before calling srFindImageInRange etc.
- Vec2 (or Point) is a table where point[0] = x and point[1] = y representing a screen coordinate or size
- Region object is a table where region[0] = x0, region[1] = y0, region[2] = width, region[3] = height
- Parse object is a table where parse[0] = x0, parse[1] = y0, parse[2] = text
- [l,t,r,b] is a bounds table where bounds[0] = left, bounds[1] = top, bounds[2] = right, and bouds[3] = bottom
- Box is a table representing a rectangular region with fields (x, y, width, height, left, top, right, bottom)
void lsSetCaptureWindow()
Attaches screen-reader/clicking functions to the window under the mouse cursor. Call it once at the very beginning of script execution. Use askForWindow() instead in most cases.
void lsSleep(int ms)
Pauses execution for a set period. For long waits, use sleepWithStatus() or sleepWithStatusPause() in ui_common.inc
string lsScriptName()
Returns the name of the currently running script.
void srClickMouse(int x, int y, bool bRightClick)
Moves mouse cursor (x, y) and sends a click event. Use safeClick() from common_click.inc instead in most cases.
void srClickMouseNoMove(int x, int y, bool bRightClick)
Sends a click event at (x, y) without moving the mouse cursor. Use safeClick() from common_click.inc instead in most cases.
void srDrag(int x0, int y0, int x1, int y1, bool rightClick)
Drags the mouse from (x0, y0) to (x1, y1), moving the mouse cursor. Use safeDrag() from common_click.inc instead in most cases.
void srSetMousePos(int x, int y)
Moves the mouse cursor to (x, y). Usually call only immediately after safeBegin() from common_click.inc to minimize interference by the user.
void srMouseDown(int x, int y, bool rightClick) void srMouseUp(int x, int y, bool rightClick)
Send mouse down/up event at position (x, y). Usually call only immediately after safeBegin() to minimize interference by the user.
x,y srMousePos()
Get the current mouse position. Use getMousePos() instead as it returns a standard Vec2 (Point) rather than two integers.
In general, avoid when possible because chat state and settings may interfere with it.
*void srKeyEvent(const char s)
Sends keyboard events (up and down) for each character in the string.
void srLeftArrow()
void srRightArrow()
void srUpArrow()
void srDownArrow()
Sends arrow keypress events.
void srKeyDown(int key)
Send a key down event by key code
void srKeyUp(int key)
Send a key up event by key code
*void srKeyEvent2(const char s)
void srLeftArrow2()
void srRightArrow2()
void srUpArrow2()
void srDownArrow2()
void srKeyDown2(int key)
void srKeyUp2(int key)
Same, but uses the Windows SendInput API, see notes below.
*void srCharEvent(const char s)
Sends characters with WM_CHAR instead of WM_KEY. Depending on the application being automated this may work better or worse than srKeyEvent and srKeyEvent2, and allows sending capital/lowercase characters instead of just key presses.
Vec2 srGetWindowSize()
Returns the capture window size. This is automated program's (e.g. ATITD's) window. Call only after lsSetCaptureWindow() or askForWindow() have been called.
*Vec2 srImageSize(const char fn)
Returns the size in pixels of the image at a given path.
void srReadScreen()
Refresh the screen buffer. Functions which search the screen use the screen as it was when this function was last called. Make sure to call this before any screen searching and any time you think the screen may have changed in a way important to your script.
*void srMakeImage(const char name, int x, int y, int w, int h)
Create a new image 'file', referenced later by the 'name' at the given path based on the pixels found on part of the atitd screen. srMakeImage does not make a file on disk, it makes an "image" to be used for srFindImage, or displayed with srShowImageDebug (see multi_click.lua). The image "name" can be referenced in the above functions.
*Vec2 srFindImage(const char fn, int tol)
Search the screen for a match on a particular image and return the coordinates of its upper-left corner. lsSetCaptureWindow() or askForWindow() must have been called. This function searches the screen as it was when srReadScreen() was last called. This function finds the top-most then left-most match. To find multiple matches, see findAllImages().
*void srShowImageDebug(const char fn, float x, float y, float z, float scale)
Show an image, such as one captured with srMakeImage, in the VT window, useful for debugging, or feedback in things like multi_click.lua.
*Vec2 srFindImageInRange(const char fn, int x0, int y0, int w, int h, int tol)
Like srFindImage(), but only searches a portion of the screen. This can be much faster than searching the entire screen.
int srReadPixel(int x, int y)
Get the pixel value at a particular location in RGBA format (to get RGB format, divide by 256 rounding down). This function reads directly from the screen, so is always up to date, and is much cheaper than refreshing the entire screen buffer, but much more expensive than reading a pixel from the captured buffer.
int srReadPixelFromBuffer(int x, int y)
Similar to the above function but fetches the pixel at a location as of the last srReadScreen() call.
*void srSaveLastReadScreen(const char fn)
Save whole screen buffer to file, useful for debugging.
Vec2 srFindNearestPixel(int color, int x, int y, bool checkRgb, bool checkHue, int radius, int rgbTol, int hueTol)
Returns the position of a pixel within the specified circular area which either matches the tolerance by RGB or Hue. Tolerances are squared difference sums (so, range of 0 to 255*255^3, recommended around 5000, maybe less for Hue).
*void lsShowScreengrab(const char _color)
Draws the captured screen in the VT window.
Vec2[] lsAnalyzePapyrus(int minsize, int maxsize, int debug, int relevant_radius)
Returns an array of positions on screen suspected to be papyrus.
Vec2[] lsAnalyzeSilt(int minsize, int maxsize, int debug, int relevant_radius)
Returns an array of positions on screen suspected to be silt.
[l,t,r,b] srGetWindowBorders(int x, int y)
Returns the bounds of the in-game window surrounding (x, y). It may return odd results if (x, y) is not inside an in-game window or if the window that (x, y) is over is behind other windows. The result looks at the screen as of the last time srReadScreen() was called. Use getWindowBorders() instead as it returns a standard Box rather than a bounds.
[r,g,b] lsColorComponent(color)
Converts a screen read color to RGB components
Important caveat for using these methods:
A side effect of finding text is that the image buffer gets modified to replace light yellow/brown pixels with all white pixels. You should always call srReadScreen() between searching for text and searching for an image. Additionally, text parsing will fail on windows like the error pane that contain vertical black bars on the same lines as text.
text_flag:
- EXACT - requires that any matching lines exactly match the text given
- NOPIN - used when searching within a window that does not have a pin image
- REGION - modifies function to return a Box representing the region containing matching text, rather than a matching parse object
Flags may be combined, i.e. EXACT_NOPIN, EXACT_REGION, NOPIN_REGION, EXACT_NOPIN_REGION.
On methods taking a window parameter, if window is not nil then only the window provided is searched, otherwise the entire screen is searched.
parse or Box findText(String text, Box window, text_flag flag)
finds first instance of text.
parse[] or Box[] findAllText(String text, Box window, text_flag flag)
finds all instances of text. If REGION flag is set returns a list of windows containing text. If text is nil returns a list of all parsed lines on the screen.
parse or Box waitForText(String text, int timeout, String message, Box window, text_flag flag)
Continuously reads the screen and waits up to timeout ms for the text to appear. Displays message on the Automato pane while waiting.
void waitForNoText(String t)
void clickText(parse p)
does a safeClick on a parse object.
parse[] getChatText()
returns a list of parse objects representing text in the chat box
int lsScreenX int lsScreenY Vec2 lsGetWindowSize()
Width/height of the VT interface window.
Vec2 lsMouseClick(int x, int y, int w, int h, int button)
Returns the coordinates of and captures a click in the specified portion of the VT window.
bool lsMouseIsDown(int button)
Returns true if the given mouse button is currently being pressed by the user. 1 = Left, 2 = Middle, 3 = Right.
*void lsPrintln(const char s)
Print a string to the console. You can open the console from the VT main menu. Used for debugging.
bool lsShiftHeld() bool lsAltHeld() bool lsControlHeld()
Returns true if the player is currently holding the given button. Make sure to check for the user releasing the button between taking actions based on the button state.
*void lsPlaySound(const char sound)
Play an audio file at the given path.
**int lsPrint(int x, int y, int z, float xsc, float ysc, const char color, const char str)
Print text to the VT interface. Displayed when lsDoFrame() is called.
void lsFontShadow(int on)
Switches to a shadowed font, this can be useful if displaying text over an image.
**int lsMessageBox(const char title, const char msg, int buttons)
Displays a message box with an OK button (1, default), Yes (2), No (4), or Cancel (8) buttons, and returns which button is clicked. Combine the bits to specify a set of buttons (e.g. 2+4=6 will show both "Yes" and "No" buttons).
**int lsPrintWrapped(int x, int y, int z, int w, float xsc, float ysc, const char color, const char str)
Print wrapped text on the VT interface. Displayed when lsDoFrame() is called.
*void lsDisplaySystemSprite(int tile, int x, int y, int z, float w, float h, const char color)
Display image on the VT interface. tile = 1 is just a solid white box, which can be used, when combined with a color, to draw a colored box of the requested size.
**bool lsButtonText(int x, int y, int z, int w, const char color, const char txt)
Display a text button on the VT interface and return true if it was clicked. Displayed when lsDoFrame() is called.
**bool lsButtonImg(int x, int y, int z, float scale, const char color, const char filename)
Display an image button on the VT interface and return true if it was clicked. Displayed when lsDoFrame() is called.
**bool lsCheckBox(int x, int y, int z, const char color, const char txt, bool value)
Display a check box that the user can toggle. Returns the current value of the check box. Displayed when lsDoFrame() is called.
*int lsDropdown(const char key, int x, int y, int z, int w, int val)
Display a dropdown menu of items the user can select. Returns the index currently selected. Displayed when lsDoFrame() is called.
*void lsScrollAreaBegin(const char key, int x, int y, int z, int w, int h)
Display a scrollable area on the VT interface. All UI done until lsScrollAreaEnd() will be within this scrollable area.
void lsScrollAreaEnd(int h)
End a scrollable area
void lsSetCamera(float x0, float y0, float x1, float y1)
Define the coordinate space used for the VT window. Can be used to zoom out the interface globally.
void lsDoFrame()
Update the screen with the set of buttons/text/controls invoked since the last lsDoFrame(). lsDoFrame() called twice in a row will produce a blank screen.
void lsTopmost(int value)
Set whether the VT window is "topmost" (appearing on top of all other windows). Sometimes this setting can get lost, or for specific scripts it may be needed to turn it off temporarily.
**{bool done, selection} lsEditBox(const char *key, int x, int y, int z, int w, int h, float xsc, float ysc, const char color, const char def)
Provide an edit box for the user to enter text into. selection returns the current contents of the box. Done is set to true when the use presses enter.
int lsGetTimer()
Returns the current time in milliseconds.
*const char lsClipboardGet()
Returns the current contents of the clipboard.
*void lsClipboardSet(const char str)
Sets the contents of the clipboard.
*bool lsKeyDownHit(const char key)
Checks if a key has been pressed this frame in the Automato window, and eats the key press. See Supported Key Names.
*bool lsKeyDown(const char key)
Checks if a key is currently held down in the Automato window. See Supported Key Names.
*bool lsKeyUpHit(const char key)
Checks if a key has been released this frame in the Automato window, and consumes the key release. See Supported Key Names.
*void lsKeyDownUnhit(const char key)
Un-consumes a key press, or, inserts a keypress to be consumed later in the frame. See Supported Key Names.
This is a 3rd party Lua module that is included in Automato to allow scripts to communicate, using HTTP, with external services.
Full reference can be found at http://w3.impa.br/~diego/software/luasocket/reference.html
Simple usage:
local http = require("socket.http");
local body, code, headers = http.request("http://www.google.com");void lsServerListen()
Listens on port 3007 for GlovNet connections. Client code to connect to this can be found in libUtil in the same repository as the Automato source code.
{ip, client, type[, cmd, data]} lsServerGetNextEvent(int timeout)
Polls for incoming network events. Type is "connect", "disconnect", or "data". If type is "data", then "cmd" and "data" will also be filled in with the command and payload.
*void lsServerSend(int client, int cmd, const char data)
Send a message to a client (client ids can be recorded from their "connect" message handled above).