-
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 lsGetUtcNowString()
Returns a string representing the current date (UTC) in the format 'YYYY-MM-DD hh:mm:ss'
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.
void srMouseWheel(int step, bool directionUp)
Send mousewheel scroll event to captured window. Automato v2.70+ step is the number of times to send the minimum scroll amount. directionUp = rolling the wheel forward. The captured window needs to be the active window. This can be useful for setting the camera position during macro setup.
In general, avoid when possible because chat state and settings may interfere with it.
void srKeyEvent(string 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(string 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(string 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(string 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(string 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.
void srSaveImageDebug(string image_name, string file_name)
Save an image, such as one captured with srMakeImage, to file, useful for debugging.
Vec2 srFindImage(string 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(string 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(string 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(string 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(string color)
Draws the captured screen in the VT window.
Vec2[] lsAnalyzeCustom(int minsize, int maxsize, int debug, int relevant_radius, int color_min, int color_max, bool block_avatar)
Returns an array of pixel cluster positions on screen whose RGB values are between the specified mins and maxes, optionally ignoring the area around the avatar/center of the screen. Alpha in colors is ignored. The algorithm downsamples the image and then looks for connected clusters of pixels matching the specified colors, then combines nearly adjacent clusters, and then returns any which contain between minsize and maxsize (downsampled) pixels. When "debug" is 1, it draws the resulting image to the Automato window, with selected pixels highlighted red, ignored pixels darkened (e.g. from block_avatar), and non-matching pixels tinted cyan-ish. If relevant_radius is less than the whole screen, it will only scrape the party of the screen within that many pixels from the center, making it potentially much faster. Setting this to something high, or 0 (meaning unlimited) is best for debugging.
Vec2[] lsAnalyzePapyrus(int minsize, int maxsize, int debug, int relevant_radius)
Returns an array of pixel cluster positions on screen suspected to be papyrus. Uses more complicated color matching logic (looking for yellows of various brightness) than can be done with lsAnalyzeCustom
Vec2[] lsAnalyzeSilt(int minsize, int maxsize, int debug, int relevant_radius)
Returns an array of pixel cluster positions on screen suspected to be silt. Equivalent to lsAnalyzeCustom(minsize, maxsize, debug, relevant_radius, 0x8D7979FF, 0xB39FA9FF, true); In older versions the min/max colors were 0xE2D7CAFF/0xE9E4D7FF
[l,t,r,b] srGetWindowBorders(int x, int y, int border_width)
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. A border is defined by any pixel found in the range specified by srSetWindowBorderColorRange() The optional border_width is added in all dimensions - pass in 3 to match ATITD T8 behavior, or leave off to get a tight/exact bounds Use getWindowBorders() instead as it returns a standard Box rather than a bounds.
A border is defined by any pixel found in the range specified by srSetWindowBorderColorRange()
The optional border_width is added in all dimensions - pass in 3 to match ATITD T8 behavior, or leave off to get a tight/exact bounds
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
[h,s,v] lsRGBAtoHSV(color)
Converts a screen read color to hue (0-360), saturation (0-1) and value (0-1)
int lsHSVtoRGBA(h, s, v)
Converts HSV to color (RGBA)
void srSetWindowBackgroundColorRange(int color_min, int color_max)
Sets the color range that is treated as window background and stripped in srStripRegion()
void srSetWindowBorderColorRange(int color_min, int color_max)
Sets the colors used by srFindFirst/NextTextRegion() and srGetWindowBorders() to determine the innermost border pixels
void srSetWindowInvertColorRange(int color_min, int color_max)
Sets the colors that srStripRegion/Screen() looks for to decide it should invert (and treat as background when stripping)
U32 srWindowGetStyle()
On Windows, gets the GWL_STYLE value of the captured window. If this is equal to 0x96000000 (fullscreen), on Windows 10, screen capture may not work reliably
void srWindowSetStyle(U32 style)
On Windows, sets the GWL_STYLE value of teh captured window
** void srSetCaptureMode(int mode)**
On Windows, changes between different capture modes for debugging and performance testing. 0 (default)=PrintWindow() 1=BitBlt()
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(string 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()
bool lsKeyHeld(int key)
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(string sound)
Play an audio file at the given path.
int lsPrint(int x, int y, int z, float xsc, float ysc, string color, string 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(string title, string 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, string color, string 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, string 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, string color, string 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, string color, string 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, string color, string 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(string 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(string 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(string key, int x, int y, int z, int w, int h, float xsc, float ysc, string color, string 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. For consistent sizing relative to lsPrint, pass in 0 for legacy_h and just use xsc/ysc.
int lsGetTimer()
Returns the current time in milliseconds.
string lsClipboardGet()
Returns the current contents of the clipboard.
void lsClipboardSet(string str)
Sets the contents of the clipboard.
bool lsKeyDownHit(string 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(string key)
Checks if a key is currently held down in the Automato window. See Supported Key Names.
bool lsKeyUpHit(string 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(string key)
Un-consumes a key press, or, inserts a keypress to be consumed later in the frame. See Supported Key Names.
void lsDrawRect(float x0, float y0, float x1, float y1, float z, int color)
void lsDrawLine(float x0, float y0, float x1, float y1, float z, float w, float spread, int color)
void lsDrawCircle(float x, float y, float z, float r, float spread, int color)
Basic shape drawing.
spreadis how sharp of an edge it has, 0.95 is good for a firm edge, 0.1 for a blurry highlight
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");
local https = require("ssl.https");
local body, code, headers = https.request("https://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, string data)
Send a message to a client (client ids can be recorded from their "connect" message handled above).