Short version (and elaborated below)
- Most of the enums - could deprecated the enums and temporarily keep them depending on relevant discussions. Unfortunately changing anything with that requires breaking lots of tools/methods through the whole project… This is a hard topic.
- Providing early notification of api breakage and documenting how to recode things appropriately. Ideally at the Mojang snapshot stage instead of release stage.
- Abstracting various event to be less implementation specific.
- Inventory events. Client actions vs. Server actions. And altering the results of these separate but intertwined things.
- Looking to fill API holes currently accomplished with nms but hard to add API while we have an upstream.
The most common complaint about the Bukkit API I notice is the enums in the API, specifically the Material api - but it applies elsewhere. I don’t want to speculate on what the proper replacement would look like. But I would want that replacement to make it really easy to make the transition so it isn’t a discouragement to do the upgrade (just look at the people that chose not to go past 1.12 because of the work required; disregarding the performance issues). By easy, I mean that you can use find/replace tools to do most of the work with minor human review to go from current API to the refactored.
A large issue I see on that subject… Is that vanilla is moving towards supporting custom data pack and resource packa into vanilla Minecraft (custom blocks/items/entities/etc). The Bukkit project has always been intentional about not providing special support to the modding community. But with certain aspects of modding coming to vanilla, I don’t see the current API adapting. It is my opinion, that if it can be done with the vanilla client, it should be supported by this project.
Additionally, policy-wise. Would want to have a Deprecation policy with the API, not to encourage us to constantly refactor things - like Sponge tends to do (significantly harder to maintain). But develop a consistent place to communicate what will be changing ahead of time, so that things like CraftEvil don’t have to exist. When there is an API break, make it easy for people to update their code even if they miss out on the new mechanics.
To further clarify. It is less about the ability to deprecate and remove things. Spigot already has that ability. The bigger picture is communicating how to transition X API to Y API in a timely fashion. Not at the time of Mojang’s final release. This cross-version documentation would make it more clear how to implement multi-version plugins since not every individual is doing the research.
The spark for this forum thread was that paper has been adding multiple PrepareFooEvent events and that could all be extended from a common event. This could probably be applied to other events as well. I personally do not tend to think about the flaws since my mindset is just working within the box.
In terms of forward-compatibility and events. I think it would be good to consider any event which has a specific entity’s name in it - to be abstract. Even if Mojang’s code doesn’t abstract it yet.
Example. For 1.15 I wrote a BeeAngerEvent for our fork. 1.16 has caused me to abstract that to an EntityAngerEvent because mojang internally abstracted it to include piglins, wolves, etc and it was easier for me to implement. For things like that, it would have been possible to deprecate the BeeAngerEvent and extend it from the EntityAngerEvent. But could have been avoided from the start if I had considered the abstract case.
Long story short. Individual entity names in events could lead to abstraction issues later on. Would be an easy API improvement even if there is only a single use of it now.
Another common api complaint is the inventory events (with regards to interaction and api accessibility). I don’t know the solution to that. As technically the current api allows most things to be possible in a horribly awkward way. In my words. It is just a wrapper for clients action. An entire thread could probably be dedicated to handling that topic alone. An extra event which fired to describe the resulting inventory action is what would be nice. The problem being the plugins are sorta designed around that not happening and makes assumptions about how to hack in what they want.
Finally. I think possibly the best thing API goals could be to look at the various plugins and look what people are reflecting into nms for. Where is the need in terms of API expansion? (somewhat off-topic to API refactoring)