-
Notifications
You must be signed in to change notification settings - Fork 6
Metadata Specification
The metadata specification describes the storage format for Blackstone. Blackstone is the data project of ParchmentMC which provides a published, consumable version of the metadata available from the Minecraft JARs, removing the need for consumers to manually create the metadata from the JARs themselves.
The Named class represents an object which may have multiple names associated with it in different mappings or schemas. There are two schemas currently used by the metadata specification: the obf schema is always present, and represents the raw name based on the JAR, while the moj schema is the Mojang or Official name, which exists if the name in the obf schema can be found or remapped using Mojang's obfuscation mappings.
The contents of the named object is dependent on the context of where it is being used. For example, it may contain a class name, or a method name, or a method descriptor, or a class signature, or other types, depending on the context. Furthermore, the obf schema does not necessarily mean that the names stored by the schema are obfuscated by ProGuard, but may also refer to names which do not have a corresponding entry in Mojang's obfuscation mappings.
A named object will never be null, but a named object may be empty of any contents if there is no data or value to be associated with the object, such as for a potentially absent property of an object.
For the rest of this document, unless otherwise specified, any reference to a 'stored name' refers to a Named object.
To simplify the definition of the various metadata classes, there are multiple superinterfaces which define common attributes across different metadata classes.
-
WithName- represents an object which has a stored name. -
OwnedByClass- represents an object which has a stored name referencing the class to which this object belongs to. For example, fields and methods reference their owning class. -
WithSecurity- represents an object which has a security specification (see later sections for details). -
WithType- represents an object which has a stored name for its type descriptor, and a possibly-empty stored name for its generics signature (see later sections for details).
A metadata class may inherit from the WithSecurity superinterface, which defines those objects to hold a security specification. A security specification is an integer bitfield where each bit has a special meaning depending on what the object is. Each bit is called an access flag, and a enumeration of known access flags can be found in the AccessFlag enum. (See JVMS Table 4.1-B for outer classes, Table 4.5-A for fields, Table 4.6-A for methods, and Table 4.7.6-A for inner classes)
Examples of what the bits may mean include the access modifiers (public, protected, private), being a compiler-generated object (synthetic), being a class member instead of an instance member (static), and others. Note that multiple access flags may share the same bit, but the flag that actually applies depends on the context and on the actual type of the object holding that security specification.
Metadata objects which inherit from the WithType superinterface hold an always-present descriptor (JVMS §4.3), and a possibly-empty signature (JVMS §4.7.9.1). The generics signature is present if the metadata object as defined in the class file contains generics references, such as a method containing generic type parameters or a field containing a type which has generics. However, there is no guarantee that the signature is present, or that it corresponds neatly with the descriptor.
The source metadata (represented by the SourceMetadata class) contains the specification version for the metadata, the Minecraft version the metadata was created for, and a set of class metadata.