[Video Tutorial] Making your first ESO Addon

moshulu · 02/14/23, 12:18 PM

I wanted to learn how to use the ESO API to create something that the community that and game I love so dearly could benefit from (and practice learning something completely new!). During my ESO Addon journey, there was plenty of information on esoui.com and wiki.esoui.com, but no truly polished tutorials that were easily accessible to everyone.

Check out the tutorial: https://youtu.be/ZYsr5pVqhso

Voilà: I created a simple tutorial that takes you from ESO addon idea to the distribution to the community via esoui.com.

I would appreciate your feedback! Perhaps you could create a version of the addon we make in the video - I would love to see what you could make! There's a lot more that could be done, as I said in the video, so I may be revisiting some of those ideas to get some more experience in Lua programming/creating tutorials.

The code can be found here: https://github.com/moshulu/ESOUI-SimpleClock

Hope to see you in-game!

@moshulu

**Baertram** · 02/14/23, 12:33 PM

Hi and thanks for creating this video. I'm sure it will help new devs to understand addon creation better, well done.

I did not fully watch yet but 1 thing in your "Assumptions and setup" should be changed by chance:

The WIKI of ESOUI -> API:
As the page clearly says at the top it's outdated and not updated since years! So you should not name it as the main reference, only as a backup.

Instead name, as done everywhere else, the WIKI's API version history >

and at each API version you will find the most up2date/or valid at that date "API Documentation_P*.txt" files linked.

Those contain the API functions, constants, events etc. to use for the current live or PTS (Public Test) servers.

The WIKI pages are often outdated and should only be used as an extra reference.

Edit:
Watching further I saw that you also mention the APIversion on the Wiki (for the manifest txt file), and you also say that functions etc. change.
I'd just make it more clear that these files are the importants to check and read, and not the Wiki page itsself, thanks.

wookiefriseur · 02/14/23, 06:14 PM

Thanks for the guide. It's a good vertical slice of the development process. Not too long, not too short and straight to the point. Subscribed

Some suggestions:

VSCode: you can zoom in a bit so your screen is easier to read (Ctrl++, Ctrl+MWheel or Ctrl+Shift+P and search for zoom)
VSCode: try zen mode for a more code focussed view (Ctrl+K->Z chord or Ctrl+Shift+P and search for zen, this hides the side panel which you can enable again using Ctrl+B)
VSCode: if you have a video with a lot of mouse interaction with the code and keyboard combinations you can try screencast mode (Ctrl+Shift+P -> screencast)
Development Process: might just be me, but I think it could be interesting if you also showed some of the research you had to do and your development process (I know its probably supposed to be more of a step-by-step-guide than a code-along)
Git: what's your target audience? If it is for beginners then the "pause the video and learn git" is a bit much , especially without any explanation why this is useful. And then you're just using it to create a zip file, oof
Dos-and-don'ts: I liked that you mentioned some coding conventions and global namespace pollution. It would be good if you also mentioned some problems users might run into.. like zipping the files instead of the parent folder, typical lua errors, other problems. Or you can make a list of problems you run into and once the list is long enough it could be a separate video.
Documentation: I liked that you showed a screenshot for the date format reference. Would be good if you did that for API functions too, from time to time.

moshulu · 02/15/23, 05:20 PM

@wookiefriseur and @baertram, thank you very much for your support and feedback. I added much of what you suggested/pointed out as a comment in the video. Hopefully, people will see it when they view the video and try to build an addon on their own.

It certainly seems a shame that the wiki isn't as updated. Is there a plan to update it in the future, with some more relevant & up-to-date information?

Also, I was aware of the TXT being the most up-to-date API version while I was initially making SimpleClock. I took a look and it's very difficult for me to understand. I could be wrong, but at first glance it seems like there is no documentation on how the functions in the API work/when events could be triggered. I know you could **guess** based on the names of the functions/events, but as I'm sure you are aware - that's not great. Do you know of any information that helps someone like me, who isn't aware of the ins and outs of the API, learn about what the functions/events do? The wiki.esoui.com/API page seemed to be going in the right direction (some of the functions were more clearly defined - like this one), but I know that it's very incomplete.

**Baertram** · 02/16/23, 04:26 AM

It certainly seems a shame that the wiki isn't as updated. Is there a plan to update it in the future, with some more relevant & up-to-date information?

Feel free to update it, it's a WIKI and all need to participate to do so.
We are doing what is possibl within our free time but updating ALL of that each time, after each API txt changes is just not possible as you cannot load all the info in there automatically, it would overwrite existing info and invalidate working links to already created "subpages".
So this either needs to be revamped and someone needs to find out all already created subpages and make it failsafe for automatic updates, or ... manually changes for thousands of lines and links...

Also, I was aware of the TXT being the most up-to-date API version while I was initially making SimpleClock. I took a look and it's very difficult for me to understand. I could be wrong, but at first glance it seems like there is no documentation on how the functions in the API work/when events could be triggered. I know you could **guess** based on the names of the functions/events, but as I'm sure you are aware - that's not great. Do you know of any information that helps someone like me, who isn't aware of the ins and outs of the API, learn about what the functions/events do? The wiki.esoui.com/API page seemed to be going in the right direction (some of the functions were more clearly defined - like this one), but I know that it's very incomplete.

It's a just a "list" txt file of given global constants, types (e.g. BAG_TYPE ->BAG_BACKPACK, BAG_BANK, ...), events, functions etc. in a documentation format that ZOs uses.
Nothing more or less -> API Docu without any description what they do in detail.
You can see by the names and parameters of the functions what types are used, and those types can be searched in the file (at the top somewhere) to see the constants that were defined.

There is no further documentation, all you need to find is in the ESOUI source code: Search for the functions in there e.g. to find out how ESO (ZOs developers) does things.
Check the file structure of the esoui sources (e.g. /ingame/crafting) to get the surrounding where it is used.
It's more or less a "search and find" and then "check code how it's done" and "reuse ZOs code or hook into etc".

I'm afraid, there is nothing more documented except parts are explained at the WIKI.
And there won't ever be more unless someone starts to document that all in more detail and depth (but it also changes with patches, sometimes less, sometimes a lot).

There exist tools to parse the file and create files for other IDEs like VScode or IntelliJ IDEA etc. so you got some auto completion and function parameter helpers.

wookiefriseur · 02/16/23, 09:26 AM

Yeah, it was my problem as well.

For the most part it seems that one has to "learn" the API by exploring it and trying what works and what doesn't. This is not ideal. For now most of the API definitions you find are crowdsourced by the community (from txt files and ingame trial and error).

But there are some tools to help the development process and the community chat on Gitter is also very helpful, even a dev from ZOS is posting there. It's also interesting to look at the code of other add ons.

See the sticky posts in Dev Tools for resources: https://www.esoui.com/forums/forumdisplay.php?f=173
I recommend the API explorer (way faster than exploring it ingame or in extracted API files): https://sir.insidi.at/or/apiexplorer/
And here is the thread about Gitter: https://www.esoui.com/forums/showthread.php?t=10

ZOS could auto generate the API from docstrings in their source code, but instead it seems like they do it manually, using documentation in Confluence file format and then copy it to the text file. At least that's what it looks like to me. Well, at least it gives the community something to do.

Edit: Gitter link is case sensitive so the link in the thread won't work, correct url is: https://gitter.im/esoui/esoui