How do you work with the new Guild History API?

ImpOfThePerverse415

I have looked over the available documentation, but it is primarily function signatures. In the past I'd just figure things out from there via trial and error, but with results reportedly taking up to an hour to load that would be a slow process. Also I'd rather not choke the servers with possibly erroneous requests if I can avoid it.

From what I can gather reading the documentation, the process for caching event history and iterating over the results is something like:

Use CreateGuildHistoryRequest to get the server to start caching events.

Poll with GetGuildHistoryRequestFlags until GUILD_HISTORY_REQUEST_FLAG_COMPLETE is true (unless there's an event I can register for that will let me know?)

Iterate over the results via GetGuildHistoryEventBasicInfo (or one of the event category specific variants of it) in a for loop, using starting and ending event indices obtained via GetGuildHistoryEventIndicesForTimeRange.

Is this accurate? I've read that the data is cached in chunks of 500 entries. If there are more than 500 results, will they all end up in the cache at the same time, or do you have to use RequestMoreGuildHistoryEvents after you've processed the current chunk?

Thank you, any insight anyone can provide would be greatly appreciated.

Baertram

I would take a look over here (as you already did ;-) ):
https://www.esoui.com/forums/showthread.php?t=10724

ImpOfThePerverse415

As you've probably seen, the response I got over there was a flat out refusal to answer any questions about using the API. I posted here hoping someone from ZOS would weigh in.

Baertram

And I dont see it was a refusal? You just said that you do not want to use the provided easiest way -> LibHistoire.

The other games API was mentioned and listed there too, with the info that you get into trouble if you try to make that work "now". As ZOs got bugs and addon devs that experienced that already and provided a library to circumvent that (or at least show ppl an UI and provide feedback so you do not have to reinvent the wheel yourself).

As ZOs did not describe how to use the APi and just shows the available functions, we also do not know in detail how to use it.
But addons/libraries like LibHistoire were created and are documented and thus should be used for that, and for compatibility reasons with other addons.

If you refuse to use it you must wait for more answers then, from devs who got expeience with the new API functions of Guild History (I do not, sorry) and their time to write it down as a HowTo.

ImpOfThePerverse415

ESOUI's wiki links that thread as a place to discuss and learn about the new API. I tried asking about the new API in that thread, and they refused to answer any questions about it because it would lead to mods that don't use LibHistoire interfering with the operation of LibHistoire.

I see the LibHistoire description page includes a thank you to some ZOS employees that helped explain how to work with the API. That thread seems like the logical place to disseminate any insights.

Baertram

Again: They did not refuse. They pointed you to the tool (LibHistoire) to use, or the ZOs code (https://github.com/esoui/esoui/tree/master/esoui/ingame/guildhistory) to check how ZOs did it.

Atm I think/experience the devs are quity busy making all work smoothly and thus they do not document anything in detail. Maybe this will come in the future.
So you will simply have to wait for someone with that KnowHow to find the time and will to document something, which is nothing (from my experience) that's done "beside fixing actual real problems in live gameplay addons". And nothing that's done until the API is stable and working. Else you do it like 50 times.

LibHistoire
btw it does not lead to mods (addOns) that interfere with LibHistoire, but that interfere with other addons, which use the Guild history API.
-> The lib was created, like many many other libs, to make all addons most compatible!

Sure you can use the API standalone and create addons that way, that's no problem I think.
But you were also told that it will lead to many unforseen problems which the library already handles (meanwhile, after some updates).

The lib in general is maintained to provide easier ways to use the API, provide an UI for the user to see what is happening/missing, and that also circumvents problems like stuck requests, copatibility for old data (at least that's planned) and bug fixes or at least prevention of possible bugs with current API usage.
In total it's there to help you and the other devs, and the users.
So I'm not sure why you are ignoring this help and want to make it a maybe incompatible addon, disturbing other addons in the end?

I get that you want to understand the basics but in the end you can do that also by using the lib, reading it's code and see how it atually uses the ZOs API functions?
That's what I understood from sirinsidiator's answer in the forum.

In general:
You can always use APi functions directly, but we do not have any particular docu or howto.
We get the API function names and we read the ESOUI source code to understand how ZOs does it :-)
If in this case someone of ZOs explained how to use it in more detail, more than that what is in the esoui forums threads, then I'm not aware of that.

If there is any examples or docu, devs do that in free time (never saw any thing from ZOs so far so do not expect that to come here), in the Wiki or esoui forums e.g.


If all of that is not enough for you, I cannot say anything else, nor help any further (as I said I do neither know how it works in detail).
Time will bring examples and documentation, or not.
But actually noone refuses to help or provide you that API info. That's a totally wrong sight of the facs that you got there!

Here the answers you got so others can read them too and see the "refuse of help" that you speak about...

Sharlikran:

At this point it's best to explain what you want to do or upgrade. The reason is if you use the low level API (meaning what you see in the docs) then it could cause your mod to appear to work properly. However, LibHistorie may not be able to function because you did something that is taboo, and it put everything on cooldown by accident. Like for example, don't try to fix mods like Shissu's.

If you want to make something from scratch, go ahead. Read the the LibHistorie description page.

sirinsidiator (even linked you the high level API of ZOs, how they do it, so you can have a look.)

You should not use the low-level api directly. Instead it's advised to utilize the high-level api found here.

But you will run into a lot of issues if you do that right now, since the game currently has a couple bugs in regards to requesting data. If you don't want to spend countless hours navigating around them, you are better off relying on LibHistoire.

If you still insist on not using it after hearing that, be warned that you will inadvertently interfere with operation of the library and make it slower. So don't blame me when it ends up taking even longer to request data.

You can also join the gitter.im esoui dev chat and speak with us there, maybe someone go more infos for you over there

ImpOfThePerverse415

Thanks. And yeah, I probably shouldn't be on forums right now lol, I've got a cold and a badly infected cut on my finger and it's making me grumpy.

The repository containing ZOS's high level API that sirinsidiator linked provides some good insight into the syntax. I'm still somewhat in the dark on the overall function of the system though, mostly how it handles the 500 event limit, and what exactly happens when you call RequestMoreGuildHistoryEvents.

I'm new to working with ESO addons (and Lua) but using library addons does seem pretty common among ESO addon authors. There's a lot to be said for it - they can insulate addons from changes to ZOS's API, they're better documented, and they concentrate all of the bug reports in one place where they can be dealt with without every addon author having to reinvent the wheel dealing with them. I've run into trouble in some game development projects in the past though with big utilities that do more than I need and become cumbersome as a result. The addon that I'm trying to update for my guild looked pretty straightforward so I just wanted to avoid any complications and unnecessary dependencies.

Baertram

And yeah, I probably shouldn't be on forums right now lol, I've got a cold and a badly infected cut on my finger and it's making me grumpy.

Recover well! All the best


In the past the equivalent to RequestMoreGuildHistoryEvents was just sending a request to the server and server queued that with all the other requests that ZOs APi and addons did send. Once time was fine it answered with data.
I expect that to be working the same/simialr now as else servers would get unstable and laggy if they directly answer.
It maybe now check if the data is in local cached files in your AppData/local/Elder Scrolls Online folder files, and only if missing request new from the server (but I never worked with that so it's only guessing here!).

I'm new to working with ESO addons (and Lua) but using library addons does seem pretty common among ESO addon authors.

es, the libs are created to ease the addon usage and to make all compatibel at best between all addons. There exist several adodns that do not use libs (for e.g. group ultimate sharing) and thus e.g. every addon did the code itsself, making it not possible to check what addons in total are doing the same and why servr disconnects you for mesage spam.
Meanwhile that get's better but that's only 1 example.

That's why Sirisidator asked you to use the 1 lib for the guild history so for the future:
-Addons can check what other addons use it and react (maybe)
-Devs can easily see where errors happen (no false reports by users tha say they got A disabled but actually it is enabled and errors -> LibDebugLgger helps there )
-You benefit from error revention
-Server benefits from queued data properly (ZOs talked to siri and they worked on a best possible and performant way, plus are still working on improvements etc.)


As you said, depending on your project, libs could be "too much". But for now we do not have any proper documentation on how that nwe guild history works in detail and what to do to make it work properly for all. Plus ZOs still got some bugs in there, so you might need to wait or try & error. But if you plan to release your addon one time or plan to raise bug reports becuase your MasterMerchant addon is not working properly, and in the end your local projetc not using Histy is the culprit: It would be best to avoid that from the start

ImpOfThePerverse415

Thank you! I'm feeling a lot better now, they put me on some potent antibiotics.

It's not an addon I'm going to release, I'm just updating a custom addon for a guild I'm in. It will probably only be run by one officer, and for better processing times and stability I can suggest they not run anything else alongside it that works with guild history.

Baertram

@ImpOfThePerverse415 LibHistoire was updated and the documenation and API docs. were updated too:
It also describeds the benefits of the lib now.
https://www.esoui.com/downloads/info2817-LibHistoire-GuildHistory.html


Examples are showing how you could use it to process guild history category events for a timeframe, or from last saved eventId onwards.