Addon Server Protocol Docs
This addon is being developed under assumption that a new protocol will be implemented for addon/server communication of bot data.
This protocol uses the ADDON channel for messaging, and a specific format that simplifies parsing and improves lua performance.
This page documents the concepts and message formats used by the protocol.
Bot always refers to a bot that has a master.
In some cases, like itemlinks the string of the itemlink can be null to indicate that item was unequipped, or removed from a bag, etc.
A null link is ~ char , example q:g:001:~
This protocol allows to completely bypass numerous issues that plaque WOW Lua API, most notably the distance/zone restrictions, state restrictions, inspect restrictions. It allows to get bot data that may not otherwise be available. It allows to hide communications from player, allowing to make all interactions with bot through user interface.
All messaging happens through ADDON channel, which all addons can parse, and as such it may lead to potential performance issues with addons that don't correctly filter addon messages. Server sends messages through this channel, meaning server can directly communicate with the addon.
Query is a way to completely resync some data, like inventory. This generates a lot of messages
To avoid resyncs, addon relies on receiving delta reports when something in the bot changes, which addon caches internally. Ideally queries should be ran once, when Bot is registered in the addon, but due to bugs desync can occur and then player can force a query to resync state.
Message structure is not flexible, the format and order of parameters should be identical on the server and the client. An example of a message:
q:p:001:b:1:20:18:[Frostweave Bag]
q - this is MSG_HEADER and currently it has 4 possible values
p - this is subtype and each header value has its own subtypes
001 - this is query id
b:1:20:18:[Frostweave Bag] - this is the payload and each message/report/query has its own unique payload structure
q:p:001: is the base structure, and the addon tests to see if the message contains _:_:___: the 3 separators in the correct positions before parsing the message. This is another safeguard to ensure only correct messages are parsed.
MSG_HEADER.SYSTEM or s these include - handshake, ping, log out, possibly more later
MSG_HEADER.REPORT or r
MSG_HEADER.QUERY or q
MSG_HEADER.COMMAND or c
This concept exists because the WOW Lua API is unreliable when it comes to online/offline status.
When master logs in, it sends pings to all bots, once. If the bot is online it responds with a ping. This lets master instantly know if the bot is online.
When bot logs in, it starts sending handshakes every second, until the master responds with a handshake. When handshake is complete, bot enables all features of the protocol.
s:h:000:
When bot logs out it sends a ( MSG_HEADER.SYSTEM , SYS_MSG_TYPE.LOGOUT ) message s:l:000:
This removes the need to use unreliable WOW API
Reports are sent by the Bot without master asking.
Reports provide delta updates, like a single item equipped, leveled up
Example of a report r:g:000:16:1:[Gladius]
REPORT_TYPE.ITEM_EQUIPPED g single gear item equipped or unequipped
example > r:g:000:16:1:[Gladius]
payload > slotId:count:itemLink
REPORT_TYPE.CURRENCY c currency changed
Subtypes
- Money
g
example > r:c:001:g:721:56:82
payload > subtype g/c:gold amount:silver amount:copper amount
Other currencies c
example > r:c:001:c:43308:100
payload > subtype g/c:currency itemId:currency amount
43308 is itemId of Honor https://wotlk.evowow.com/?currencies
REPORT_TYPE.INVENTORY i single inventory item added/moved/removed, or a bag added/removed/moved
All bags included (-2) to 11
On bag change
-
If the bag changed, generate bag report
-
If bag changed, report all the contents of this bag
example >
-- Moved a bag from slot 2 to slot 1
r:i:000:b:2:0:~
r:i:000:b:1:20:[Frostweave Bag]
r:i:000:i:1:12:1:[Worn Mail]
-- ... contents of the bag, skip empty slotspayload bag > b:bagSlotID:bagSlotCount:bag link
On Item Change
If item changed report it.
This includes:
- Item moved
- Item added
- Item removed
- Item count changed
- Item enchanted
- Item gemmed
example > r:i:000:i:0:16:10:[Fine Aged Cheddar] move item from bagpack to bank space
example > r:i:000:i:-1:5:10:[Fine Aged Cheddar]
payload > i:bagSlotId:containerSlotId (which slot in the bag the item is in):itemCount:itemLink
REPORT_TYPE.TALENTS t WIP talent learned / spec changed / talents reset / glyph added/removed
REPORT_TYPE.SPELLS s WIP spell learned
REPORT_TYPE.QUEST q WIP single quest accepted, abandoned, changed, completed
REPORT_TYPE.EXPERIENCE e WIP level changed , experience changed (occasional updates?)
REPORT_TYPE.STATS S WIP stats and combat ratings (possibly delta changes? will require server to keep compare current and new values?)
Query is generated by the addon.
Bot responds with matching query ID and one of the following opcodes (which replace subtype)
Addon assigns an id 1-999, and Bot responds with the same id. Once the query is closed due to completion or the time to close, the query is finalized and ID is recycled. In a scenario where a player has 25+ bots online it is possible to reach 100+ open queries, so the number has 3 digits.
QUERY_OPCODE.PROGRESS p carries a payload and indicates that the query is not yet complete
example > q:p:001:i:0:15:15:[Moonberry Juice]
payload > any payload that matches the initial query subtype
QUERY_OPCODE.FINAL f can carry a payload (optional) and indicates that this is the last message of the query
example > q:f:001:i:0:15:15:[Moonberry Juice]
If the opcode is a number between 0-9 it indicates an error.
0-5 are reserved for general error, that will be added later.
6-9 are for query specific errors and can carry an error message as payload.
example > q:6:003:"Bank is not accessible from this zone" (imaginary example)
QUERY_TYPE.WHO w level, class, spec, location, experience and more
example response > q:f:001:WARRIOR:65:0:1:0:0:0:0:0:0:0:Lion's Pride Inn
info > p1-6 are the corresponding talent tree points, 1-3 in the spec1, and 4-6 in spec2
payload > classFileName:level:dualSpectUnlocked (0/1):activeSpec (1/2):p1:p2:p3:p4:p5:p6:floatRemainingExpToNextLevel (0-1):zoneString
QUERY_TYPE.GEAR g Send all items that are currently equipped
example response > q:p:001:9:1:[Light Mail Bracers]
payload > equipSlotId:itemCount:itemLink
QUERY_TYPE.INVENTORY i items in bags, empty slots are not sent
example response > q:p:001:b:1:20:[Frostweave Bag]
Multistep
Step 1 : Send equipped bag data. Only equippable bags are sent (1-11)
Includes bank bags.
bag payload > b:bagSlotNum (1-4):amountItemSlots:bagItemLink
Step 2 : Send items in bags (-2) to 11
Includes -2 keychain, -1 bank space, 0 backpack
item payload > i:bagSlotNum(which bag item is in):containerSlotId (which slot the item is inside the bag):itemCount:itemLink
QUERY_TYPE.CURRENCY c
Response Subtypes
- Money
g
example > q:p:001:g:721:56:82
payload > subtype g/c:gold amount:silver amount:copper amount
Other currencies c
example > q:p:001:c:43308:100
payload > subtype g/c:currency itemId:currency amount
43308 is itemId of Honor https://wotlk.evowow.com/?currencies
QUERY_TYPE.TALENTS t WIP
QUERY_TYPE.SPELLS s WIP
QUERY_TYPE.QUESTS q WIP
QUERY_TYPE.STRATEGIES S WIP
Most commands are grouped logically, and use subtypes to route to specific command.
COMMAND.ITEM i Commands related to items
Subtypes
-
e- equip -
u- unequip -
U- use -
t- use on target -
d- destroy -
s- sell -
j- sell junk -
b- buy
e - equip an item
example > c:i:000:e:[Gladius]
payload > itemLink
u - unequip an item
example > c:i:000:u:[Gladius]
payload > itemLink
U - use item
example > c:i:000:U:[Alterac Swiss]
payload > itemLink
t - use item on another item
example > c:i:000:t:[Solid Sharpening Stone]:[Gladius]
payload > itemLink:itemLink
d - destroy item
example > c:i:000:d:[Gladius]
payload > itemLink
s - sell item
example > c:i:000:s:[Gladius]
payload > itemLink
j - sell junk items
example > c:i:000:j:
payload > none
b - buy item
example > c:i:000:b:[Gladius]
payload > itemLink
WIP