wizSDK Documentation¶

Client¶

class wizsdk.Client(handle=None, silent_mouse=False)¶

Bases: wizsdk.pixels.DeviceContext, wizsdk.keyboard.Keyboard, wizsdk.window.Window

Main class for wizSDK.

Example

# registers a new client
player = client.register(name="My Bot")
await player.activate_hooks()

async activate_all_hooks()¶: Activate all hooks (including special hooks like “mouseless_cursor_move”)

async activate_hooks(*hook_names)¶: Activate all hooks excluding special hooks like “mouseless_cursor_move”

async activate_silent_mouse_hook()¶

async autocast(*spells: str, target=None)¶

Short-hand for find_spell followed by cast_spell. Finds and casts spells. If 2 spells are provided, it will enchant spell 2 with spell 1. If target is provided, it will click the target. If any of the spells are not found, this function exits with False.

Parameters

spells – provide up to 2 spell arguments
target (int, optional) – the target to cast the spell on. See Card.cast

Returns

True if all spells were found, False otherwise

Examples

player = Client.register(name="Bot")
battle = player.get_battle("Test")
# Loop
while await battle.loop():
    # The following are all correct ways of using `autocast`
    await player.autocast("epic", "bat", target=0)
    await player.autocast("epic", "tempest")
    await player.autocast("storm-blade", target=4)

async click_confirm(*, timeout=None)¶

Waits for the “confirm” prompt, and clicks “confirm”

Parameters: timeout (optional) – value in seconds to timeout if it hasn’t finished yet. Defaults to None
Returns: True if the function completed successfully, False if the function timed out.

async face_quest_destination() → None¶: Changes the player’s yaw to be facing the quest destination. Note: depending on your location, this may differ from where your quest arrow is pointing to

async find_spell(spell_name: str, threshold: float = 0.12, ignore_gray_detection=False) → wizsdk.card.Card¶

Searches spell area for an image matching spell_name. An additional check to see if the spell is grayed out is done by default.

Parameters

spell_name (str) – The name of the spell as you have it saved in your spells image folder.
threshold (float) – How precise the match should be. The lower this value, the more exact the match will be.
ignore_gray_detection (bool) – should the gray detection be ignored. defaults to False

Returns

x positions of spell if found, None otherwise

Return type

int

async finish_loading(*, timeout=None) → bool¶

Waits for player to have gone through the loading screen. If this function is called too late and the player is already out of the loading screen, it will wait indefinitely.

Parameters: timeout (optional) – value in seconds to timeout if it hasn’t finished yet. Defaults to None
Returns: True if the function completed successfully, False if the function timed out.

async get_backpack_space_left() → Optional[int]¶

Gets the backpack space left. Will try to refresh the value by quickly opening and closing the backpack if necessary. Returns None if it wasn’t able to get the value.

Returns: space left in the backpack, None if it’s not able to get the value.

get_battle(name: Optional[str] = None) → wizsdk.battle.Battle¶

Fetch a battle associated with the client

Parameters: name (str) – Name of battle for logging purposes.
Returns: object with battle methods linked to this client
Return type: Battle

get_confirm()¶

Detects if a “confirm” prompt is open (either from teleporting a friend or exiting an unfinished dungeon). It does this by matching a “confirm” image.

Returns: (x, y) where the confirm button has been found
Return type: tuple

async get_gold() → int¶

Gets gold value from memory.

Returns: The player’s gold value as an int

async get_health() → int¶: Gets health value from memory. :returns: The health value of the player as an int

async get_health_max() → int¶

Gets maximum health value from memory.

Returns: The max health value of the player as an int

async get_health_percentage() → int¶

Gets health, and max health value from memory then divides them. For accurate values, only use after finishing a fight or after getting whisps. Returns 99,999 if the stats hook hasn’t run.

Returns: The health percentage of the player as an int rounded down to the first decimal.

async get_mana() → int¶

Gets mana value from memory.

Returns: The mana value of the player as an int

async get_mana_max() → int¶

Gets maximum mana value from memory.

Returns: The maximum mana value of the player as an int

async get_mana_percentage() → int¶

Gets health, and max health value from memory then divides them.

Returns: The health percentage of the player as an int rounded down to the first decimal.

async get_player_level() → int¶

Gets player level value from memory.

Returns: The level of the player as an int

async get_player_location() → wizsdk.utils.XYZYaw¶

Fetches the player’s XYZYaw location Requires the player_struct hook to be activated

Returns: (X, Y, Z, Yaw) tuple values of the player’s position and direction.
Return type: XYZYaw

async get_quest_xyz() → tuple¶

Gets the X, Y, Z coordinates to the quest destination Requires the quest_struct hook to be activated

Returns: (X, Y, Z) value of the quest goal location.
Return type: tuple

async go_through_dialog(times=1, *, timeout=None)¶

Goes through the prompts of the dialog (“press x” or “more”/”continue”). Waits for “press x” or the dialog box before starting.

Parameters

times (int) – Defaults to 1 The number of times to repeat. (When going through quests, you might need to set this to 2. There’s one to hand in the quest, the second to get the next quest)
timeout (optional) – value in seconds to timeout if it hasn’t finished yet. Defaults to None

Returns

True if the function completed successfully, False if the function timed out.

is_crown_shop() → bool¶

Detects if the crown shop is open by matching a red pixel in the “close” icon.

Returns: True if the menu is open / False otherwise
Return type: bool

is_dialog_more()¶

Detects if the dialog (from NPCs etc.) is open by matching pixels in the “more” or “done” button.

Returns: True if the dialog menu is open / False otherwise
Return type: bool

is_health_low()¶

DEPRECATED: Detects if the player’s health is low by matching a red pixel in the lower third of the globe.

Returns: is the health low
Return type: bool

is_idle()¶

Detects if the player is idle (out of loading and not in battle) by matching pixels in the spellbook.

Returns: True if the player is idle / False otherwise
Return type: bool

is_mana_low()¶

DEPRECATED: Detects if the player’s mana is low by matching a blue pixel in the lower third of the globe.

Returns: is the mana low
Return type: bool

async is_move_locked()¶

Detects if player is locked in combat

Returns: Whether player is move locked by combat or not.
Return type: bool

is_press_x()¶

Detects if the “press x” prompt is present by matching the “x” image.

Returns: “press X” has been found
Return type: bool

log(message: str)¶: Debug log function. Useful to identify which client the log is coming from. :param message: The message to log. [client-name]: message :type message: str

async logout_and_in(confirm=False, *, confirm_timeout=None, timeout=None)¶

Logs the user out and then logs it in again.

Parameters

confirm (bool, optional) – Should the bot wait for a “confirm” prompt before continuing. Defaults to False Set to True if logging out durring a battle or to exit an unfinished dungeon.
confirm_timeout – timeout argument for the click_confirm task. Defaults to None
timeout – time in seconds before the function times out. Defaults to None

Returns

True if the function completed successfully, False if the function timed out.

async pass_turn() → None¶: Clicks pass while in a battle

async press_x(*, timeout=None)¶

Waits for the “press x” prompt and sends the “X” key.

Parameters: timeout (optional) – value in seconds to timeout if it hasn’t finished yet. Defaults to None
Returns: True if the function completed successfully, False if the function timed out.

classmethod register(nth=0, name=None, handle=None, silent_mouse: bool = False)¶

Assigns the instance to a wizard101 window. (Required before using any other SDK methods)

Parameters

nth (int, optional) – Index of the wizard101 client to use (if there’s more than one)
name (str, optional) – Name to prepend to the window title. Used for identifying which windows are controlled.
silent_mouse – When enabled, moves the mouse without taking control of the actual cursor

set_name(name: str)¶: Sets the window title. Useful to identify which window the bot is running on :param name: The text to prepend to the window title :type name: str

async teleport_to(location: wizsdk.utils.XYZYaw)¶

Teleports to XYZYaw location Will return immediately if player movement is locked Requires the player_struct hook to be activated

Parameters: location (XYZYaw) – location to move to

async teleport_to_friend(match_img) → bool¶

Completes a set of actions to teleport to a friend. The friend must have the proper symbol next to it. The symbol must match the image passed as ‘match_img’.

Parameters: match_img – A string of the image file name, or a list of bytes returned by Client.get_image The friend icon to find to select which friend to teleport to.
Returns: Whether the friend was found or not.
Return type: bool

async unregister()¶: Properly unregister hooks and clean up possible ongoing asyncio tasks

async use_potion_if_needed(health=1000, mana=20)¶

Clicks on a potion if health or mana values drop below the settings

Parameters

health – Health value threshold. Potion will be used if health value drops below
mana – Mana value threshold. Potion will be used if mana value drops below

Returns

None

async wait(seconds: float)¶

Alias for asyncio.sleep()

Parameters: seconds (float) – number of seconds to “sleep”

async walk_to(location: wizsdk.utils.XYZYaw, mount_speed: float = - 1)¶

Walks to XYZYaw location in a straight line only. Will _not_ work if there are obstacles in the way. Ideal for short distances Will return immediately if player movement is locked Requires the player_struct hook to be activated.

Parameters: location (XYZYaw) – The location to walk to. (Only the x and y value will actually be used)

Defaults¶

wizsdk.client.SPELLS_FOLDER = 'spells'¶: Default folder to look for spells in

wizsdk.client.IMAGE_FOLDER = ''¶: Default folder to look for images in.

wizsdk.client.DEFAULT_MOUNT_SPEED = 1.4¶: Default mount speed (40%)

Helpers¶

wizsdk.client.register_clients(n_handles_expected: int, names: list = [], confirm_position: bool = False, silent_mouse: bool = False) → list¶

Register multiple clients, sorted from left to right, top to bottom.

Parameters

n_handles_expected (int) – the expected # of wiz windows opened. Use -1 for undetermined
names (list) – A list of strings that will serve as the names of the windows
confirm_position (bool) – prompt the user to confirm the windows order before continuing
silent_mouse – When enabled, moves the mouse without taking control of the actual cursor

Returns

A list populated with Client instances

Return type

client_list (list)

async wizsdk.client.unregister_all()¶: Properly unregisters all clients

Battle¶

class wizsdk.Battle(client, name=None, default_image_folder='')¶

Battle class

Example

# register the client
p1 = Client.register(name="Bot")
# Get a battle object from the client
battle = p1.get_battle("Test")
# Loop
while await battle.loop():
    if battle.round_count == 1:
        # pass on the first round
        p1.pass_turn()
    else:
        # Cast enchanted tempest
        temp = await p1.find_spell("tempest")
        epic = await p1.find_spell("epic")

        if temp and epic:
            e_temp = await epic.enchant(temp)
            await e_temp.cast()
        else:
            await p1.pass_turn()

find_ally(ally_image)¶: Attemps to find the position of an ally the matches the image provided returns 4, 5, 6, 7 if found otherwise returns False

find_enemy(enemy_image)¶: Attemps to find the position of an enemy that matches the image provided returns 0, 1, 2, 3 if found otherwise returns False

get_enemy_count()¶: Returns the number enemies in the fight

get_enemy_positions()¶

Gets the indices of the enemies present

Examples

# Register
player = client.register(name="test")
# Get the battle
battle = player.get_battle()
while await battle.loop():
    enemies = battle.get_enemy_positions() # -> [0, 1]
    print(len(enemies)) # -> 2
    # Get the position of the first enemy in battle
    first_enemy = enemies[0] # -> 0
    # Get spell
    firecat = await player.find_spell('firecat') # -> Card
    if firecat:
        # Cast at enemy position
        await firecat.cast(target=first_enemy)

property going_first¶: True if your team is going first, False if enemies are going first. Value is set once at the beginning of the fight.

async loop()¶

Handles the looping logic for a battle. The loops exists when the battle ends.

Examples

while await battle.loop():
    print(battle.round_count)
    print(battle.enemy_first)
    print(battle.get_enemy_count())

property round_count¶: Current round of the fight. Starts at 1

Card¶

class wizsdk.Card(client, name, spell_x)¶

Bases: object

async cast(target=None)¶

Selects spell. If target is specified, it clicks on target (0-3 for enemies, 4-7 for allies)

0 1 2 3
-------
7 6 5 4

Parameters: target (int, optional) – The target to select after clicking the spell

async enchant(spell: None) → None¶

Enchants spell with self.

Returns: A new Card object representing the new enchanted spell

Keyboard¶

class wizsdk.Keyboard(window_handle)¶

Keyboard class. Sends events directly to the client. Must pass in window_handle of the client to use.

async hold_key(key, seconds=0.1)¶

Hold down a key for an amount of time. The key is sent directly to the client, the client does not need to be in focus.

Parameters

key (str) – The key to hold down. “TAB”, “ENTER”, “ALT”, “ESC”, “SPACE” and others are also accepted as special keys
seconds (int, optional) – duration to hold for

key_down(key)¶

Hold down a key. Call key_up to release.

Parameters: key (str) – The key to hold down

key_up(key=None)¶

Release a key that has been pressed down

Parameters: key (str, optional) – The key to release If no key is specified, all keys will be released

async send_key(key, seconds=0.1)¶: Alias for hold_key

type_key(char)¶

Sends a key to the client. This is a different event than send_key and is only useful for the chat window.

Parameters: char – The character to type “TAB”, “ENTER”, “ALT”, “ESC”, “SPACE” and others are also accepted as special keys

type_string(string)¶

Type a string of letters directly to the window.

Parameters: string – the text to type

Mouse¶

class wizsdk.Mouse(window_handle=None, silent_mode=False, walker=None)¶

Bases: wizsdk.window.Window

Class for controlling the computer’s mouse.

async click(x=- 1, y=- 1, button='left', duration=None, delay=0.1)¶: Click at the specified placed

double_click(pos=(- 1, - 1), button='left')¶: Double click at the specifed placed

failSafeCheck()¶

get_position()¶: get mouse position

get_rel_position()¶: get mouse position relative to window

in_rect(rect_area)¶: Returns true if the mouse is in the given region

async init_silent_mode()¶

async move_out(rect_area)¶: Move the mouse outside of the given rect If the mouse is already outside, return

async move_to(x, y, duration=0.5)¶: Move the mouse to the x, y coordinates relative to the window

wizsdk_client_coords_to_wizwalker(x: int, y: int) → tuple¶: Converts WizSDK client coords to wizwalker client coords

DeviceContext¶

class wizsdk.DeviceContext(handle)¶

Bases: wizsdk.window.Window

Base class for accessing the Window’s Device Context (pixels, image captures, etc..)

get_image(region=None)¶

returns a byte array with the pixel data of the region from the window_handle window. region is relative to the window_handle window. If no region is specified, it will capture the entire window. If no window_handle is provided on initiation, monitor 1 is used as the context.

Parameters: region – (x, y, width, height) tuple relative to the window_handle context. Defaults to None
Returns: A 2d numpy array representing the pixel data of the captured region.

get_pixel(x, y) → tuple¶

Returns the (red, green, blue) channel’s of the pixel at x, y relative to the window_handle context.

Parameters

x –
y –

Returns

(r, g, b) tuple

is_gray_rect(region, threshold=25)¶

calculates if a (x, y, width, height) region is gray by iterating through all its pixels and calculating the difference between the channel with the lowest value, and the one with the highest value. Stops iterating if that value is greater than threshold. Returns the highest of the values calculated.

Parameters

region – (x, y, width, height) tuple relative to the window_handle context.
threshold – difference allowed between highest channel and lowest channel to still be considered gray.

Returns

the greatest difference between the highest channel and lowest channel.

locate_on_screen(match_img, region=None, *, threshold=0.1, debug=False, folder=None)¶

Attempts to locate match_img in the Wizard101 window. pass a rect tuple (x, y, width, height) as the region argument to narrow down the area to look for the image. Adjust threshold for the precision of the match (between 0 and 1, the lowest being more precise). Set debug to True for extra debug info

Parameters

match_img – to image to locate, can be a file name or a numpy array
region – (x, y, width, height) tuple relative to the window_handle context. Defaults to None
theshold – precision of the match – between 0 and 1, the lowest being more precise
debug – set to True to show a pop up of the area that matched the image provided.
folder – folder to look in. Overrides IMAGE_FOLDER default

Returns

(x, y) tuple for center of match if found. False otherwise.

pixel_matches_color(xy, expected_rgb, tolerance=0)¶: gets the value of a pixel with get_pixel and checks it against expected_rgb. Accepts tolerance amount of differences between the pixel and its expected value.

screenshot(filename, region=None)¶

captures a screenshot of the provided region, saves it to file as filename.

Parameters

filename – what to save to image as
region – (x, y, width, height) tuple relative to the window_handle context. Defaults to None

Window¶

class wizsdk.Window(handle=None)¶

Base class for all classes in wizSDK. Keeps track of the wizard101 app window.

get_rect() → tuple¶

Gets the area rectangle of the window (x, y, width, height) relative to the monitor position.

Returns: tuple (x, y, width, height) of the window

is_active() → bool¶: Returns true if the window is focused

set_active()¶: Sets the window to active if it isn’t already

Hot Keys¶

class wizsdk.HotkeyEvents(debug=False)¶

Hotkey event manager class

Examples

import wizsdk
import asyncio

# Initiate the event manager
events = wizsdk.HotkeyEvents()

# Add hotkeys
def print_hello():
    print("Hello, world!")

events.set_hotkey("ctrl + q", events.safe_quit) # safetly quit the program
events.set_hotkey("SPACEBAR", print_hello)
events.set_hotkey("Left mouse", lambda: print("click"))


async def main_function():
    # main script goes here

# run the two coroutines at the same time
wizsdk.run_threads(events.listen(), main_function())

async listen()¶: starts an event loop that will listen for key presses and call actions triggered by the hotkeys.

async safe_quit()¶: Safetly quit the program by first un-hooking all clients.

set_hotkey(trigger: str, action)¶

Registers a hotkey

Parameters

trigger – the hotkey(s) that will trigger the action. Separate multiple keys with a +
action – the function that will run when the hotkey is triggered. This can be a regular or an ``await``able function

unset_hotkey(trigger)¶

Removes a previously set hotkey

Parameters: trigger – the same trigger used to register the hotkey

Utils¶

wizsdk.utils.count_wiz_clients() → int¶

Returns the number of wizard101 clients detected

Returns: Number of wizard101 clients detected

async wizsdk.utils.finish_all_loading(*players)¶: Wait for all players passed in as arguments to have gone through the loading screen.

wizsdk.utils.get_all_wiz_handles() → list¶

Retrieves all window handles for windows that have the ‘Wizard Graphical Client’ class

Returns: List of all the wizard101 device handles

wizsdk.utils.packaged_img(filename: str = '')¶

Helper function to reference images packaged within the WizSDK module

Returns: Full file path to the packaged image.

wizsdk.utils.run_threads(*coroutines, return_when='FIRST_COMPLETED')¶

creates an asyncio event loop to run coroutines concurrently

Parameters

coroutines – any amount of coroutines to run at the same time
return_when – when to stop the threads and return: asyncio.FIRST_COMPLETED, asyncio.ALL_COMPLETED, or asyncio.FIRST_EXCEPTION