I cannot for the life of me understand how capabilities work. It may just be the way I'm needing to implement them, so I'll be talking about that specifically.
I'm currently making a mod that adds a modifier to the player's health to allow for more than just the generic 20 max health. Previously I used a class that contained a player cache and had functions to store and modify the NBT data of said player. Well, I was recently told to use capabilities now, but I have absolutely no idea how to do that. From what I understand, capabilities are supposed to be an easy way to store data alongside Minecraft classes. For example, an easy way to store data for a furnace or something. What I don't understand is how the hell this is supposed to work; what is a capability? Is it a modification to the way things work? Or is it supposed to be an easy interface between NBT data and Minecraft objects? How the hell do you attach a capability to an Entity? Do I need to provide my own Capability Provider, or use one of Forge's? If I need to use one of Forge's, which one do i use? How do I provide my own, in the case I need to do that (the forge documentation is useless and outdated). What does it mean to "expose" a capability? What is a capability type? What does it mean to "attach" a capability? Capabilities do not make sense at all!
I will attempt to break this down so you can understand what I don't: "In general terms, each capability provides a feature in the form of an interface, alongside with a default implementation which can be requested, and a storage handler for at least this default implementation. " "each capability provides a feature in the form of an interface," what does this even mean? I've completed my college course on Java and still have no idea what this implies. A Java interface is used to easily describe classes and provides a layer of abstraction, it is not supposed to provide features. You cannot "implement" a feature using an interface. "alongside with a default implementation which can be requested," what? A default implementation versus... what, a custom one? Someone else's? Why not just implement what you need instead of attempting to provide an interface? "a storage handler for at least this default implementation," again, what is this 'default implementation', and what other types of implementations are there? Also, what in the world is this implementation?
I, alongside many others, learn best by example, but the examples on the Forge docs don't provide any context whatsoever. The text refers to things that haven't been talked about, and implies that you have already created things that you didn't even know existed. How am I supposed to have made an "instance of the underlying capability type" if I didn't even know I needed to make one? Maybe I'm just having a hard time understanding Forge's documentation, but I have no idea what capabilities are supposed to be, what they provide in functionality, and how they're supposed to be "easier" than just directly interfacing with a player's NBT data. And yes, I have looked in the source, and no, it doesn't help whatsoever because if I don't even know what they do in the first place how am I supposed to understand an implementation?
Note: Once I truly understand the purpose of a capability and how to implement one, I would love to make a PR to help improve the wording of the docs.