Addon developer requires new way to query bots

[azcguy]

The ISSUE

I am developing PlayerbotsPanel - an addon that should ideally replace any interactions with bots through chat

So far it goes great, most of the features work - gear, cached data for offline bots, one click add/remove .. etc
However, the problems start when addon needs to query the bot for data in a safe and effective (lol) way.
Things like inspecting gear are done through WOW addon API, but inventory and other "hidden" data is done through chat.
Currently I have a shoddy system of parallel queues that send and catch whispers to and from bots and the way it currently works,
it simply isn't good.

• There is no way to identify that payload is intended for a specific query
  example - we await inventory items, and bot says Hello!, or something similar (see screenshot 2)
• There is no start/end of query
  there is a start like === Inventory === but no end
• The formatting of responses is bad, and hard to parse (as you can see from the screenshot the money have s and c in them,
  that is because I didn't even start parsing it properly, hoping this thread will lead to a better way, so i don't have to)

Proposal
Someone, probably liyunfan1223 should implement additional, structured query messages for bots.
Similar to human readable, but structured in a machine friendly way.

I propose the following mechanism for receiving bot info through chat channels
legend:
> to bot, not part of the queries
< from bot, not part of the queries

1. Addon sends a request

> q:72:1
// or
> q:44:stats
// or
> q:9288:currency

q - query , 9288 - id assigned by addon, used to map request and response , currency/stats string query types, or 1 int/enum query types, for less data transferred

to which bot responds with

> q:9288:currency             // give me currency
< r1:9288                          // r1 - response start
< r2:9288:00,01,872,5124 // r2 - response payload , 9288 - id, 00 - copper, 01 - silver, 872 - gold, 5124 - honor
< r3:9288                          // r3 - request complete

// or 
> q:9288:currency             // give me currency
< r4:9288                          // r4 - error, query aborted

more examples

> q:77:equip // list of equipped gear
< r1:77
< r2:77:|cff0070dd|Hitem:80921:4721:::::::36:103::1:::::::|h[Saboteur's Stabilizing Bracers]|h|r 
... // and so on for all equipped gear
< r3:77 

Above example is doing the same thing wow Inspect API does, but since its a chat message, it is better,
because the API NotifyInspect() is restricted by distance. And has other restrictions,
for example addon can't query gems/talents fast, it needs to wait for server response async and can be subject to throttling (not sure how that works with azerothcore)
so with these queries it would be instant and contain a lot more information

> q:124:items // list of items in inventory
< r1:124
< r2:124:|cff0070dd|Hitem:80921:4721:::::::36:103::1:::::::|h[Saboteur's Stabilizing Bracers]|h|r 
... 
< r4:124 // error, bot is being disconnected

Important - if the server can send messages through SendAddonMessage
https://web.archive.org/web/20091024082724/http://wowprogramming.com/docs/api/SendAddonMessage
It would also help a lot, because these don't require client side chat filtering, and can be spammed without fear of throttling

Alternatives
Parsing the messages as is, and having a buggy addon

[liyunfan1223]

Awesome! I noticed that there is a message type for addons (CHAT_MSG_ADDON), which should be a good way to communicate between the server and the addon without making the messages annoying. I'm new to addon development so I'm not sure how to communicate between addon and server properly, but I think after some trying it should be fine.

Regarding the API, I agree with setting some formats to facilitate parsing. Is there any API design reference like the "wow Inspect API" you mentioned? Which API would you like to start a trial with, maybe a inventory list api?

Since I am not very familiar with addon development, if you can provide an unfinished version (for example, with the function of initiating API requests but no need to handle the response), it should be very helpful to the server API development. Likewise, you're welcome to discuss what other addon features you'd like to implement and I'll try to help as much as possible.

[azcguy]

Boss, i am preparing the addon for init repo, and i will setup code and debug tools so you can quickly hop in and start developing.

Is there any API design reference like the "wow Inspect API" you mentioned?

This function is the cornerstone of inspect https://wowpedia.fandom.com/wiki/API_NotifyInspect
It initializes a bunch of async events on the server that addon can catch later like INSPECT_READY INSPECT_ACHIEVEMENT_READY INSPECT_TALENT_READY
but gear inspect is not async, its instant, but limited by distance
Here are some useful links
https://web.archive.org/web/20100726103603/http://wowprogramming.com/docs/events
https://web.archive.org/web/20100726112636/http://wowprogramming.com/docs/api_categories
https://addonstudio.org/wiki/WoW:Lua_functions
https://www.townlong-yak.com/framexml/3.3.5/Constants.lua#192
https://www.wowinterface.com/forums/showthread.php?t=40444

Which API would you like to start a trial with, maybe a inventory list api?

Inventory is the most crucial and a good testbed.
Ideally the following things should be queried separately

- Gear
- Items
- Quests
- Talents
- Spells (spellbook)
- Stats - real bot stats, str/agi/ratings/resists
- Skills 
- Currencies - money, honor and any tokens 
- Reputation

Also bot should just send status updates without queries when

- going online/offline 
- entering/exiting combat, 
- equip changed/ inventory changed
- quest status changes
- spells changed (learned spell)
- talents changed
and more probably

these can be used by addon to trigger queries,
for example equip changed would trigger stats query to update bot stats data
if all bot internal changes will have a status update msg, then addon can omit periodic "scan all bots" updates

if you can provide an unfinished version (for example, with the function of initiating API requests but no need to handle the response), it should be very helpful to the server API development.

In a day or two (refactor / mocks)

Likewise, you're welcome to discuss what other addon features you'd like to implement and I'll try to help as much as possible.

Thank you, it would be great if all bot commands like ue [item] also would be replicated as hidden addon messages, silent (echo off) and machine friendly.

I plan to make a contextual mini panel where there are Portraits of the owned bots nearby, and buttons appear over each portrait depending on what the bot can do, for example train if trainer is selected and bot class matches

I have many plans for the addon - group templates, strategy builder ui also with templates, i will write all of this on the repo

[azcguy]

I created the repository https://github.com/azcguy/PlayerbotsPanel

Issues-

1. It is not possible to reliably get online status of a player in an addon, without your help

Knowing if the bot is online is crucial for most functionality, and there are many cases where if bot is offline,
there is no way to 100% know it if using WOW API,

• /who, SendWho is protected, requires parsing, or if there are multiple matches doesnt give an answer
• UnitExists() only works in party
• send whisper will crash the addon with an error if the target is offline
  and so on, so if its possible the first thing i need is playerbot pinging the player with online status, which we can actually replace with a "handshake"

Handshake - bot sends addonmsg to player every second, to establish that the player actually uses an addon that uses this channel. If the player has an addon, it reponds and a handshake is complete. If the player doesnt respond after 5 seconds, bot stops and assumes there is no addon.

Once handshake is complete, the bot starts sending a stream of reports and opens query and command channel

-- broker.lua

PlayerbotsBrokerReportType = {}
local REPORT_TYPE = PlayerbotsBrokerReportType
REPORT_TYPE.STATUS = 0 -- status changed
REPORT_TYPE.CURRENCY = 1 -- currency changed
REPORT_TYPE.GEAR = 2 -- gear changed (item equipped/ unequipped)
REPORT_TYPE.INVENTORY = 3 -- inventory changed (bag changed, item added / removed / destroyed)
REPORT_TYPE.TALENTS = 4 -- talent learned / spec changed / talents reset
REPORT_TYPE.SPELLS = 5 -- spell learned
REPORT_TYPE.QUEST = 6 -- single quest accepted, abandoned, changed, completed

On the addon side - if there is no handshake from bot, the bot is considered offline.
Once the bot went online, addon will catch "going offline" report.

This way the addon will always know if the bot is online, even when its not in a group, nearby and so on.

About the addon,
currently a bot that is online will always be invited to the party automatically, until the above is resolved.

I tried to cleanup the code as much as i could, and split it into logical files, i move all addon-bot comms to broker.lua
Where queries are defined in queryTemplates and have 3 phases - start/progress/finalize, after finalize the ui will react and update. It's not finished yet, and because i have nothing to work with,

I am considering creating another addon that acts as a server emulator - receives queries and sends responses, run from another account, as if that account was a bot. So a bot-emulator addon

I will push this emulator into the same repository and we can both first work out how to structure messages in lua, before moving into cpp.

What do you think?

[azcguy]

I've been working on server emulator - https://github.com/azcguy/PlayerbotsPanelEmu
So far its going great and fixes all issues with online status through a combination of handshake and pings
The emu part is quite simple right now compared to the main addon, i also have issues with emu generating login/logout messages using WOW API events, so i fake those with Sim login buttons

I assume the server side knows exactly when every player and bot logs in, so it can directly use those events to generate messages.

[liyunfan1223]

Thanks for your work, sorry for the late reply as I'm on a trip for about week or so and I'll get back to work as soon as I'm done.

[azcguy]

Protocol seems to be able to fit everything we need
Im trying to make sure it's optimized on lua side, to the extent it is possible with tricks like

-- read id "000" 3 bytes from msg string and convert them to int without allocating a string
local id = ((idb1-48) * 100) + ((idb2-48) * 10) + (idb3-48)

Also the queries MASTER >> BOT can be packed into a single message like this

q:w:001:q:w:002:q:w:003:q:w:004:q:w:005:q:w:006:q:w:007:q:w:008:q:w:009:

Otherwise the throttling problem can occur in instanced content (dungeons/raids) where even AddonMessage is limited for some reason. Throttling is something that may be fixed in mod-playerbots, by allowing master to have no throttling applied when messaging bots?
I will create a wiki page to document protocol with all messages structure.
I dont know if compressing messages will be a good choice, because it adds overhead to the server and lua and i think its simply less instructions to use many fast parses than decompress massive blobs, and then parse them.

Later i will extract PlayerbotsBroker into a standalone lib so any addon can use it

[azcguy]

One of the issues im thinking about is sync of the data when bot is online while player is not.
This forces player to query data (like resync all of items in inventory), instead of relying on delta reports.
Im thinking that maybe there is a way to buffer reports and send them to player? But what if the amount of reports is larger than just resync? How would that be stored on the server? Maybe its a bad idea.

[azcguy]

Created the wiki page for the protocol https://github.com/azcguy/PlayerbotsPanel/wiki/Addon-Server-Protocol-Docs

[azcguy]

inventory.tab.mp4

Made async item data load from server and bag queries and reports work, im going to do bank and keychain next, then commands for this tab, equip/use etc.

I have a question about bank, a player can only access bank when player interacts with it, can the bot access bank from anywhere?
In c++ ? At least to read from it, so the queries dont rely on a bot being at the bank.

[azcguy]

Are you open to adding new commands? Right now the trade doesnt have a specific command, player has to initiate trade and then just whisper itemlinks.
I propose to instead have a dedicated command to add item to trade, so Bot initiates trade when command is given and adds the item to the trade window.

Scratch that, the ITEM_USE command already handles it contextually. May need to revisit it later but adding items to trade works as is atm.

[liyunfan1223]

It took me some time to catch up :D. So now we need to modify the server bots so that they respond to requests of addon, in the same way as PlayerbotsPanelEmu?

[azcguy]

Yes, the protocol is essential.
I've created this wiki page https://github.com/azcguy/PlayerbotsPanel/wiki/Addon-Server-Protocol-Docs
It has things that i am sure are stable. If you create the c++ architecture for it, i can help with the query code in the functions.

I was thinking about how best to implement it, i think there should be a global switch in mod-config,
and a per bot persistent switch, like a bot whisper command addon comms > Addon comms protocol was enabled for the bot Bot , to isolate players from accidents and bugs related to it.

[azcguy]

I think we should drop multiple query packing, its overengineering with minimal gain.

[azcguy]

Added REPORT_TYPE.CURRENCY and QUERY_TYPE.CURRENCY to https://github.com/azcguy/PlayerbotsPanel/wiki/Addon-Server-Protocol-Docs

If its more convenient to send gold as a single number tell me.