SquirtBot F O R E V E R

The API reference is maintained in English. Forever-specific entry conventions are explained first.

SquirtBot API

Forever Script Entry and Native WoW API Calls

local abc, wow = ...

For Forever scripts, receive these two arguments at the top of each Lua file that needs these interfaces. All native World of Warcraft API functions used by the script must be accessed through the injected wow table: use wow.FunctionName(...) for ordinary functions and wow.C_Namespace.FunctionName(...) for namespaced functions.

This calling convention is required only for Forever. Standard level-60, level-70, level-80, and MoP clients retain their existing client and loader conventions. The distinction concerns the game version, not the client's language.

What the Entry Statement Means

... is Lua's variable-argument expression. At this script entry point, it receives the arguments supplied by the unlocker when it loads the script. It is literal Lua syntax, not a placeholder to replace.

Element Meaning
abc The first argument: the unlocker's own API table, providing its extension functions.
wow The second argument: the native WoW API table supplied by the host for the current game client.
local Keeps these variables local to the current Lua file without overwriting global variables.

abc is a variable name of your choice; names such as aa or host work equally well. Keep the argument order unchanged. If you only need the WoW API, retain the first argument's position:

local _, wow = ...

Do not write local wow = ...: that assigns the first argument, the unlocker API table, to wow. Do not create an empty wow = {} table or replace the injected table with _G.

Why Forever Requires This Convention

The Forever host supplies unlocker extensions and native game APIs as two separate interfaces. The injected wow table is the intended source of game functions for the script. A bare call such as UnitName(...), GetTime(), or C_QuestLog.GetInfo(...) instead looks up a global name in the script environment. That name may be unavailable or may not refer to the interface supplied by the host.

Use the injected wow table consistently in Forever scripts. Even if a bare global happens to work, do not mix it with injected calls or automatically fall back to _G when an interface is missing or a call fails. Check and handle missing interfaces explicitly. Adding wow. does not create an API that the client lacks, nor does it change the function's arguments or return values.

Calling Native APIs

The left column shows bare calls to replace; the right column shows the required Forever form. The left column is not a fallback for Forever.

Bare call Forever call
UnitName("player") wow.UnitName("player")
UnitHealth("player") wow.UnitHealth("player")
UnitHealthMax("player") wow.UnitHealthMax("player")
GetTime() wow.GetTime()
GetBuildInfo() wow.GetBuildInfo()
CreateFrame("Frame") wow.CreateFrame("Frame")
C_QuestLog.GetInfo(index) wow.C_QuestLog.GetInfo(index)
C_Spell.GetSpellInfo(spellID) wow.C_Spell.GetSpellInfo(spellID)

Preserve the complete C_* namespace hierarchy: wow.C_QuestLog.GetInfo must not become wow.GetInfo. Use dot notation for these functions. Writing wow:UnitName("player") would pass an extra self argument and change the call signature.

Check that the current client provides the functions your script uses, including the namespaced APIs shown above.

What Does Not Use the wow Prefix

Complete Example: Read Player Health and Handle an Event

Run this example after entering the game world. Player-related APIs and data are not guaranteed to be available on the login screen.

local abc, wow = ...

assert(type(abc) == "table", "Missing unlocker API argument")
assert(type(wow) == "table", "Missing WoW API argument")
assert(type(wow.UnitName) == "function", "Missing wow.UnitName")
assert(type(wow.UnitHealth) == "function", "Missing wow.UnitHealth")
assert(type(wow.UnitHealthMax) == "function", "Missing wow.UnitHealthMax")
assert(type(wow.CreateFrame) == "function", "Missing wow.CreateFrame")

local function ShowPlayerHealth()
    local name = wow.UnitName("player")
    local health = wow.UnitHealth("player")
    local maximum = wow.UnitHealthMax("player")
    print("Player:", name, "Health:", health, "/", maximum)
end

ShowPlayerHealth()

local frame = wow.CreateFrame("Frame")
frame:RegisterEvent("UNIT_HEALTH")
frame:SetScript("OnEvent", function(self, event, unit)
    if unit == "player" then
        ShowPlayerHealth()
    end
end)

UnitName, UnitHealth, UnitHealthMax, and CreateFrame are accessed through wow. assert, type, and print are Lua functions. RegisterEvent and SetScript are methods on the frame object.

Event callbacks can use the wow variable captured from the surrounding file. Do not receive local abc, wow = ... again inside an event callback: callback arguments describe the event, not the two interfaces supplied when the host loaded the script.

Scripts with Multiple Files

A file's local wow is not automatically available as a local variable in another file. Each file independently loaded by the host under this convention should receive local abc, wow = ... if it needs these interfaces. For modules or factory functions that you call yourself, pass the interfaces explicitly; arbitrary Lua calls do not automatically receive them.

This is the up-to-date list of all SquirtBot API, classified into the following categories.

Common (Arguments)

The following common API functions deal with SquirtBot related arguments.

Back to Table of Contents

GetAppDirectory

Gets the working directory path of SquirtBot client, where the subfolder navmeshes reside.

result = GetAppDirectory()
-- result (string): The result directory path

Back to Category

GetAppSessionCount

Gets the total session count of the current SquirtBot launch.

result = GetAppSessionCount()
-- result (number): The result count

Back to Category

GetAppSessionId

Gets the server ID of the current SquirtBot session, starting from 1. This ID is unique among all sessions, even across computers.

result = GetAppSessionId()
-- result (number): The result ID

Back to Category

GetAppSessionIndex

Gets the client index of the current SquirtBot session, starting from 1. This index is unique on the local computer.

result = GetAppSessionIndex()
-- result (number): The result index

Back to Category

GetAppSessionToken

Gets the token of the current SquirtBot session.

result = GetAppSessionToken()
-- result (string): The result token

Back to Category

GetAppUsername

Gets the username of the current SquirtBot session.

result = GetAppUsername()
-- result (string): The result username

Back to Category

GetSystemErrorCode

Gets the current error code of the SquirtBot system. It returns 0 if the system has no errors. Notice that if any non-zero error code pops up, the engine will stay alive for at most 5 minutes followed by process termination. Such a 5-min grace period should be used to prepare for game exit. Once ready, you could opt to call TerminateCurrentProcess in advance to avoid security concerns as much as possible.

errorCode[, secondsToTermination] = GetSystemErrorCode()
-- errorCode (number): The result error code, which can be one of the followings
{
    SubscriptionExpired = 1,
    RunTooLong = 2,
    HeartbeatFailure = 3,
    SessionInvalidated = 4,
    SecurityRelated = 5
}
-- secondsToTermination (number): The remaining seconds to termination if errorCode is non-zero.

Back to Category

GetSystemVar and SetSystemVar

These API allow you to reads or writes a system-wide global variable that will never go out of scope until the game process is terminated.

value = GetSystemVar(name)
-- name (string): The name of the global variable
-- value (string): The current value of the global variable (nil if it does not exist)

SetSystemVar(name, value)
-- name (string): The name of the global variable
-- value (string): The value of the global variable (nil to remove it)

Back to Category

GetWoWDirectory

Gets the directory path of WoW.exe.

result = GetWoWDirectory()
-- result (string): The result directory path

Back to Category

Common (Constants)

The following common API functions return SquirtBot defined constants.

Back to Table of Contents

GetStringEncodingsTable

Gets the table of supported string encodings.

encodings = GetStringEncodingsTable()
-- encodings (table): The table that contains the following string encodings
{
    Plain = 0,  -- The original data in as-is form (including binary data)
    Base64 = 1, -- Base-64 encoding of the original data
    Hex = 2,    -- Hex encoding of the original data, always in lower case
}

Back to Category

GetValueTypesTable

Gets the table of all value types to read from memory.

types = GetValueTypesTable()
-- types (table): The table that contains the following memory value types
{
    Bool = 1,
    Char = 2,
    Byte = 3,
    Short = 4,
    UShort = 5,
    Int = 6,
    UInt = 7,
    Long = 8,
    ULong = 9,
    Float = 10,
    Double = 11,
    String = 12,
    IntPtr = 13,
    UIntPtr = 14,
    GUID = 15,
}

Back to Category

Common (Encryption)

The following common API functions handle encryptions and encodings.

Back to Table of Contents

Aes256Encrypt and Aes256Decrypt

Encrypts or decrypts a string by AES-256 CBC with padding.

output = Aes256Encrypt(input, key, iv[, padding = "zero", output_encoding = encodings.Plain])
-- input (string): The input string to be encrypted
-- key (string): The key for encryption (must be 32 bytes)
-- iv (string): The IV for encryption (must be 16 bytes)
-- padding (string)：The padding method, which can be either "pkcs7" or "zero"
-- output_encoding (number): The encoding for the encrypted result, from GetStringEncodingsTable()
-- output (string): The output string encrypted

output = Aes256Decrypt(input, key, iv[, padding = "zero", input_encoding = encodings.Plain])
-- input (string): The input string to be decrypted
-- key (string): The key for decryption (must be 32 bytes)
-- iv (string): The IV for decryption (must be 16 bytes)
-- padding (string)：The padding method, which can be either "pkcs7" or "zero"
-- input_encoding (number): The encoding of the input, from GetStringEncodingsTable()
-- output (string): The output string decrypted

In order to make sure your own AES encryption matches the API above, the test vector is given below:

local test = "test";
local encodings = GetStringEncodingsTable();
local encrypted_string = Aes256Encrypt(test, "01234567890123456789012345678901", "0123456789012345", "pkcs7", encodings.Hex);
local decrypted_string = Aes256Decrypt(encrypted_string, "01234567890123456789012345678901", "0123456789012345", "pkcs7", encodings.Hex);
print("result:", encrypted_string, decrypted_string, test == decrypted_string); -- result: a68c23c38693a8ebd1d6276fbb90e5e1 test true

Back to Category

EncodeDecode

Transforms the encoding of an input string from one to another.

output = EncodeDecode(input, input_encoding, output_encoding)
-- input (string): The input string
-- input_encoding (number): The encoding of the input string, from GetStringEncodingsTable()
-- output_encoding (number): The encoding of the output string, from GetStringEncodingsTable()
-- output (string): The output string

Back to Category

Sha256

Computes the hash digest of a plain string by SHA-256.

output = Sha256(input)
-- input (string): The plain string
-- output (string): The digest string

In order to make sure your own SHA256 digest matches the API above, the test vector is given below:

local test = "The quick brown fox jumps over the lazy dog";
local digest = Sha256(test);
print("result:", digest); -- result: d7a8fbb307d7809469ca9abcb0082e4f8d5651e46d3cdb762d02d0bf37c9e592

Back to Category

Common (File)

The following common API functions provide file system operations.

Back to Table of Contents

CreateDirectory

Creates a new directory.

success = CreateDirectory(path)
-- path (string): The directory path
-- success (boolean): Whether the directory is created successfully.

Back to Category

DirectoryExists

Checks if a directory exists.

existence = DirectoryExists(path)
-- path (string): The directory path
-- existence (boolean): Whether the directory exists

Back to Category

FileExists

Checks if a file exists.

existence = FileExists(path)
-- path (string): The file path
-- existence (boolean): Whether the file exists

Back to Category

GetDirectoryFiles

Gets the names of all files in a specific directory.

fileNames = GetDirectoryFiles(path)
-- path (string): The directory path
-- fileNames (table): The file name array

Back to Category

GetDirectoryFolders

Gets the names of all subfolders in a specific directory.

folderNames = GetDirectoryFolders(path)
-- path (string): The directory path
-- folderNames (table): The folder name array

Back to Category

ReadFile

Reads the content of a file.

content = ReadFile(path[, encoding = encodings.Plain])
-- path (string): The file path
-- encoding (number): The encoding to encode the file content, from GetStringEncodingsTable()
-- content (string): The file content

Back to Category

WriteFile

Writes the content of a file.

success = WriteFile(path, content[, append = false])
-- path (string): The file path
-- content (string): The file content
-- append (boolean): Whether to append or overwrite the file
-- success (boolean): Whether the content is successfully written to the file

Back to Category

Common (Lua)

The following common API functions give you some additional features of Lua engine.

Back to Table of Contents

EnableUnlocker

Enables the unlocker for all Blizzard API functions. It is disabled by default and you should enable it when you need to call protected API.

enabled = EnableUnlocker([enable])
-- enable (boolean): Whether to enable or disable the unlocker (none/nil to only get the current enable status)
-- enabled (boolean): The current enable status of the unlocker

Back to Category

LoadScript

Loads a Lua script as a function. It behaves similar to loadstring but provides an additional layer against API hooking.

script | error = LoadScript(name, content)
-- name (string): The name of the script (shown in Lua error messages if any)
-- content (string): The content of the script
-- script (function): The loaded function if compilation succeeds
-- error (string): The syntax error message if compilation fails

Back to Category

LoadScriptAesEncrypted

Loads a Lua script as a function, whose content is encrypted with AES-256 CBC. It behaves similar to loadstring but provides an additional layer against API hooking and brute-force memory scanning.

script | error = LoadScriptAesEncrypted(name, content, key, iv[, padding = "zero", encoding = encodings.Plain])
-- name (string): The script name (shown in Lua error messages if any)
-- content (string): The encrypted script content
-- key (string): The key for decrypt the script content (must be 32 bytes)
-- iv (string): The IV for decrypt the script content (must be 16 bytes)
-- padding (string)：The padding method, which can be either "pkcs7" or "zero"
-- encoding (number): The encoding of encrypted script content, from GetStringEncodingsTable()
-- script (function): The loaded function if compilation succeeds
-- error (string): The syntax error message if compilation fails

Back to Category

RunScript

Runs a Lua script. Any syntax/runtime error results in an error popup. Any return values from the script will be discarded. It behaves similar to RunScript but provides an additional layer against API hooking. If you wish to stay silent or grab the return values, use LoadScript followed by manual pcall.

RunScript(name, content)
-- name (string): The name of the script (shown in Lua error messages if any)
-- content (string): The content of the script

Back to Category

RunScriptAesEncrypted

Runs a Lua script, whose content is encrypted with AES-256 CBC. Notice that any decryption failures might cause the system to crash. Any return values from the script will be discarded. It behaves similar to RunScript but provides an additional layer against API hooking and brute-force memory scanning. If you wish to stay silent or grab the return values, use LoadScriptAesEncrypted followed by manual pcall.

RunScriptAesEncrypted(name, content, key, iv[, padding = "zero", encoding] = encodings.Plain)
-- name (string): The script name, shown in any Lua error message
-- content (string): The encrypted script content
-- key (string): The key for decrypt the script content (must be 32 bytes)
-- iv (string): The IV for decrypt the script content (must be 16 bytes)
-- padding (string)：The padding method, which can be either "pkcs7" or "zero"
-- encoding (number): The encoding of encrypted script content, from GetStringEncodingsTable()

Back to Category

SetCustomScript

Adds/Updates a custom script that gets loaded side by side with the plugin scripts (usually after game init). Notice that there will be a popup if there are any Lua syntax or runtime errors in the script content.

SetCustomScript(name, content)
-- name (string): The script name, shown in any Lua error message
-- content (string): The script content

Back to Category

Common (Maths)

The following common API functions add more math helpers.

Back to Table of Contents

GetAllSpanningCircles

Gets all spanning circles of a specific radius over certain weighted points. This is usually useful if you need to calculate the landing position of an AoE spell.

centers = GetAllSpanningCircles(radius, minWeight, points)
-- radius (number): The circle radius
-- minWeight (number): The minimum weight in total of the points that the circle should cover
-- points (table): The weighted position array, in which each element should look like {x, y, z[, w = 1]}
-- centers (table): The center positions of all result circles, in which each element should look like {x, y, z}. The circles are sorted according to the total weight in descending order

Back to Category

Common (Network)

The following common API functions provide network functionalities.

Back to Table of Contents

DisconnectFromServer

Disconnects the currently connected WoW session from the Blizzard server.

DisconnectFromServer()

Back to Category

SendHttpRequest and ReceiveHttpResponse

Sends a HTTP request asynchronously and receives the response later. SendHttpRequest() will return immediately after the request is sent without waiting for the response. ReceiveHttpResponse() will clear the request from memory if it is finalized.

request = SendHttpRequest(info)
-- info (table): The request info, which looks like:
{
    Agent = "SquirtBot", -- [OPTIONAL] string: The request agent.
    Body = "{\"test\": 123}", -- [OPTIONAL] string: The request body, only used Method is "POST" or "PUT".
    Callback = function(request, status[, bodySize]) ... end, -- [OPTIONAL] function: The callback function when the status of the request is updated.
    Certificate = "PINNED CERTIFICATE", -- [OPTIONAL] string: The pinned HTTPs server certificate as a protection for packet sniffing. If provided, the server certificate must match it or the HTTP request would fail with status "INVALID_CERTIFICATE".
    Headers = "Content-Type: application/json\r\nX-Custom: test", -- [OPTIONAL] string: The additional request headers
    Method = "POST", -- [OPTIONAL] string: The request method, which can be "GET", "POST", "PUT" or "DELETE"
    Url = "https://www.microsoft.com/", -- string: The request URL
}
-- request (string): The HTTP request ID if sent successfully, for querying HTTP response later

status[, body | bodySize] = ReceiveHttpResponse(request[, encoding = encodings.Plain])
-- request (string): The HTTP request ID previously returned from SendHttpRequest().
-- encoding (number): The encoding to encode the response body, from GetStringEncodingsTable().
-- status (string): The current status of the HTTP request, which can be one of the followings:
    -- "REQUESTING": The request is still on the way
    -- "REDIRECTING": The request is being redirected to another URL (HTTP 301/302)
    -- "RESPONDING": Downloading response after the request is sent
    -- "SUCCESS": The response is well received and everything about the HTTP request is finalized
    -- "REQUEST_FAILED": The request is terminated due to failures
    -- "INVALID_CERTIFICATE": The request is terminated due to invalid HTTPs certificate
    -- "RESPONSE_HEADERS_FAILED": The response is terminated while fetching response headers
    -- "RESPONSE_BODY_FAILED": The response is terminated while fetching response body
-- body (table): The response data, available only if status is "SUCCESS", which looks like:
{
    Body = "...", -- string: The HTTP response body
    BodySize = 1024, -- number: The total size of Body, in bytes
    Certificate = "SERVER CERTIFICATE", -- string: The actual server certificate if the request is HTTPs, which can be used for pinning
    Code = 200, -- number: The HTTP response status code
    Headers = "HTTP/1.1 200 OK...", -- string: The HTTP response headers
}
-- bodySize (number): The size of response data received so far, in bytes, only available if status is "RESPONDING"

Given the nature of async programming model, a simple example to send and receive HTTP is given as below, leveraging the callback function.

SendHttpRequest({
    Url = "https://www.microsoft.com",
    Method = "GET",
    Callback = function(request, status, bodySize)
        -- Deal with the current status and response of the HTTP request here.
        if (status == "RESPONDING") then
            print("receiving response:", bodySize)
        elseif (status == "SUCCESS") then
            local _, response = ReceiveHttpResponse(request);
            print("all done! body:", response.Body);
        end
    end
});

Another example to send and receive HTTP is given as below, leveraging frame updates.

local http_frame = CreateFrame("FRAME");
local http_request;
http_frame:SetScript("OnUpdate", function()
    if (not http_request) then
        local info = {...}; -- Fill your actual info here.
        http_request = SendHttpRequest(info);
    else
        local http_status, http_response = ReceiveHttpResponse(http_request)
        if (not http_status) then
            -- The HTTP request has been fulfiled.
            http_frame:SetScript("OnUpdate", nil);
            http_frame = nil;
            return;
        end
        -- Deal with the current status and response of the HTTP request here.
        if (status == "RESPONDING") then
            print("receiving response:", bodySize)
        if (http_status == "SUCCESS") then
            print("response body:", http_response.Body);
        end
    end
end);

Back to Category

Common (State)

The following common API functions manage game engine states.

Back to Table of Contents

ResetAfk

Resets the game engine AFK countdown timer.

ResetAfk()

Back to Category

Common (Win32)

The following common API functions give you power to access certain Win32 capabilities.

Back to Table of Contents

GetKeyState

Gets the pressed state of a specific key.

down, toggled = GetKeyState(key)
-- key (number): The key code, from https://learn.microsoft.com/en-us/windows/win32/inputdev/virtual-key-codes
-- down (boolean): Whether the key is pressed down
-- toggled (boolean): Whether the key is being toggled (such as CapsLock)

Back to Category

GetMemoryOffset

Gets the offset/rva of a specific memory address in a specific memory module.

offset = GetMemoryOffset(module, address)
-- module (string): The name of the memory module (nil for "Wow.exe" aka the main module)
-- address (number): The absolute memory address
-- offset (number): The result offset *nil if the memory address is not found)

Back to Category

IsCurrentWindow

Checks whether the game window is at foreground.

result = IsCurrentWindow()
-- result (boolean): Whether the game window is at foreground

Back to Category

PlaySoundFile

Plays a specific sound WAV/MP3 file once.

success = PlaySoundFile(path)
-- path (string): The file path of the WAV/MP3 file
-- success (boolean): Whether the sound file is played successfully

Back to Category

ReadMemory

Reads a value at a specific memory offset/rva in a specific memory module.

value = ReadMemory(module, offset, type)
-- module (string): The name of the memory module (nil for "Wow.exe" aka the main module)
-- offset (number): The offset/rva in the memory module to read
-- type (number): The type of the value, from GetValueTypesTable()
-- value (number): The result value (nil if the memory address is not found)

Back to Category

ShellExecute

Executes a command of Win32 shell (DOS command).

success = ShellExecute(command)
-- command (string): The shell command
-- success (boolean): Whether the shell command is executed successfully

Back to Category

TerminateCurrentProcess

Terminates the current process, aka WoW game process.

TerminateCurrentProcess()

Back to Category

In-World (Action)

The following in-world API functions extends the character action controls.

Back to Table of Contents

ClickPosition

Click a world position.

ClickPosition(x, y, z[, right = false])
-- x, y, z (number): The position co-ordinate.
-- right (boolean): Whether it is left-click (true) or right-click (false).

Back to Category

FaceDirection

Sets the facing (horizontal) of the currently controlled unit, in radian (from 0 to 2 * PI). The angle value is relative instead of absolute, if the player is on a transport.

success = FaceDirection(angle[, update = true])
-- angle (number): The facing/rotation in radian.
-- update (boolean): Whether to update the facing immediately (with an instant turn animation).
-- success (boolean): Whether the facing is changed.

Back to Category

FaceDirectionSmoothly

Sets the horizontal facing of the currently controlled unit smoothly instead of instantly, in radian (from 0 to 2 * PI). The angle value is relative instead of absolute, if the player is on a transport.

success = FaceDirectionSmoothly(angle, duration[, isRandom = false])
-- angle (number): The horizontal facing, in radian.
-- duration (number): The duration of the smooth facing takes, in seconds.
-- isRandom (boolean): Whether the rotation speed is random.
-- success (boolean): Whether the smooth facing is started.

Back to Category

GetLastClickedPosition

Gets the last world position clicked.

x, y, z = GetLastClickedPosition()
-- x, y, z (number): The position co-ordinate.

Back to Category

IsFacingSmoothly

Gets whether a smooth facing is ongoing.

ongoing = IsFacingSmoothly()
-- ongoing (boolean): Whether the smooth facing is in progress.

Back to Category

MoveTo

Moves the player to a specific position, using Click-To-Move. You must enable the system CVar autoInteract to make this work, which is the same as enabling "Click To Move" in game settings.

MoveTo(x, y, z[, instantTurn = false])
-- x, y, z (number): The position co-ordinate.
-- instantTurn (boolean): Whether to instantly face to the destination before moving.

Back to Category

SetPitch

Sets the vertical pitch of the currently controlled unit, in radian (from -PI/2 to +PI/2).

SetPitch(angle)
-- angle (number): The pitch in radian.

Back to Category

In-World (Black Technology)

The following in-world API functions gives you some super power of character actions.

Back to Table of Contents

EnableClimbing

Grants/Revokes the power of climbing to the currently controlled unit. Notice that the standard power of this can only allow you to climb up to 90 degree slopes. You can opt to enable super power that allows you to continue go straight up when an obstacle with larger than 90 degree slope is collided. In the super mode, your character may go straight into the obstacle and can lead to unexpected result. This API is considered to be a replacement over the deprecated SetClimbAngle, and you shouldn't mix-use them both.

enabled, isSuper = EnableClimbing([enable, isSuper = false])
-- enable (boolean): Whether to enable climbing (none/nil to only get the current enable status)
-- isSuper (boolean): Whether to enable super climbing
-- enabled (boolean): Whether climbing is currently enabled.

Back to Category

EnableFlying

Grants/Revokes the power of flying to the currently controlled unit. When flying power is on, you can use SetPitch to move the unit vertically anywhere.

enabled = EnableFlying([enable])
-- enable (boolean): Whether to enable flying (none/nil to only get the current enable status)
-- enabled (boolean): Whether flying is currently enabled.

Back to Category

EnableNoclip

Grants/Revokes the power of noclip to the currently controlled unit against certain obstacles.

currentModes = EnableNoclip([modes])
-- modes (number): The modes of noclip which can be a sum of any of the following flags (none/nil to only get the current modes):
0 = none
1 = building
2 = static object
4 = dynamic object
8 = terrain (be careful!)
-- currentModes (number): The current modes of noclip.

Back to Category

IgnoreWater

Ignore water bodies while moving.

currentMode = IgnoreWater([mode])
-- mode (number): Water ignorance mode, which can be one of the followings (none/nil to only get the current mode)
0 = Normal mode
1 = Treat water as ground (walk above water)
2 = Ignore the presence of water (walk under water)
-- currentMode(number): The current water ignorance mode

Back to Category

SetCameraDistanceMax

Sets the maximum distance of the game camera to any value, in yards. This distance will override the game setting if applied.

SetCameraDistanceMax([distance])
-- distance (number): The maximum distance (none/nil to restore game setting)

Back to Category

SetClimbAngle

Sets the maximum angle to climb, in radian.

SetClimbAngle([angle])
-- distance (number): The maximum angle (none/nil to restore game engine allowance)

Back to Category

SetCVarEx

Forcibly sets the value of a CVar. Similar as the Blizzard API SetCVar, but this one could bypass the game engine limitation.

success = SetCVarEx(name, value)
-- name (string): The name of the CVar
-- value (string | number): The value of the CVar
-- success (boolean): Whether the CVar is set successfully

Back to Category

SetNameplateDistanceMax

Sets the maximum distance of a visible nameplate, in yards.

SetNameplateDistanceMax([distance])
-- distance (number): The nameplate distance maximum (none/nil to restore default setting)

Back to Category

StopFalling

Stops the character falling.

StopFalling()

Back to Category

In-World (Constants)

The following in-world API functions return SquirtBot defined constants.

Back to Table of Contents

GetObjectDescriptorsTable

Gets the table of all object descriptor offsets.

descriptors = GetObjectDescriptorsTable()
-- encodings (table): The table that contains the following descriptors, which looks like:
{
    ["CGObjectData__m_guid"] = 0,
    ["CGObjectData__m_entryID"] = 8,
    ...
}

Back to Category

GetObjectFieldsTable

Gets the table of all object field offsets.

fields = GetObjectFieldsTable()
-- fields (table): The table of all object field offsets, which looks like:
{
    ["AnimationState"] = 123,
    ...
}

Back to Category

GetObjectQuestGiverStatusesTable

Gets the table of all quest giver statuses.

statuses = GetObjectQuestGiverStatusesTable()
-- statuses (table): The table of all quest giver statuses, which looks like:
{
    ["None"] = 0,
    ["Unavailable"] = 1,
    ...
}

Back to Category

GetObjectTypeFlagsTable

Gets the table of all object type flags.

flags = GetObjectTypeFlagsTable()
-- flags (table): The table of all all object type flags, which looks like:
{
    Object = 1,
    Item = 2,
    Container = 4,
    AzeriteEmpoweredItem = 8,
    AzeriteItem = 16,
    ...
}

Back to Category

GetUnitMovementFlagsTable

Gets the table of all unit movement flags.

flags = GetUnitMovementFlagsTable()
-- flags (table): The table of all unit movement flags, which looks like:
{
    Forward = 1,
    Backward = 2,
    StrafeLeft = 4,
    StrafeRight = 8,
    TurnLeft = 16,
    ...  
}

Back to Category

In-World (Navigation)

The following in-world API functions provide navmesh calculations. Notice that the map must be loaded beforehand for the rest calculation to work properly (see LoadMap). Regarding the special terms referred, check below: - Offmesh Connection - Polygon Flags are a type attribute of polygons. It is used to indicate certain types of polygons passability. - Polygon Area is just another type attribute of polygons. It is used to apply different costs for shortest path calculation. But unlike polygon flags, which are a combination of various flag values, a polygon can only have one type of area.

Back to Table of Contents

AddOffmeshConnection

Adds a new offmesh connection to a map on the fly. Notice: 1. There might be pre-compiled offmesh connections in the map files. 2. The added offmesh connection only applies before you unload the map. 3. The start and end position must be within the same tile or the API will fail and return nil. 4. There is a system limit for the maximum of offmesh connections on a single map tile, which is 128.

connection = AddOffmeshConnection(mapId, x1, y1, z1, x2, y2, z2, isBidirectional[, polygonFlags = 1])
-- mapId (number): The map ID of the offmesh connection (this is the raw map ID when it comes to map phases)
-- x1, y1, z1 (number): The start position of the offmesh connection
-- x2, y2, z2 (number): The end position of the offmesh connection
-- isBidirectional (boolean): Whether the offmesh connection is a two-way road
-- polygonFlags (number): The polygon flags of the offmesh connection (Ground? Water?)
-- connection (string): The result offmesh connection ID

Back to Category

FindPath

Calculates a path to navigate from one position to another.

pointPath, polygonPath = FindPath(mapId, x1, y1, z1, x2, y2, z2[, ignoreWater = true|ignoreFlags = NAV_WATER, searchCapacity = 1024, agentRadius = 0, searchDeviation = 3, isSmooth = false])
-- mapId (number): The map ID
-- x1, y1, z1 (number): The start position
-- x2, y2, z2 (number): The end position
-- ignoreWater (boolean): Whether to avoid walking into water terrain
-- ignoreFlags (number): Alternatively, if you pass a number in place of ignoreWater, you can specify the flags of a navmesh polygon to be ignored
-- searchCapacity (number): This is a combined value to specify the maximum count of waypoints and the size of search node pool. Increase the number if you wish to find longer path, but meanwhile it will also take longer time due to more navmesh polygons to traverse
-- agentRadius (number): The radius of the navigation agent (your character), in yards. To avoid wall collision, you should set the value accordingly. This value can only take 5 in maximum, and any number > 5 will lead to ignorance
-- searchDeviation (number): The deviation to search for the actual position on mesh for start and end positions, in yards
-- isSmooth (boolean): Whether smooth calculation is used
-- pointPath (table): The array of navigation points of the found path. NIL if path is not found
-- polygonPath (table): The array of navigation mesh polygons of the found path. NIL if path is not found

Back to Category

GetClosestMeshPolygon

Searches for the closest polygon on mesh in a certain cube with a specific center position.

polygon[, polygonX, polygonY, polygonZ, polygonDistance] = GetClosestMeshPolygon(mapId, x, y, z, dX, dY, dZ[, ignoreWater = true|ignoreFlags = NAV_WATER])
-- mapId (number): The map ID
-- x, y, z (number): The center position
-- dX, dY, dZ (number): The cube dimensions
-- ignoreWater (boolean): Whether to ignore water areas
-- ignoreFlags (number): Alternatively, if you pass a number in place of ignoreWater, you can specify the flags of a navmesh polygon to be ignored
-- polygon (string): The closest polygon found. NIL if none
-- polygonX, polygonY, polygonZ (number): The closest position on polygon. NIL if none
-- polygonDistance (number): The distance between {x, y, z} and {polygonX, polygonY, polygonZ}

Back to Category

GetCurrentMapInfo

Gets the map information of the current player's location.

mapId, zoneId, subzoneId[, swapIds] = GetCurrentMapInfo()
-- mapId (number): The map ID.
-- zoneId (number): The map zone ID.
-- subzoneId (number): The map subzone ID.
-- swapIds (table - number[]): The array of map IDs that are active swaps of the current map (none if there isn't any)

Back to Category

GetMeshAreaCost

Gets the cost of a specific mesh area for polygons in a certain map. By default all polygon areas have the same cost of 1. To get the area of a polygon, see GetMeshPolygonArea.

cost = GetMeshAreaCost(mapId, area)
-- mapId (number): The map ID
-- area (number): The polygon area
-- cost (number): The cost of the polygon area

Back to Category

GetMeshPolygons

Searches for adjacent mesh polygons starting from a certain polygon, within a certain sphere. Notice that only adjacent polygons that intersect with the sphere will be included.

polygons = GetMeshPolygons(mapId, startPolygon, x, y, z, radius[, ignoreWater = true|ignoreFlags = NAV_WATER, resultCountMax = 1024])
-- mapId (number): The map ID
-- startPolygon (string): The navigation mesh polygon to start with
-- x, y, z (number): The center position
-- radius (number): The search range, in yards
-- ignoreWater (boolean): Whether to ignore water areas
-- ignoreFlags (number): Alternatively, if you pass a number in place of ignoreWater, you can specify the flags of a navmesh polygon to be ignored
-- resultCountMax (number): The maximum count of polygons to search
-- polygons (table): The found polygons

Back to Category

GetMeshPolygonArea

Gets the area of a certain mesh polygon.

area = GetMeshPolygonArea(mapId, polygon)
-- mapId (number): The map ID
-- polygon (string): The mesh polygon
-- area (number): The area of the polygon (nil if the polygon does not exist)

Back to Category

GetMeshPolygonFlags

Gets the flags of a certain mesh polygon. Flags are a combination of terrain flag, passed into other API arguments to indicate that certain polygons are unpassable.

flags = GetMeshPolygonFlags(mapId, polygon)
-- mapId (number): The map ID
-- polygon (string): The mesh polygon
-- flags (number): The flags of the polygon

Back to Category

GetMeshPolygonVertices

Gets the vertices of a certain mesh polygon.

vertices = GetMeshPolygonVertices(mapId, polygon)
-- mapId (number): The map ID
-- polygon (string): The mesh polygon
-- vertices (table - {x, y, z}[]): The array of vertex positions of the polygon (nil if the polygon does not exist)

Back to Category

GetMeshTile

Gets the mesh tile co-ordinate of a certain position. It helps you to locate the corresponding .mmtile file in navmeshes folder, whose name follows the format "MMMMYYXX.mmtile". e.g. The tile at (31,41) of map 1 should correspond to the map file "00014131.mmtile".

tileX, tileY[, phaseMapId] = GetMeshTile(mapId, x, y, z)
-- mapId (number): The map ID
-- x, y, z (number): The world position on the map
-- tileX, tileY (number): The corresponding map tile coords (nil if the position is not on the map)
-- phaseMapId (number): The current phase map ID of the tile (nil if there is no phase map applied to the tile)

Back to Category

GetOffmeshConnectionDetails

Gets the details of a specific offmesh connection.

mapId, tileX, tileY, x1, y1, z1, x2, y2, z2, isBidirectional, polygonFlags[, polygon] = GetOffmeshConnectionDetails(connection)
-- connection (string): The offmesh connection ID
-- mapId (number): The map ID of the offmesh connection (Notice that this is the raw map ID when it comes to map phases)
-- tileX, tileY (number): The map tile coords of the offmesh connection (Read more in about this in GetMeshTile())
-- x1, y1, z1 (number): The start position of the offmesh connection
-- x2, y2, z2 (number): The end position of the offmesh connection
-- isBidirectional (boolean): Whether the offmesh connection is a two-way road
-- polygonFlags (number): The polygon flags of the offmesh connection (Ground? Water?)
-- polygon (string): The actual polygon loaded in mesh (nil if the offmesh connection is not loaded in mesh)

Back to Category

GetOffmeshConnections

Gets all offmesh connections of a certain map.

connections = GetOffmeshConnections(mapId)
-- mapId (number): The map ID (it could be the ID of a phase map)
-- connections (table - string[]): The array of offmesh connection IDs

Back to Category

IsMapLoaded

Checks if a navigation map is loaded.

isLoaded = IsMapLoaded(mapId)
-- mapId (number): The map ID
-- isLoaded (boolean): Whether the map is loaded

Back to Category

LoadMap

Loads a navigation map. Notice that map loading is synchronous hence may freeze the game for a while.

success = LoadMap(mapId)
-- mapId (number): The map ID
-- success (boolean): Whether the map is loaded

Back to Category

MapExists

Checks whether the files in navmeshes for a navigation map exist.

existence = MapExists(mapId)
-- mapId (number): The map ID
-- existence (boolean): Whether the map files exist

Back to Category

RemoveOffmeshConnection

Removes an existing offmesh connection.

success = RemoveOffmeshConnection(connection)
-- connection (string): The offmesh connection ID
-- success (boolean): Whether the offmesh connection is removed successfully

Back to Category

SetMeshAreaCost

Sets the cost of a specific mesh area for polygons.

success = SetMeshAreaCost(mapId, area, cost)
-- mapId (number): The map ID
-- area (number): The polygon area
-- cost (number): The cost of the polygon area
-- success (boolean): Whether the polygon area cost is updated

Back to Category

SetMeshPolygonArea

Sets the area of a certain mesh polygon.

success = SetMeshPolygonArea(mapId, polygon, area)
-- mapId (number): The map ID
-- polygon (string): The mesh polygon
-- area (number): The area to set
-- success (boolean): Whether the polygon area is updated

Back to Category

SetMeshPolygonFlags

Sets the flags of a certain mesh polygon.

success = SetMeshPolygonFlags(mapId, polygon, flags)
-- mapId (number): The map ID
-- polygon (string): The mesh polygon
-- flags (number): The flags of the polygon
-- success (boolean): Whether the polygon flags are updated

Back to Category

UnloadMap

Unloads a navigation map. This is useful to free up more memory when you don't need the map data.

success = UnloadMap(mapId)
-- mapId (number): The map ID
-- success (boolean): Whether the map is unloaded

Back to Category

In-World (Object)

The following in-world API functions read information from a WoW object. Our engine assigns a unique ID (string) for each of them, wbich can be passed in as another API's argument. Any API arguments that require UnitId can also take our object ID, and vice versa. Different types of object follow the inheritance model as below. - object: The base type of any WoW object - unit: A living object with health bar - player: A character - gameObject: A world object rendered from server - dynamicObject: A world object that is usually short-lived rendered from server

Back to Table of Contents

GameObjectIsUsable

Checks if a game object is usable (right-clickable).

usable = GameObjectIsUsable(gameObject, checkDistance)
-- gameObject (string): The object ID
-- checkDistance (boolean): Whether to check the interaction distance
-- usable (boolean)

Back to Category

GameObjectType

Gets the sub type of a game object.

typeId, typeName = GameObjectType(gameObject)
-- gameObject (string): The object ID
-- typeId (number): The ID of the sub type.
-- typeName (string): The name of the sub type.

Back to Category

GetActiveMover

Gets the currently controlled unit.

activeMover = GetActiveMover()
-- activeMover (string): The object ID of the currently controlled unit (nil if there is none)

Back to Category

GetAnglesBetweenObjects

Gets the angles (facing & pitch) between two objects.

facing, pitch = GetAnglesBetweenObjects(object1, object2)
-- object1 (string): The ID of object 1
-- object2 (string): The ID of object 2
-- facing (number): The horizontal angle from object 1 to object 2, in radian
-- pitch (number): The vertical angle from object 1 to object 2, in radian

Back to Category

GetCorpsePosition

Gets the position of the corpse if the current character is dead.

x, y, z = GetCorpsePosition()
-- x, y, z (number): The co-ordinate of the current character's corpse (nil if not dead)

Back to Category

GetDistanceBetweenObjects

Gets the 3D distance between two objects.

distance = GetDistanceBetweenObjects(object1, object2)
-- object1 (string): The ID of object 1
-- object2 (string): The ID of object 2
-- distance (number): The distance in between (nil if either object does not exist)

Back to Category

GetDistanceBetweenPositions

Gets the 3D distance between two positions.

distance = GetDistanceBetweenPositions(x1, y1, z1, x2, y2, z2)
-- x1, y1, z1 (number): The co-ordinate of position 1
-- x2, y2, z2 (number): The co-ordinate of position 2
-- distance (number): The distance in between

Back to Category

GetObject

Gets the ID of a specific object.

id = GetObject(object)
-- object (string): The object ID or unit ID
-- id (string): The object ID (nil if the object does not exist)

Back to Category

GetObjectWithGUID

Gets the ID of a specific object by its GUID.

id = GetObjectWithGUID(guid)
-- guid (string): The object's GUID
-- id (string): The object's ID (nil if the object with GUID does not exist)

Back to Category

GetPositionBetweenObjects

Gets the position at a certain distance from object 1 to object 2.

x, y, z = GetPositionBetweenObjects(object1, object2, distance)
-- object1 (string): The ID of object 1
-- object2 (string): The ID of object 2
-- distance (number): The distance
-- x, y, z (number): The position co-ordinate

Back to Category

GetPositionBetweenPositions

Gets the position at a certain distance from position 1 to position 2.

x, y, z = GetPositionBetweenPositions(x1, y1, z1, x2, y2, z2, distance)
-- x1, y1, z1 (number): The co-ordinate of position 1
-- x2, y2, z2 (number): The co-ordinate of position 2
-- distance (number): The distance
-- x, y, z (number): The position co-ordinate

Back to Category

GetPositionFromPosition

Gets the position from a specific position.

x, y, z = GetPositionFromPosition(x1, y1, z1, distance, facing, pitch)
-- x1, y1, z1 (number): The co-ordinate of the start position
-- distance (number): The distance from the start position
-- facing (number): The horizontal angle from the start position, in radian
-- pitch (number): The vertical angle from the start position, in radian
-- x, y, z (number): The target position co-ordinate

Back to Category

SetMouseoverObject

Sets the object of mouseover, pointed by mouse cursor.

SetMouseoverObject(object)
-- object (string): The ID of the mouseover object

Back to Category

ObjectAnimationState

Gets the animation state of an object.

state = ObjectAnimationState(object)
-- object (string): The ID of the object
-- state (number): The animation state, usually representing "bobbing" (nil if the object does not exist)

Back to Category

ObjectCreator (aka UnitCreator)

Gets the creator of an object.

creator = ObjectCreator(object)
-- object (string): The ID of the object
-- creator (string): The ID of the object creator (nil if the object or its creator does not exist)

Back to Category

ObjectDynamicFlags

Gets the dynamic flags of an object, which is actually the "CGObjectData__m_dynamicFlags" offset.

flags = ObjectDynamicFlags(object)
-- object (string): The ID of the object
-- flags (number): The dynamic flags of the object (nil if the object does not exist)

Back to Category

ObjectExists

Checks whether an object exists in memory.

existence = ObjectExists(object)
-- object (string): The ID of the object
-- existence (boolean): Whether the object exists

Back to Category

ObjectFacing

Gets the horizontal rotation of an object, in radian.

facing = ObjectFacing(object)
-- object (string): The ID of the object
-- facing (number): The horizontal rotation of the object, in radian (nil if the object does not exist)

Back to Category

ObjectField (aka ObjectDescriptor)

Gets the value of a specific field (previously descriptor) of an object.

value = ObjectField(object, offset, type)
-- object (string): The ID of the object
-- offset (number): The memory offset of the field, in bytes (see GetObjectDescriptorsTable() and GetObjectFieldsTable())
-- type (number): The field value type (see GetValueTypesTable())
-- value (boolean | number | string): The field value (nil if the object does not exist)

Back to Category

ObjectHeight

Gets the display height of the object.

height = ObjectHeight(object)
-- object (string): The ID of the object
-- height (number): The display height of the object (nil if the object does not exist)

Back to Category

ObjectId

Gets the numeric ID of an object, which is part of the object GUID.

id = ObjectId(object)
-- object (string): The ID of the object.
-- id (number): The number ID of the object (nil if the object does not exist)

Back to Category

ObjectIsBehind

Checks if an object is behind another object.

isBehind = ObjectIsBehind(object1, object2)
-- object1 (string): The ID of object 1
-- object2 (string): The ID of object 2
-- isBehind (number): Whether object 1 is behind object 2 (nil if either of the objects does not exist)

Back to Category

ObjectIsFacing

Checks if an object is facing another object.

isFacing = ObjectIsFacing(object1, object2[, tolerance = PI/2])
-- object1 (string): The ID of object 1
-- object2 (string): The ID of object 2
-- tolerance (number): The facing check tolerance, in radian (if the angle in between goes beyond that, the API returns false)
-- isFacing (boolean): Whether object 1 is facing object 2

Back to Category

ObjectIsQuestObjective

Checks whether an object is tracked in current quests (usually glowing). This is a RETAIL-only API.

isInQuestCache = ObjectIsQuestObjective(object, unknown)
-- object (string): The ID of the object
-- unknown (boolean): An unknown flag
-- isInQuestCache (boolean): Whether the object is tracked in the quest cache

Back to Category

ObjectIsType

Checks if an object is of a specific type, which can be a value from GetObjectTypeFlagsTable.

isOrNot = ObjectIsType(object, type)
-- object (string): The ID of the object
-- type (number): The object type to check
-- isOrNot (boolean): Whether the object is of the type

Back to Category

ObjectPosition

Gets the world position of an object.

x, y, z = ObjectPosition(object)
-- object (string): The ID of the object
-- x, y, z (number): The position co-ordinate of the object

Back to Category

ObjectQuestGiverStatus

Gets the quest giver status of a specific object, which can be a value from GetObjectQuestGiverStatusesTable.

status = ObjectQuestGiverStatus(object)
-- object (string): The ID of the object
-- status (number): The status of the object

Back to Category

ObjectQuests

Gets the IDs of the related quests of an object. This is a RETAIL-only API.

id1, id2, ... = ObjectQuests(object)
-- object (string): The ID of the object
-- id ... (number): The IDs of the related quests

Back to Category

ObjectRelativePosition

Gets the relative world position of an object to its "carrier".

x, y, z = ObjectRelativePosition(object)
-- object (string): The ID of the object
-- x, y, z (number): The relative position co-ordinate of the object

Back to Category

ObjectRelativeFacing

Gets the relative rotation of an object to its "carrier", in radian.

facing = ObjectRelativeFacing(object)
-- object (string): The ID of the object
-- facing (number): The relative facing of the object, in radian

Back to Category

ObjectScale

Gets the scale of an object.

scale = ObjectScale(object)
-- object (string): The ID of the object
-- scale (number): The scale of the object

Back to Category

ObjectTypeFlags

Gets the type flags of an object, which should be one of GetObjectTypeFlagsTable.

typeFlags = ObjectTypeFlags(object)
-- object (string): The ID of the object
-- typeFlags (number): The type flags of the object

Back to Category

UnitBoundingRadius

Gets the bounding radius of an unit.

radius = UnitBoundingRadius(unit)
-- unit (string): The ID of the unit object
-- radius (number): The bounding radius of the object, in yards

Back to Category

UnitCasting

Gets the casting spell info of a specific unit. Similar to Blizzard's UnitCastingInfo but it adds additional information about the spell target.

spellId, target, startTime, endTime = UnitCasting(unit)
-- unit (string): The ID of the unit object
-- spellId (number): The casting spell ID (nil if the unit or spell does not exist)
-- target (string): The ID of the casting target unit
-- startTime (number): The start time of the casting spell
-- endTime (number): The end time of the casting spell

Back to Category

UnitCastingTarget

Gets the casting spell target of a specific unit.

target = UnitCastingTarget(unit)
-- unit (string): The ID of the unit object
-- target (string): The ID of the casting target unit (nil if the unit or casting spell does not exist)

Back to Category

UnitChannel

Gets the channel spell info of a unit. Similar to Blizzard's UnitChannelInfo but it adds additional information about the spell target.

spellId, target, startTime, endTime = UnitChannel(unit)
-- unit (string): The ID of the unit object
-- spellId (number): The channel spell ID (nil if the unit or spell does not exist)
-- target (string): The ID of the casting target unit
-- startTime (number): The start time of the casting spell
-- endTime (number): The end time of the casting spell

Back to Category

UnitCombatReach

Gets the combat reach of a unit.

combatReach = UnitCombatReach(unit)
-- unit (string): The ID of the unit object
-- combatReach (number): The combat reach of the unit, in yards (nil if the unit does not exist)

Back to Category

UnitCreatureTypeId

Gets the ID of the creature type of a specific unit.

typeId = UnitCreatureTypeId(unit)
-- unit (string): The ID of the unit object
-- typeId (number): The ID of the unit's creature type (nil if the unit does not exist)

Back to Category

UnitCreatureFamilyId

Gets the ID of the family of a specific unit.

familyId = UnitCreatureFamilyId(unit)
-- unit (string): The ID of the unit object
-- familyId (number): The ID of the unit's creature family (nil if the unit does not exist)

Back to Category

UnitCreatureField

Gets a field value of the creature cache struct of a specific unit.

value = UnitCreatureField(unit, offset, type)
-- unit (string): The ID of the unit object
-- offset (number): The offset of the field in creature cache, in bytes
-- type (number): The field value type (see GetValueTypesTable())
-- value (boolean | number | string): The actual field value (nil if the unit does not exist)

Back to Category

UnitFlags

Gets the flags of a specific unit, which is located at the descriptor "CGUnitData__flags".

flags = UnitFlags(unit)
-- unit (string): The ID of the unit object
-- flags (number): The flags value (nil if the unit does not exist)

Back to Category

UnitIsLootable

Checks whether a unit is lootable.

lootable = UnitIsLootable(unit)
-- unit (string): The ID of the unit object
-- lootable (boolean): Whether the unit is lootable

Back to Category

UnitIsMounted

Checks whether a unit is mounted.

mounted = UnitIsMounted(unit)
-- unit (string): The ID of the unit object
-- mounted (boolean): Whether the unit is mounted

Back to Category

UnitIsSkinnable

Checks whether a unit is skinnable.

mounted = UnitIsSkinnable(unit)
-- unit (string): The ID of the unit object
-- mounted (boolean): Whether the unit is skinnable

Back to Category

UnitMovementField

Gets a field value of the movement struct of a specific unit.

value = UnitMovementField(unit, offset, type)
-- unit (string): The ID of the unit object
-- offset (number): The offset of the field in movement struct, in bytes
-- type (number): The field value type (see GetValueTypesTable())
-- value (boolean | number | string): The actual field value (nil if the unit does not exist)

Back to Category

UnitMovementFlags

Gets the flags in the movement struct of a specific unit, which indicates its movement status.

flags = UnitMovementFlags(unit)
-- unit (string): The ID of the unit object
-- flags (number): The movement flags of the unit (nil if the unit does not exist)

Back to Category

UnitPitch

Gets the pitch (vertical angle) of a unit, in radian.

pitch = UnitPitch(unit)
-- unit (string): The ID of the unit object
-- pitch (number): The pitch of the unit (nil if the unit does not exist)

Back to Category

UnitSkinningType

Gets the type of a skinnable unit.

skinningType = UnitSkinningType(unit)
-- unit (string): The ID of the unit object
-- skinningType (number): The type ID of the skinnable unit (nil if the unit does not exist)

Back to Category

UnitTarget

Gets the target unit of a specific unit.

target = UnitTarget(object)
-- unit (string): The ID of the unit object
-- target (string): The ID of the unit's target unit object (nil if the unit or its target unit does not exist)

Back to Category

UnitTransport

Gets the transport object on which a specific unit stands.

transport = UnitTransport(unit)
-- unit (string): The ID of the unit object
-- transport (string): The ID of the unit's transport object (nil if the unit or its transport does not exist)

Back to Category

In-World (Object Manager)

The following in-world API functions read all WoW objects living in memory. The functions are implemented in pairs, of which one is GetXXXCount() that needs to be called first upon each frame to cache all current objects and another is GetXXXWithIndex() that is used to retrieve any one of them.

Back to Table of Contents

GetAreaTriggerCount

Gets the count of specific area triggers, optionally within a certain range.

count = GetAreaTriggerCount([center | x, y, z][, range])
-- center (string): The ID of the center object
-- x, y, z (number): The co-ordinate of the center position
-- range (number): The radius of the range, in yards
-- count (number): The count of area triggers within the range

Back to Category

GetAreaTriggerWithIndex

Gets a specific area trigger in the previously saved cached objects from GetAreaTriggerCount.

areaTrigger = GetAreaTriggerWithIndex(index)
-- index (number): The index of the cached area trigger, starting from 1
-- areaTrigger (string): The ID of the area trigger

Back to Category

GetDynamicObjectCount

Gets the count of specific dynamic objects, optionally within a certain range.

count = GetDynamicObjectCount([center | x, y, z][, range])
-- center (string): The ID of the center object
-- x, y, z (number): The co-ordinate of the center position
-- range (number): The radius of the range, in yards
-- count (number): The count of dynamic objects within the range

Back to Category

GetDynamicObjectWithIndex

Gets a specific dynamic object in the previously saved cached objects from GetDynamicObjectCount.

dynamicObject = GetDynamicObjectWithIndex(index)
-- index (number): The index of the cached dynamic object, starting from 1
-- dynamicObject (string): The ID of the dynamic object

Back to Category

GetGameObjectCount

Gets the count of specific game objects, optionally within a certain range.

count = GetGameObjectCount([center | x, y, z][, range])
-- center (string): The ID of the center object
-- x, y, z (number): The co-ordinate of the center position
-- range (number): The radius of the range, in yards
-- count (number): The count of game objects within the range

Back to Category

GetGameObjectWithIndex

Gets a specific game object in the previously saved cached objects from GetGameObjectCount.

gameObject = GetGameObjectWithIndex(index)
-- index (number): The index of the cached game object, starting from 1
-- gameObject (string): The ID of the game object

Back to Category

GetNpcCount

Gets the count of specific NPCs (non-player unit), optionally within a certain range.

count = GetNpcCount([center | x, y, z][, range][, rangeOption])
-- center (string): The ID of the center object
-- x, y, z (number): The co-ordinate of the center position
-- range (number): The radius of the range, in yards
-- rangeOption (number): Specifies the meaning of range, which is one of the several values given below
{
    direct = 0; -- raw distance between myself and the unit
    target_reach_only = 1; -- consider only the unit reach on top of the range
    both_reaches = 2; -- consider both reaches of myself and the unit on top of the range
    both_melee_reaches = 3; -- consider the unit as a melee target on top of the range
    both_melee_reaches_with_movement = 4; -- consider the unit as a moving melee target on top of the range
}
-- count (number): The count of NPCs within the range

Back to Category

GetNpcWithIndex

Gets a specific NPC (non-player unit) in the previously saved cached objects from GetNpcCount.

npc = GetNpcWithIndex(index)
-- index (number): The index of the cached NPC, starting from 1
-- npc (string): The ID of the NPC

Back to Category

GetObjectCount

Gets the count of all WoW objects as well as the changes compared to the last call. Notice that a better performance is given when you refer to a more filtered version such as GetNpcCount.

count, isUpdated, addedObjects, removedObjects = GetObjectCount()
-- count (number): The count of all WoW objects
-- isUpdated (boolean): Whether the WoW objects experience any changes from the last call
-- addedObjects (table): The IDs of added WoW objects
-- removedObjects (table): The IDs of removed WoW objects

Back to Category

GetObjectWithIndex

Gets a specific WoW object by its index in the previously saved cached objects from GetObjectCount.

object = GetObjectWithIndex(index)
-- index (number): The index of the cached object, starting from 1
-- object (string): The ID of the object

Back to Category

GetPlayerCount

Gets the count of specific players, optionally within a certain range.

count = GetPlayerCount([center | x, y, z][, range][, rangeOption])
-- center (string): The ID of the center object
-- x, y, z (number): The co-ordinate of the center position
-- range (number): The radius of the range, in yards
-- rangeOption (number): Specifies the meaning of range, which is one of the several values given below
{
    direct = 0; -- raw distance between myself and the unit
    target_reach_only = 1; -- consider only the unit reach on top of the range
    both_reaches = 2; -- consider both reaches of myself and the unit on top of the range
    both_melee_reaches = 3; -- consider the unit as a melee target on top of the range
    both_melee_reaches_with_movement = 4; -- consider the unit as a moving melee target on top of the range
}
-- count (number): The count of players within the range

Back to Category

GetPlayerWithIndex

Gets a specific player in the previously saved cached objects from GetPlayerCount.

player = GetPlayerWithIndex(index)
-- index (number): The index of the cached player, starting from 1
-- player (string): The ID of the player

Back to Category

In-World (Spell)

The following in-world API functions provide extensions for spells.

Back to Table of Contents

CancelPendingSpell

Cancels the pending spell on the cursor.

CancelPendingSpell()

Back to Category

GetActiveSpellCount

Gets the count of active spells, which will be cached in memory in the current frame.

count = GetActiveSpellCount()
-- count (number): The count of active spells

Back to Category

GetActiveSpellWithIndex

Gets the details of a specific active spell, previously stored by GetActiveSpellCount

spellId, auraId, caster, sourceX, sourceY, sourceZ, targetX, targetY, targetZ, facing = GetActiveSpellWithIndex(index)
-- index (number): The index of the cached active spell, starting from 1
-- spellId (number): The ID of the spell
-- auraId (number): The ID of the aura spell
-- caster (string): The ID of the caster unit
-- sourceX, sourceY, sourceZ (number): The source position co-ordinate of the spell cast
-- targetX, targetY, targetZ (number): The target position co-ordinate of the spell cast
-- facing (number): The horizontal angle of the spell object, in radian

Back to Category

GetAuraCount

Gets the count of the auras on a unit, which will be cached in memory in the current frame.

count = GetAuraCount(unit, [spellId])
-- unit (string): The ID of the unit
-- spellId (number): Specifies the ID of the aura spell
-- count (number): The count of auras found

Back to Category

GetAuraWithIndex

Gets the spell ID of a specific aura, previously stored by GetAuraCount.

spellId = GetAuraWithIndex(index)
-- index (number): The index of the cached aura, starting from 1
-- spellId (number): The ID of the aura spell when detailed is false

Back to Category

GetMissileCount

Gets the count of missile spells around, which will be cached in memory in the current frame.

count = GetMissileCount()
-- count (number): The missile count

Back to Category

GetMissileWithIndex

Gets the details of a specific missile spells, previously stored by GetMissileCount.

spellId, spellVisualId, x, y, z, sourceObject, sourceX, sourceY, sourceZ, targetObject, targetX, targetY, targetZ = GetMissileWithIndex(index)
-- spellId (number): The ID of the missile spell
-- spellVisualId (number): The visual ID of the missile spell
-- x, y, z (number): The co-ordinate of the current missile position
-- sourceObject (string): The ID of the source object
-- sourceX, sourceY, sourceY (number): The co-ordinate of the source position
-- targetObject (string): The ID of the target object
-- targetX, targetY, targetY (number): The co-ordinate of the target position

Back to Category

GetPendingSpell

Gets the ID of the pending spell.

spellId = GetPendingSpell()
-- spellId (number): The ID of the pending spell (nil if no spell is pending)

Back to Category

In-World (State)

The following in-world API functions read world states.

Back to Table of Contents

GetCurrentAccount

Gets the current WoW account name, which is the same as the WTF sub folder name.

account = GetCurrentAccount()
-- account (string): The account name

Back to Category

GetCurrentTime

Gets the current WoW calendar time.

time1, time2, time3, time4, time5, time6 = GetCurrentTime()
-- time1-6 (number): The number segments of the calendar time

Back to Category

In-World (Vision)

The following in-world API functions provide vision information.

Back to Table of Contents

GetCameraPosition

Gets the position of the camera.

x, y, z = GetCameraPosition()
-- x, y, z (number): The co-ordinate of the camera position

Back to Category

ScreenToWorld

Projects a screen NDC position to a world position, along with a world object if any.

x, y, z[, object] = ScreenToWorld(screenX, screenY)
-- screenX, screenY (number): The co-ordinate of the screen NDC position (ranging from 0.0 to 1.0)
-- x, y, z (number): The co-ordinate of the world position
-- object (string): The ID of the world object at the position, if any

Back to Category

TraceLine

Checks ray cast intersection from a certain position to another.

x, y, z = TraceLine(x1, y1, z1, x2, y2, z2, flags)
-- x1, y1, z1 (number): The co-ordinate of position 1
-- x2, y2, z2 (number): The co-ordinate of position 2
-- flags (number): The flags of surface facets the ray cast should be considered as "intersected", which can be any sum of the followings:
{
    None                = 0x00000000,
    DoodadCollision     = 0x00000001,
    DoodadRender        = 0x00000002,
    WmoCollision        = 0x00000010,
    WmoRender           = 0x00000020,
    WmoNoCamCollision   = 0x00000040,
    Terrain             = 0x00000100,
    IgnoreWmoDoodad     = 0x00002000,
    LiquidWaterWalkable = 0x00010000,
    LiquidAll           = 0x00020000,
    Cull                = 0x00080000,
    EntityCollision     = 0x00100000,
    EntityRender        = 0x00200000,
    Collision           = DoodadCollision | WmoCollision | Terrain | EntityCollision,
    LineOfSight         = WmoCollision | EntityCollision
}
-- x, y, z (number): The co-ordinate of the first intersection position of the ray cast (nil if no intersection is found)

Back to Category

WorldToScreen

Projects a world position to the screen NDC position.

isOnScreen, screenX, screenY = WorldToScreen(object | x, y, z)
-- object (string): The ID of an object whose position will be projected
-- x, y, z (number): The co-ordinate of the world position
-- isOnScreen (boolean): Whether the object is within the screen frame
-- screenX, screenY (number): The screen NDC position

Back to Category