MoreMcmeta parser plugins read metadata files with a particular extension.

Every parser plugin reads files with a particular extension, which is returned by the extension() method of MoreMcmetaMetadataParserPlugin.

If two plugins have the same extension, and one plugin is a default plugin, then the default plugin will be disabled. If two plugins have the same extension, but neither is a default plugin, then there will be a conflict.

The metadata parser has two roles:

• parsing metadata from a file into MetadataViews
• combining multiple MetadataViews for the same texture into a single MetadataView

A single file might contain metadata relevant to multiple textures, so parse() returns a map of texture paths to MetadataViews.

MetadataView allows for values of all the Java primitive types, as well as InputStreams for binary data. Some file formats may differentiate between key-value objects and arrays, but MetadataView does not: they are both treated as a "sub view." If you need to parse an array, you can simply use the index of each element in the array as the key.

Each MetadataView should contain sub views where the key for each sub view is the metadata section name. See the texture plugin documentation for more information about section names. Primitive values or nested sub views should be inside the sub view for each section.

The ordering of sections in the MetadataView returned by parse() is the order in which plugins will be applied. If the underlying file format is inherently unordered, then you should provide a way for users to set the order. For example, JSON objects are considered unordered. MoreMcmeta's default JSON (.moremcmeta) plugin allows users to specify a layer that determines the order in which plugins are applied; otherwise, it defaults to alphabetical order. At minimum, the ordering of sections should be deterministic so that for a given texture, plugins are applied in the same order every time the game runs.

Any metadata provided to the parser in the combine() method is guaranteed to come from its parse() method. That is, if parse() always returns metadata of a specific subclass, then the combine() method will always receive metadata of that subclass.

Like parse(), combine() method should pay attention to the ordering of sections in the returned MetadataView.

Both the parse() and combine() methods may throw an InvalidMetadataException if the metadata cannot be parsed or combined. MoreMcmeta will handle these exceptions and log warnings with the exception message.

Exceptions thrown should be focused on issues with parsing and combining the metadata, not issues related to specific texture plugins. For example, MoreMcmeta's .properties parser plugin does not throw exceptions when a boolean is used for frame time in an animation. The animation plugin is responsible for indicating that the use of a boolean is invalid. However, the .properties plugin does throw an exception if a .properties file contains image data.

Keep the average user in mind: not everyone configuring textures will be a technical expert. Try to explain the problem simply and be specific as to where the issue is. Don't throw an exception with a message that amounts to "error."

MoreMcmeta will not handle exceptions besides InvalidMetadataException, and other exceptions may crash the game. If you use code that throws other exception types, you must catch and rethrow them as InvalidMetadataExceptions.

Methods in the MetadataParser may be called from multiple threads. If any internal state is required, it must be thread-safe.