[API] Public API Drafting

steviegt6 commented 1 year ago

Before releasing this mod to the public, we should try to do several things things:

follow SemVer specifications;
design a defensively-developed codebase and API, resistant to changes in a manner that preserves compatibility;
deliver updates according to SemVer as specified by the above two items;
and generalize tasks and expose the necessities, while keeping things subject to change hidden.

Points of Concern

Localization

How should localization work? We will need to plan ahead in a manner that hopefully makes the port to 1.4.4 easier for everyone. I would like to encourage the use of LocalizedText, but string properties instead may be better so people can use raw strings, LocalizedText (for vanilla and 1.4.4), and ModTranslation (for tML 1.4.3).

Namespace Organization

Some discussion has occurred in the Discord, but namespaces need to be streamlined as changing them after releasing an update is a breaking change.

Saving and Loading

We need to deal with corrupted toolbar saves or toolbars with tools that are not currently loaded.

Tool API

The abstract Tool class needs to be made public, we should go over each member before to figure out what is necessary.

UI Autoloading

Discussion surrounding what should be exposed needs to occur (we can discuss later, not a high priority).

APIs for Existing Tools

Big points of concern are custom filters for some spawners, and things of that nature - how should we handle them?

WeakReference Support

Allow registration of various components through a Mod.Call? Perfectly doable, albeit not all that intuitive. Should APIs for existing tools be provided through here optionally as well?

steviegt6 commented 1 year ago

@ScalarVector1, I would love your input. I do not have access to Discord right now but I will check there shortly as well. I'll try to keep general points of discussion updated here as well for any external spectators, as well as to simply archive decisions.

ScalarVector1 commented 1 year ago

100% agree on following semver, was planning on this initially and it's going to be important if we want to allow for addons to be made easily.

Currently localization for me is a low priority issue, only exacerbated by 1.4.4s upcoming changes. Localization is not in HEROs/Cheatsheet as far as I can tell, and thus not part of feature parity. It is certainly something to consider, but likely in a post 1.4.4 environment.

Namespace structure can be discussed, I think the main point here was if we should collapse the Core/System namespace, which we can likely do to the small scale of the project.

Safety checks for profile loads will likely be a change to come soon, hopefully along with documentation about how to utilize it better. Other feature considerations here are scanning the directory and selecting a saved layout ingame.

I'd like to discuss the tool API exposure seperately, as other things such as certain GUI parent classes will need to be made public to allow for addon developers to have layout consistency with the base mod. We should encourage using these.

Autoloading is likely more a technical issue -- what do we know about the tmodloader modtype system? Would this cover most of the bases here?

Custom modifiers and filters will likely get their own unique API implementation. I'm not sure fully exposing the specific browser subclasses would be wise.

I cant think of a usecase for this. Why would a mod want to weakref add a tool without the mod to provide the GUI to use the tool? If you have a specific usecase we can discuss this further, but I dont see much a point to it currently.

steviegt6 commented 1 year ago

Currently localization for me is a low priority issue, only exacerbated by 1.4.4s upcoming changes. Localization is not in HEROs/Cheatsheet as far as I can tell, and thus not part of feature parity. It is certainly something to consider, but likely in a post 1.4.4 environment.

I think just using a string is fine, my main point of concern would be switching to a ModTranslation and then getting screwed over. Localization is generally a good thing to have, however.

Namespace structure can be discussed, I think the main point here was if we should collapse the Core/System namespace, which we can likely do to the small scale of the project.

Yes.

I'd like to discuss the tool API exposure seperately, as other things such as certain GUI parent classes will need to be made public to allow for addon developers to have layout consistency with the base mod. We should encourage using these.

Sounds good, a follow-up issue can be created later. For now, we should keep our tools internal.

Autoloading is likely more a technical issue -- what do we know about the tmodloader modtype system? Would this cover most of the bases here?

I didn't even consider it, but ModType would work fine for UIs, actually.

I cant think of a usecase for this. Why would a mod want to weakref add a tool without the mod to provide the GUI to use the tool? If you have a specific usecase we can discuss this further, but I dont see much a point to it currently.

Easy debug tools and stuff that can be quickly scaffolded while developing a mod, without the need to depend directly on Dragon Lens.

ScalarVector1 / DragonLens