uo.dll API

uo.dll is the EasyUO engine packaged as a DLL, for programs written in other languages: the same client reading and automation that EasyUO scripts use, called from your own code. EasyUO Reforged itself does not need it; it only matters if you write such a program. Keep uo.dll next to your program, or give its full path.

How it works

Everything goes through a handle and a stack of values.

Open returns a handle. Each handle has its own stack and its own attached client.
To do something, push the command, the name and any values onto the stack, then call Execute.
Execute returns 0 when it worked, or a negative error code. It removes what you pushed, so the stack then holds only the results, from position 1 up.
Read the results with the Get… functions, then empty the stack with SetTop(handle, 0).
Close releases the handle.

There are three commands to read, change and run members:

Command	Pushed	Results
`Get`	`"Get"`, the property name	Its value.
`Set`	`"Set"`, the property name, the new value	Nothing.
`Call`	`"Call"`, the method name, its parameters	What the method returns.

The first thing a program does is attach a client: Set CliNr 1 attaches the first running client, and CliCnt says how many there are.

Values

The stack holds numbers, strings, booleans, pointers and nil. Unlike EasyUO scripts, uo.dll uses real types:

IDs and types are plain numbers, not the letter codes scripts see (#CharID reads ABCDEF; CharID returns the number behind it).
Strings keep their spaces; nothing is turned into _, and $ is just a character.
Where a script variable would read N/A, uo.dll returns 0, an empty string or false.

Error codes

Code	Name	Meaning
`0`	`RES_OK`	It worked.
`-1`	`ERR_NOTFOUND`	No property, method or command with that name.
`-2`	`ERR_WRONGPAR`	The name exists, but not with these parameters.
`-3`	`ERR_GENERIC`	Something else went wrong.

Type tells which parameters a member accepts; GetError turns a code into its name.

Exported functions

Every function uses the stdcall convention (the normal 64-bit Windows convention) and takes the handle first. The names are exported with the original decorations, for example _UOOpen@0.

Function	Export name	What it does
`Version()`	`_UOVersion@0`	API version: 3.
`Open()`	`_UOOpen@0`	New handle (pointer-sized).
`Close(h)`	`_UOClose@4`	Frees the handle.
`Execute(h)`	`_UOExecute@4`	Runs `Get`, `Set`, `Call`, `Type` or `Help`; returns an error code.
`Query(h)`	`_UOQuery@4`	Runs a query such as `GetKeywords`; returns an error code.
`GetTop(h)`	`_UOGetTop@4`	Number of values on the stack.
`SetTop(h, n)`	`_UOSetTop@8`	Cuts the stack down to `n` values; `0` empties it.
`GetType(h, i)`	`_UOGetType@8`	Type of value `i`: 0 nil, 1 boolean, 2 pointer, 3 number, 4 string.
`PushNil(h)`, `PushBoolean(h, b)`, `PushInteger(h, n)`, `PushDouble(h, d)`, `PushPointer(h, p)`	`_UOPushNil@4`, …	Push a value.
`PushStrVal(h, s)`, `PushLStrVal(h, s, len)`	`_UOPushStrVal@8`, `_UOPushLStrVal@12`	Push a copy of a string (the `L` form may contain zero bytes).
`PushStrRef(h, s)`, `PushLStrRef(h, s, len)`	`_UOPushStrRef@8`, `_UOPushLStrRef@12`	Push a string without copying it; it must stay valid.
`GetBoolean(h, i)`, `GetInteger(h, i)`, `GetDouble(h, i)`, `GetPointer(h, i)`	`_UOGetInteger@8`, …	Read value `i`.
`GetString(h, i)`, `GetLString(h, i, var len)`	`_UOGetString@8`, `_UOGetLString@12`	Read a string; it stays valid until the stack changes.
`Insert(h, i)`, `Remove(h, i)`, `PushValue(h, i)`	`_UOInsert@8`, …	Move, remove or copy stack values.
`Mark(h)`, `Clean(h)`	`_UOMark@4`, `_UOClean@4`	Remember the stack size / remove that many values from the bottom.

Example

A sketch in Python with ctypes (64-bit Python):

import ctypes as C

uo = C.WinDLL(r"C:\Games\EasyUOReforged\uo.dll")

def fn(name, restype, *argtypes):
    f = uo[name]
    f.restype, f.argtypes = restype, argtypes
    return f

H = C.c_ssize_t                                   # the handle is pointer-sized
Open    = fn('_UOOpen@0', H)
Close   = fn('_UOClose@4', None, H)
Execute = fn('_UOExecute@4', C.c_int, H)
SetTop  = fn('_UOSetTop@8', None, H, C.c_int)
PushStr = fn('_UOPushStrVal@8', None, H, C.c_char_p)
PushInt = fn('_UOPushInteger@8', None, H, C.c_int)
GetInt  = fn('_UOGetInteger@8', C.c_int, H, C.c_int)
GetStr  = fn('_UOGetString@8', C.c_char_p, H, C.c_int)

h = Open()

def run(command, name, *values):
    SetTop(h, 0)
    PushStr(h, command.encode())
    PushStr(h, name.encode())
    for v in values:
        PushInt(h, v) if isinstance(v, int) else PushStr(h, v.encode())
    return Execute(h)                             # 0 = it worked

run('Set', 'CliNr', 1)                            # attach the first client
run('Get', 'CharName');           print(GetStr(h, 1).decode())
run('Call', 'GetSkill', 'mage');  print('Magery', GetInt(h, 1) / 10)
Close(h)

Reference

Name	Description	Category
`AR`	Your character’s physical resistance (armour rating before Age of Shadows).	Properties
`BackpackID`	ID of your character’s backpack.	Properties
`BlockInfo`	Reads the client's walkability data for an area of up to 32×32 tiles starting at `x`, `y`, `z`.	Methods
`BuffBarOpen`	#true when the client’s buff bar window is open, #false when it is closed.	Properties
`Call`	Runs a method with the parameters that follow; pushes what it returns.	Generic calls
`CharDir`	Direction your character is facing, 0 (north) to 7.	Properties
`CharID`	ID of your character.	Properties
`CharName`	Your character’s name.	Properties
`CharPosX`	Your character’s X position in the world (west–east).	Properties
`CharPosY`	Your character’s Y position in the world (north–south).	Properties
`CharPosZ`	Your character’s height (Z coordinate).	Properties
`CharStatus`	Letters for your character’s states: frozen, female, flying or poisoned, yellow health bar, war mode, hidden.	Properties
`CharType`	Body type of your character, as a Sys26 type.	Properties
`Click`	Clicks at `x`, `y` in the client window, like `click`.	Methods
`CliCnt`	Number of supported UO clients running.	Properties
`CliDrag`	Picks up an item with the client's own drag, like `event Drag`.	Methods
`CliLang`	Language code of the client, such as ENU.	Properties
`CliLeft`	X position of the game area inside the client window; set it to move the game area.	Properties
`CliLogged`	1 when a character is logged in, 0 at the login screens.	Properties
`CliNr`	Which of the running clients the script drives, counting from 1.	Properties
`CliTitle`	Title of the client window; set it to rename the window.	Properties
`CliTop`	Y position of the game area inside the client window; set it to move the game area.	Properties
`CliVer`	Version of the attached client, such as 7.0.117.1.	Properties
`CliXRes`	Width of the game area in pixels; set it to resize the game area.	Properties
`CliYRes`	Height of the game area in pixels; set it to resize the game area.	Properties
`CloseClient`	Closes the attached client, like `terminate uo`.	Methods
`ContID`	ID of the item a container gump on top belongs to.	Properties
`ContKind`	Kind of the gump on top, as a code; tells crafting menus, runebooks and more apart.	Properties
`ContName`	Name of the gump on top, such as container_gump or paperdoll_gump.	Properties
`ContPosX`	X position of the gump on top; set it to move the gump.	Properties
`ContPosY`	Y position of the gump on top; set it to move the gump.	Properties
`ContSizeX`	Width of the top gump in pixels.	Properties
`ContSizeY`	Height of the top gump in pixels.	Properties
`ContTop`	Brings a gump to the front, counted from the top gump (0), like `event ContTop`.	Methods
`ContType`	Type of the item a container gump on top belongs to.	Properties
`CR`	Your character’s cold resistance.	Properties
`CursKind`	Facet you are on: 0 Felucca, 1 Trammel, 2 Ilshenar, 3 Malas, 4 Tokuno, 5 Ter Mur.	Properties
`CursorX`	Mouse cursor X position relative to the game area.	Properties
`CursorY`	Mouse cursor Y position relative to the game area.	Properties
`Custom`	Sends a raw packet to the server: `packet` holds its bytes, exactly as the server expects them.	Methods
`Dex`	Your character’s dexterity.	Properties
`Drag`	Picks up an item through the server, like `exevent Drag`.	Methods
`DropC`	Drops the item last dragged into a container, or onto a stack, like `exevent DropC`.	Methods
`DropG`	Drops the item last dragged on the ground, like `exevent DropG`.	Methods
`DropPD`	Puts the item last dragged with `Drag` on, like `exevent DropPD`.	Methods
`EnemyHits`	Health in percent of the enemy in #EnemyID.	Properties
`EnemyID`	ID of the enemy whose health bar the client shows, or N/A.	Properties
`Equip`	Equips the items with the given IDs in one request, like `exevent Equip`.	Methods
`ER`	Your character’s energy resistance.	Properties
`ExMsg`	Shows a message above an object, like `event ExMsg`.	Methods
`FilterItems`	Narrows the list `ScanItems` made, and returns how many items are left.	Methods
`Followers`	How many follower slots your pets and summons use.	Properties
`FR`	Your character’s fire resistance.	Properties
`Get`	Reads a property: pushes its value.	Generic calls
`GetBuff`	Reads one buff of the list `ScanBuffs` made.	Methods
`GetCommands`	Pushes the names of the `Execute` commands: Call, Get, Help, Set, Type.	Generic calls
`GetCont`	Describes one open gump, counted from the top (0), skipping the ignored ones.	Methods
`GetError`	Pushes the name of an error code: `RES_OK`, `ERR_NOTFOUND`, `ERR_WRONGPAR`, `ERR_GENERIC`, or `ERR_UNKNOWNERR`.	Generic calls
`GetFeatures`	Pushes `CEIKD`, the feature letters of this API version.	Generic calls
`GetInit`	Pushes a short Lua script that makes the API available as `UO.Name` in Lua, the way OpenEUO used it.	Generic calls
`GetItem`	Reads one item of the filtered list, like the `#Find…` variables after `finditem`.	Methods
`GetItemLayer`	Reads the equip layer of one item of the filtered list, as `#FindLayer`.	Methods
`GetJournal`	Reads one journal line of the list `ScanJournal` made: 0 is the newest.	Methods
`GetKeywords`	Pushes the name of every property and method, once each.	Generic calls
`GetPath`	Plans a walking route, like `path find`: from your character on its facet, or from `fromx`, `fromy`, `fromz` on `facet`, to `x`, `y` (with `z`, to the floor nearest that height).	Methods
`GetPix`	Reads the colour of a pixel of the client window.	Methods
`GetShop`	Reads the entry shown at the top of the shop gump, like `getshopinfo`.	Methods
`GetSkill`	Reads a skill.	Methods
`Gold`	Gold your character carries, as the status window shows it.	Properties
`Help`	Does nothing and returns 0.	Generic calls
`HideItem`	Hides an item from your screen, like `hideitem`.	Methods
`Hits`	Your character’s current hit points.	Properties
`IgnoreCont`	Adds a gump to the ignore list, by name or by kind, like `ignorecont`.	Methods
`Int`	Your character’s intelligence.	Properties
`Key`	Presses a key in the client, like `key`.	Methods
`LHandID`	ID of the item for the left hand; set it, then event Macro 24 1 arms it.	Properties
`LLiftedID`	ID of the object last picked up (dragged).	Properties
`LLiftedKind`	1 while something hangs on the cursor, 0 otherwise.	Properties
`LLiftedType`	Type of the object last picked up (dragged).	Properties
`LObjectID`	ID of the last object used; set it, then event Macro 17 uses that object.	Properties
`LObjectType`	Type of the last object used.	Properties
`LShard`	Number of the last shard chosen; set it before logging in to preselect a shard.	Properties
`LSkill`	Number of the last skill used; set it, then event Macro 14 uses that skill.	Properties
`LSpell`	Number of the last spell cast; set it, then event Macro 16 casts that spell.	Properties
`LTargetID`	ID of the last object targeted; set it, then event Macro 22 targets that object.	Properties
`LTargetKind`	What the last target was: 1 object, 2 ground, 3 resource such as a tree or water.	Properties
`LTargetTile`	Map graphic of the tile last targeted; used for resources such as trees.	Properties
`LTargetX`	World X position of the last target; used when targeting the ground or a resource.	Properties
`LTargetY`	World Y position of the last target; used when targeting the ground or a resource.	Properties
`LTargetZ`	World height of the last target; used when targeting the ground or a resource.	Properties
`Luck`	Your character’s luck.	Properties
`Macro`	Runs one of the client's macros, like `event Macro`.	Methods
`Mana`	Your character’s current mana.	Properties
`MaxDmg`	Most damage of the weapon in your hands.	Properties
`MaxFol`	How many follower slots your character has.	Properties
`MaxHits`	The most hit points your character can have.	Properties
`MaxMana`	The most mana your character can have.	Properties
`MaxStam`	The most stamina your character can have.	Properties
`MaxStats`	Your character’s stat cap: the most strength, dexterity and intelligence together.	Properties
`MaxWeight`	Most weight your character can carry, calculated from strength: 3.5 × Str + 40.	Properties
`MinDmg`	Least damage of the weapon in your hands.	Properties
`MountID`	ID of the mount item your character rides, or N/A while it is on foot.	Properties
`MountType`	Type of the mount item your character rides, or N/A while it is on foot.	Properties
`Move`	Walks towards a position without pathfinding, like `move`.	Methods
`Msg`	Types text into the client, like `msg`.	Methods
`NextCPosX`	X position where the next gump will open.	Properties
`NextCPosY`	Y position where the next gump will open.	Properties
`OpenClient`	Starts another client, like `uoxl new`.	Methods
`PathAvoid`	Marks the rectangle from `x`, `y` to `x2`, `y2` as a place routes should go round if they can, like `path avoid`.	Methods
`PathBlock`	Marks a tile, or the rectangle from `x`, `y` to `x2`, `y2`, as a place routes must never use, like `path block`.	Methods
`PathCan`	Says whether a character can stand at `x`, `y`, like `path can`.	Methods
`PathCheck`	Asks the client itself whether the character can step onto `x`, `y` in direction `dir` from the tile behind it, at height `z`, like `path check`: the check the client makes before every step, with everything it has loaded.	Methods
`PathClear`	Forgets rules, like `path clear`.	Methods
`Pathfind`	Walks to a nearby position with the client's pathfinding, like `event PathFind`.	Methods
`PathLink`	Adds a teleporter, gate or ladder routes may use, from `x`, `y`, `z` to `x2`, `y2`, `z2` on the same facet, like `path link`.	Methods
`PathSet`	Changes a planning option, like `path set`: `accuracy`, `accuracyz`, `maxnodes`, `timeout`, `margin`, `turncost`, `heuristic`, `doorcost`, `difs`, `mobiles` or `doors`.	Methods
`PathUnblock`	Removes the blocks that overlap a tile or a rectangle, like `path unblock`.	Methods
`Popup`	Opens the context menu of an object, like `exevent PopUp`.	Methods
`PR`	Your character’s poison resistance.	Properties
`Property`	Reads the property tooltip of an object, like `event Property`.	Methods
`RenamePet`	Renames a pet, like `exevent RenamePet`.	Methods
`RHandID`	ID of the item for the right hand; set it, then event Macro 24 2 arms it.	Properties
`ScanBuffs`	Reads the buff bar, like `scanbuffs`; with `icon`, only buffs with that icon ID.	Methods
`ScanItems`	Makes a fresh list of the items and characters the client knows, like the first step of `finditem`.	Methods
`ScanJournal`	Reads the journal.	Methods
`Set`	Changes a read/write property.	Generic calls
`SetDelay`	Registers a function the DLL calls whenever a method has to wait (two pointers: the function, and a value passed back to it).	Generic calls
`SetShop`	Sets how many of an item to buy, like `setshopitem`.	Methods
`Sex`	Your character’s sex: 0 male, 1 female.	Properties
`Shard`	Name of the shard the client is logged in to.	Properties
`SkillLock`	Sets a skill's lock, like `exevent SkillLock`: `lock` 0 up, 1 down, 2 locked; `skill` a skill code or `all`.	Methods
`Stamina`	Your character’s current stamina.	Properties
`StatBar`	Opens a character's health bar, like `event StatBar`.	Methods
`StatLock`	Sets a stat's lock, like `exevent StatLock`: `stat` is `str`, `dex` or `int`; `lock` 0 up, 1 down, 2 locked.	Methods
`Str`	Your character’s strength.	Properties
`SysMessage`	Shows a system message in the client, like `event SysMessage`.	Methods
`SysMsg`	The last system message the client showed.	Properties
`TargCurs`	1 while a target cursor is showing; set it to 1 to let the user pick a target.	Properties
`TileCnt`	Counts the tiles at a map position, like `tile cnt`.	Methods
`TileGet`	Reads one tile at a map position, like `tile get`; `layer` counts from 1.	Methods
`TileInit`	Loads the map files of the attached client, like `tile init`.	Methods
`TP`	Your character’s tithing points.	Properties
`Type`	Describes a member: pushes its kind (1 read-only property, 2 read/write property, 3 method), then one parameter mask per form (`n` number, `s` string, `b` boolean, `*` anything that follows).	Generic calls
`Weight`	Weight your character carries, in stones.	Properties