Process Functions

attach

attach(window)

Attaches MicroMacro's input to another window. You may only attach to a single window at a time. When using attached input, MicroMacro will send input directly to the specified window; meaning it will not interfere with other windows if you switch focus and may allow you to continue sending input while it is in a minimized state. Note that this does not work for all applications, and you may still need to keep the window focused for input to register.

While in an attached state, the start and stop hotkeys will only work if MicroMacro or it's attached window are currently focused (ie. on top). This is intentional.

Example

attach( findWindow("mygame") );

attachKeyboard

attachKeyboard(window)

Exactly like attach(), except that it only attached keyboard input instead of both keyboard and mouse input.

attachMouse

attachMouse(window)

Exactly like attach(), except that it only attached mouse input instead of both keyboard and mouse input.

detach

detach()

Removes the attachment to whichever window was specified when using attach(). After detaching, MicroMacro will no longer specifically target it's previously attached window.

Example

attach( findWindow("mygame") );
yrest(100);
detach();

getAttachedHwnd()

number getAttachedHwnd()

Returns the handle to window of the currently attached window. If a window is not attached, this function will return 0.

openProcess

handle openProcess(proc)

Opens the process for reading/writing of memory. Returns a handle to the process, or 0 on failure. Accepts a process ID. You should use findProcess() if applicable. You should use closeProcess() to close the process handle when you are done, however, no serious problems will arise if you forget.

You should store the handle in a variable; You will need it for reading and writing memory.

Example - Using process ID

myProcess = openProcess( 1234 );
if( myProcess == 0 ) then
  print("Could not find and open the process");
end

Example - Using window name

myProcess = openProcess( findProcess("The window name") );
if( myProcess == 0 ) then
  print("Could not find and open the process");
end

closeProcess

closeProcess(proc)

Closes the specified handle to the process. You should close any handles that you are no longer using, but it is not necessary. MicroMacro will automatically close any handles that have gone out of scope in your scripts. Closing process handles will help to free system resources when needed, but is unnecessary unless you are opening hundreds of processes in a short amount of time.

Example

myProcess = openProcess( findProcess("The window name") );
closeProcess( myProcess ); -- myprocess is closed. You must re-open it in order to
-- read or write memory from/to it.

findProcess

process findProcess(windowname)

Finds the window's process with the specified window name. Must be exact, but accepts wild cards '*' and '?'. Returns a process ID on success, 0 on failure. This will only return on the first window to match; so you might not find the correct window if multiple windows have the same, or similar, names.

Example - No wild cards

myProcess = openProcess( findProcess("Mozilla Firefox") );

This example will target only windows named exactly "Mozilla Firefox".

Example - Single character wild cards

myProcess = openProcess( findProcess("M?zilla F?refox") );

This example will target windows named "M_zilla F_refox" where _ can be any single character. This would match "Mozilla Firefox" as well as "Mazilla Forefox".

Example - Full wild cards

myProcess = openProcess( findProcess("Mozilla *") );

This example will target windows named that start with "Mozilla ", including "Mozilla Firefox" as well as "Mozilla Thunderbird", but not "Mozilla" (because of the lack of a trailing space).

findProcessByExe

process findProcessByExe(exeName)

Finds the application's process with the specified name. Accepts wildcards '*' and '?'. Returns a process ID on success, 0 on failure. This will only return on the first process to match; so you might not find the correct process if multiple processes have the same, or similar, names.

Returns 0 if the process is not found.

See findProcess() for more information on wild cards.

Example

myProcess = openProcess( findProcessById("mygame.exe") );

findProcessByWindow

process findProcessByWindow(window)

Finds the process which belongs to the specified window. Returns a process ID on success, 0 on failure.

See findProcess() for more information on wild cards.

Example

win = findWindow("Untitled - Notepad");
proc = findProcessByWindow(win)

findWindow

number findWindow(windowName) number findWindow(windowName, className)

Finds the window with the specified name. Accepts wildcards '*' and '?'. Returns a handle to the window on success, 0 on failure. This will only return on the first window to match; so you might not find the correct window if multiple windows have the same, or similar, names.

You may also, optionally, provide a class name to target specific processes or parts of processes. In example, the section of Notepad in which you can type has a classname of 'EDIT'. Using findWindow() and providing the 'EDIT' class name will allow you to find the handle to the edit box so that you are able to attach to it.

In some games, the client window will be given a specific classname. For example, Runes of Magic uses the class name "Radiant Arcana". You can use this to make sure you are finding the correct window rather than anything with "Runes of Magic" in the title (such as if you are browsing the Runes of Magic website, your web browser will contain "Runes of Magic" in the window title).

See findProcess() for more information on wild cards.

Example

myWindow = findWindow("Untitled - Notepad");

findWindowList

table findWindowList(windowName)

Finds all windows that match the specified mask. Accepts wildcards '*' and '?'. Returns a full table on success, or an empty table on failure. You may use getWindowName() to find each window's name.

See findProcess() for more information on wild cards.

Example

myList = findWindowList("Untitled - Notepad");
for i = 1,#myList do
  printf("Found window %x [%s]\n", myList[i], getWindowName(myList[i]));
end

foregroundWindow

window foregroundWindow()

Finds the window that is on top. Returns a handle to the window on success, 0 on failure.

Example

myWindow = foregroundWindow();

windowValid

bool windowValid(win)

Returns true if a window handle is still valid or not. You may use this to detect if a window has been closed.

Do not rely on this too heavily; Windows recycles handles and it is possible a new window was created with the same handle.

Example

win = findWindow("Something");

printf("Close the window \'Something\'\n");
while( windowValid(win) ) do -- wait for the window to be closed.
  yrest(100);
end

getHwnd

window getHwnd()

Returns MicroMacro's window. You can use this to set the window title of the calling MicroMacro window.

Example

mmwin = getHwnd();
setWindowName(mmwin, "This is an example");

getWindowName

string getWindowName(window)

Returns the window title of the specified window.

Example

win = findWindow("*");
printf("Found window is named: %x\n", getWindowName(win));

getWindowClassName

string getWindowClassName(window)

Returns the window's class name of the specified window.

Example

win = findWindow("*");
printf("Found window's class name is named: %x\n", getWindowClassName(win));

setWindowName

setWindowName(window, name)

Changes the specified window's title.

Example

win = findWindow("*");
setWindowName(win, "Changed");

After running the above example, the first window found by findWindow() will have it's window title changed to "Changed".

windowRect

x,y,w,h windowRect(window)

Returns the rectangle that contains the window. 4 integers are returned: x, y, width, height (in that order). If the window is minimized, x and y will be -32000 while width and height will be 0. Variables x and y represent the top-left corner of the client region of the window. Variables width and height represent the width and height of the client area within the window. This can be used to find the top left corner of the window to be used as offset values in functions such as mouseSet() to ensure that the coordinates are within the window's boundaries. It may also be used to find which resolution a user is running the target program under.

Example

window = findWindow("Untitled - Notepad");
x,y,w,h = windowRect(window);

printf("window is at (%d,%d) and is %d wide, and %d high.", x, y, w, h);

openDC

hdc openDC(window)

Returns the Handle to Device Context (HDC) of the specified window. Some functions may require an HDC to read/draw to and from their screen bitmaps.

Typically, you will want to only open an HDC to a window once and leave it open until it is no longer needed. Do not continuously re-open an HDC to the same window all the time, as this consumes system resources.

Example

window = findWindow("Untitled - Notepad");
hdc = openDC(window);

closeDC

closeDC(hdc)

Releases a Handle to Device Context that was retrieved using openDC(). You do not need to use this function, as the HDC will automatically be closed once the variable goes out of scope, however, it is in good practice to do so.

Example

window = findWindow("Untitled - Notepad");
hdc = openDC(window);
closeDC(hdc);

makeColor

color makeColor(r, g, b)

Returns a color value for the given red, green, blue values. r, g, and b should be an integer between 0 and 255.

Example

pink = makeColor(255, 0, 255);

getR

int getR(color)

Returns the red channel value for the given color. The returned value will be between 0 and 255.

Example

pink = makeColor(255, 0, 247);
red = getR(pink); -- red will be 255

getG

int getG(color)

Returns the green channel value for the given color. The returned value will be between 0 and 255.

Example

pink = makeColor(255, 0, 247);
green = getG(pink); -- green will be 0

getB

int getB(color)

Returns the blue channel value for the given color. The returned value will be between 0 and 255.

Example

pink = makeColor(255, 0, 247);
blue = getB(pink); -- blue will be 247

getPixel

r,g,b getPixel(hdc, x, y)

Returns the red, green, and blue values of the pixel located at (x,y) on the HDC (opened by openDC()). This can be used to read color values from the screen. The coordinates, x and y, are window coordinates, not screen coordinates! The returned values (r, g, b) will be integers between 0 (none) and 255 (full).

Note that if the user is running under different color depth, has a vastly different video card, or different video settings, it could cause the color values returned to be different by up to (on average) +- 15 per channel. You should always allow for a wide range per channel if you are checking a specific pixel for information.

Example

hdc = openDC( findWindow("Untitled - Notepad") );
r,g,b = getPixel(hdc, 12, 24);
printf("RGB: %d, %d, %d", r, g, b);

setPixel

setPixel(hdc, x, y, color)

Draws a pixel onto the HDC at (x,y) with color 'color'. 'color' should be generated through the use of makeColor().

If you will be writing pixels to the screen often (say, in a for loop), then it is not good practice to continuously call makeColor() to generate a color value. If you will be using the same color over and over, generate the color once, store it in a variable, and use the variable instead.

Example

hdc = openDC( findWindow("Untitled - Notepad") );
setPixel(hdc, 12, 24, makeColor(255,0,255));

pixelSearch

x,y pixelSearch(hdc, color, x1, y1, x2, y2)

x,y pixelSearch(hdc, color, x1, y1, x2, y2, accuracy)

x,y pixelSearch(hdc, color, x1, y1, x2, y2, accuracy, step)

Scans 'hdc' within the rectangle represented by (x1,y1)(x2,y2) for a pixel that matches the given color.

If 'accuracy' is not given, it is assumed to be 0 (exact match). Otherwise, all color channels must be within 'accuracy' units of the given color for a match to take place. A higher 'accuracy' level means that the colors do not need to match as closely.

If 'step' is not given, it is assumed to be 1. Otherwise, the algorithm will skip some number of pixels. For example, if 'step' is 2, then every other pixel will be scanned (across both X and Y axis). Using a higher 'step' value will cause the search to be quicker in most cases, however, it may skip pixels that should otherwise cause a match.

If the pixel is not found within the specified area, then pixelSearch() will return -1, -1.

Example

hdc = openDC( findWindow("Untitled - Notepad") );
matchcolor = makeColor(0, 0, 0); -- we're looking for black (text)
x,y = pixelSearch(hdc, matchcolor, 0, 0, 1024, 768, 0, 4);

--(x,y) should now represent a point near the very first detected character
--entered into notepad that is on the screen.

drawLine

drawLine(hdc, x1, y1, x2, y2, color, size)

Draws a line onto the hdc from (x1,y1) to (x2,y2) with the given color and size. 'color' should be generated using makeColor(), and size should be an integer specifying the width of the line in pixels.

Example

window = findWindow("Untitled - Notepad");

hdc = openDC(window);
drawLine(hdc, 32,32, 128,64, makeColor(255, 0, 255), 2);

drawRect

drawRect(hdc, x1, y1, x2, y2, color, size)

Draws a rectangle onto the hdc from (x1,y1) to (x2,y2) with the given color and size. 'color' should be generated using makeColor(), and size should be an integer specifying the width of the lines in pixels.

Example

window = findWindow("Untitled - Notepad");

hdc = openDC(window);
drawRect(hdc, 32,32, 128,64, makeColor(255, 0, 255), 2);

saveScreenshot

saveScreenshot(window, filename)

This will save a bitmap screenshot of a specified window (or use 0 for the desktop) as the given filename. 'filename' may include a full or relative path, and should include the '.bmp' extension.

showWindow

showWindow(window, command)

Allows you to show, hide, minimize, and maximize windows. 'window' should be obtained through findWindow() or similar functions. 'command' should be one of the following:

 sw.show -- activate (show and set focus to) the window
 sw.shownormal -- activate and restore to original size and position
 sw.hide -- hide the window
 sw.forceminimize -- forcefully minimize (also hides the window)
 sw.minimize -- minimize the window
 sw.maximize -- activate and maximize the window
 sw.restore -- activate the window and restore to original size and position (used after minimizing)

Example

window = findWindow("Untitled - Notepad");
showWindow(window, sw.show);

findPatternInProcess

number findPatternInProcess(process, pattern, mask, startAddress, length)

Returns the address of the start of a pattern within a process. 'process' should be gathered by using openProcess. 'pattern' will be a string of bytes containing values you which to search, and 'mask' will be a string-mask explaining which values must match and which ones can be 'wild-cards'. 'startAddress' will denote where to begin searching, and 'length' will be the number of bytes to scan before giving up.

In most cases, you will be looking for a series of bytes. In this case, it makes more sense to take advantage of string.char() rather than using a direct string of bytes. In your 'mask', you should use the character 'x' to represent a character that should match, and the character '?' to represent a 'wild-card'.

If the pattern is not found, findPatternInProcess() will return 0.

Example:

local pattern = string.char(0x8B, 0x07, 0x8B, 0x0D, 0xFF, 0xFF, 0xE8, 0x50);
local mask = "xxxx??xx";

-- Using this pattern and mask combination, we'll be looking for:
-- 8B 07 8B 0D ?? ?? E8 50

local foundAddress = findPatternInProcess(proc, pattern, mask, 0x400000, 0x10000);
if( foundAddress == 0 ) then
  printf("Failed to find the pattern in the process.\n");
end

getModuleAddress

number getModuleAddress(procid, module)

Returns the address of a given module inside of the specified address. This can be used to find the origin of a process (by specifying "whatever.exe" for the module name) or to find the location of a dynamic link library in memory (by providing "whatever.dll" for the module name).

Note that 'procid' should be the process identifier (use findProcess* functions for this), not a handle returned by openProcess().

Example:

local notepadOrigin = getModuleAddress(notepadProc, "notepad.exe");

flashWindow

flashWindow(window, count)

Causes the specified window to "flash" in an attempt to grab the users attention. If 'window' is not specified, the calling MicroMacro instance will be used. 'count' refers to how many times the window will flash. If 'count' is 0, the window will continue to flash until it is pulled into the foreground by the user.

Example:

flashWindow(); -- flash MicroMacro window until user focuses it
flashWindow(nil, 10);-- flash MicroMacro window 10 times
flashWindow(findWindow("notepad"), 0);-- flash Notepad until it is focused
flashWindow(nil, -1); -- Stop flashing MicroMacro window

getWindowParent

window getWindowParent(hwnd)

Returns the parent of window 'hwnd'. If it does not have a parent, this function will return nil.

Example:

local child = findWindow("Child window title");
local parent = getWindowParent(child);