Documentation: Registries: why?

2

There are two things to address here.

  1. It is recommended to use the RegistryEvents to register your stuff, but you can just as easily and correctly do it using the GameRegistry in preInit (which is the way we've done it forever, too). It is not explained why it is recommended to use RegistryEvents over the other way. This needs to be explained.
  2. The value of making a registry with the RegistryBuilder is not explained. I can just as easily make a static class in my API that functions as a registry. Why should we use the RegistryBuilder over a private static map or list gated behind some helper functions? This needs to be explained in the docs.
elifoster picture elifoster  ·  3 Jan 2017

Most helpful comment

3

From the perspective of someone who is relatively new to the modding scene, I think it is much more intuitive to include the _why_ when there are API changes. While, yes, docs are usually supposed to just say how and not why, I can think of a couple of reasons why it makes sense in this case. The existing 1.12+ tutorials tend to use the old GameRegistry method, as mentioned by others here, so new modders may not be familiar with the new method. Unless someone pieces apart the Forge API from source, which is an unlikely feat for newer programmers, one would need to be given a reason why.

Also, one has to consider the size of the community. With a much larger community, like in the area of, say, web development, if some new feature of some package becomes popular, the community will be quick to answer the _why_. The devs aren’t burdened with that. They just have to say what they changed and then they can rely on the community to explore it and share what’s new and what benefits the new feature brings. With modding Minecraft, it’s a bit different. The community is not as large, so often times it’s the burden of the developers or those brave enough to dig through source, forgoing tutorials, to share what is changed and why others should switch to the new way of doing things.
That is more of a general rule. I think, no matter the size of the community, it is always useful to include a reason for switching to a new way of doing things, especially if that reason comes from the official docs and/or the devs themselves. Humans don’t typically change their ways without a good reason.

It’s because of these things that I would like to see an even lengthier reason in the docs for why we should ditch the GameRegistry, much like the one Lex presented.

cavatron picture cavatron  ·  15 Apr 2018

All comments

0

I suppose "why" belongs in the paragraph about using the old method. I can think of a few specific reasons why the new system is preferred:

1) Faster startup
2) Easier cross-mod compatibility and interaction
3) Unfathomable future possibilities thanks to a more managed API

But a shorter one sentence reason is probably good enough, which could be along the lines of "because it lets Forge actually register things at the most appropriate time". That potential for optimization should be reason enough.

cosmicdan picture cosmicdan  ·  30 Mar 2018
0

1) The main difference is reinitalization. We are slowly {fighting modders every step of the way} trying to move Minecraft into a more data/instanced system. If people use the registry events it means we can nuke the registry, and re-run the register event and end up with a valid registry. We can't do that if modders are adding/removing crap all over the place. Why is this important? Connecting to servers, or loading multiple single player worlds. We hack around things using delegates and magic reflection replacements. But it would be nice to get away from that.

2) RegistryBuilder is just a normal builder pattern. Thats a fairly common java object style. As for why use a Forge registry over a Map? If you have soft dependencies on things having the events fire the creation is ideal. However, if you don't care about forcing a hard dep , and you don't care about syncing the ids over the network/disc {or if you dont use integer IDs anywhere at all} then you can just use normal Maps.
But Forge registries have a lot of benefits:
k/v <-> int id
S->C sync/compressed id usage.
Override tracking/management
Few other things, but there are benefits, and costs.

LexManos picture LexManos  ·  31 Mar 2018
0

Great explanation Lex, makes much more sense than what I said - re-initialization alone is a great reason.

So the original issue was the documentation lacking an explanation on why the new system is preferred over the old system. Is it even necessary to justify such a change within the _documentation_?

cosmicdan picture cosmicdan  ·  31 Mar 2018
0

@cosmicdan As long as both are present I believe so, personally.

elifoster picture elifoster  ·  2 Apr 2018
1

As long as both are present I believe so, personally.

That's true. But, beyond common sense, a lot of it comes down to subjective opinion. As someone who has been an on-and-off modder for only a couple years, I consider the move to registries and events as an intuitive one, if only from the point of view of API consistency (us Java developers are not exactly used to API consistency are we lol). Most of the other ways Forge interfaces with Minecraft is through events, so it makes sense that this also be in events. So it's just "better".

With that said, one of my mods does still need to use the old method of registering blocks. It creates blocks that depend on oreDict entries from other mods, and the oreDict isn't completely populated until later - so I do it myself manually.

So to me, the main advantage and disadvantage of the new registration system are one and the same - it's more managed. This goes the same as for creating your own Forge registry.

Lex already explained the technicalities on why it is better, but I question whether the documentation needs _that much detail_ - it really doesn't. Docs are for explaining how, not why. Only people who are stuck in the old system are going to care; most any new modder will appreciate the new implementation that Forge provides for them - like any good API should.

Hopefully with Events we'll one day be completely free of the crapshoot and boilerplate that is SidedProxy's too. But at the same time, they should stay available for those 5% of cases where an existing registry/event doesn't account for that exact implementation detail.

EDITED: Words

cosmicdan picture cosmicdan  ·  2 Apr 2018
3

While I generally agree with you Lex is constantly complaining about modders using old systems or hackily re-implementing old systems, and 1) the overwhelming majority of mod development guides are oldish; 2) while those old systems exist people will not want to update until they are absolutely forced. I think that providing a rationale helps push at least some people who generally are too lazy to update to new systems to actually do it.

elifoster picture elifoster  ·  2 Apr 2018
3

From the perspective of someone who is relatively new to the modding scene, I think it is much more intuitive to include the _why_ when there are API changes. While, yes, docs are usually supposed to just say how and not why, I can think of a couple of reasons why it makes sense in this case. The existing 1.12+ tutorials tend to use the old GameRegistry method, as mentioned by others here, so new modders may not be familiar with the new method. Unless someone pieces apart the Forge API from source, which is an unlikely feat for newer programmers, one would need to be given a reason why.

Also, one has to consider the size of the community. With a much larger community, like in the area of, say, web development, if some new feature of some package becomes popular, the community will be quick to answer the _why_. The devs aren’t burdened with that. They just have to say what they changed and then they can rely on the community to explore it and share what’s new and what benefits the new feature brings. With modding Minecraft, it’s a bit different. The community is not as large, so often times it’s the burden of the developers or those brave enough to dig through source, forgoing tutorials, to share what is changed and why others should switch to the new way of doing things.
That is more of a general rule. I think, no matter the size of the community, it is always useful to include a reason for switching to a new way of doing things, especially if that reason comes from the official docs and/or the devs themselves. Humans don’t typically change their ways without a good reason.

It’s because of these things that I would like to see an even lengthier reason in the docs for why we should ditch the GameRegistry, much like the one Lex presented.

cavatron picture cavatron  ·  15 Apr 2018