Catalog Types
A big part of the data API consists of special values with a specific meaning. In previous versions of Minecraft these
have been numbers such as 1
that meant something specific in a given context, for example a simple stone in
the /give
command. From version to version Minecraft moved away from these magics numbers and moved to a more
declarative way using (namespaced) identifiers such as minecraft:stone
. This however brought up two big issues with
these values:
How do I persist them and reload them?
Which values do exist?
Because of this, Sponge introduced a new class of data: CatalogTypes.
CatalogType
s provide two methods that make them very versatile.
First, the CatalogType#getId() method that provides an easy access to a unique identifier (within that type of data) that can be used to save it to a config file and retrieve it back using the GameRegistry#getType(Class, String) method. In fact you don’t have to do this yourself, you can rely on Sponge’s config serialization to do this for you instead.
Some ids are not really human readable, so there is another method for CatalogType
s that tries to return a human
readable name. You can also check whether your type is Translatable, which gives you a good name to show to
your players using their locale.
GameRegistry
The GameRegistry gives you access to all variants of a CatalogType
s using the
GameRegistry#getAllOf(Class) method. It also offers various other ways of retrieving a CatalogType
and
related classes such as builders for most classes including data classes. You can also get more specific registries from
there such as the VillagerRegistry
and the recipe registries.
Usage in Commands
CatalogType
s can be easily used in Plugin Commands using the catalogedElement
which will automatically
support auto completion for all possible variants of the given type. Read more about it in the
Análisis de argumentos section.
Catalog Classes
Sometimes we just want to reference a CatalogType
entry in our code without actually getting it from the registry;
this is usually the case for default values. To simplify these use-cases there are additional catalog classes which
contain static references to types that are either provided by Minecraft itself or Sponge. You can locate these classes
by following the CatalogedBy annotation on your CatalogType
class. If the annotation is missing on that
class please also check the parent and child classes. If the class has too many variants or variants can be added and
removed at runtime then there won’t be a catalog class. A list of all native catalog types can be found in
CatalogTypes.
Advertencia
Do not use those static references inside your own static fields, because the references are initialized only during game startup and thus might still contain their dummy values. Using these dummy values will cause exceptions that might be hard to trace back to their origin.