How To: Creating Retextured Models

Introduction

Some mods need models that are simply re-textured versions of existing JSON models. It can be tedious to create and maintain a large number of JSON block state and model files for these repetitive scenarios. In other cases, the specific number and type of these models is dynamic or configurable and thus not suitable for static JSON assets.

The RetexturedModelBuilder interface provides a way to generate the models automatically.

public interface RetexturedModelBuilder {
    public static RetexturedModelBuilder builder(String sourceModel, String targetModel) {
        return builder(new Identifier(sourceModel), new Identifier(targetModel));
    }
    
    public static RetexturedModelBuilder builder(Identifier sourceModel, Identifier targetModel) {
        return RexturedModelBuilderImpl.builder(sourceModel, targetModel);
    }

    RetexturedModelBuilder mapSprite(Identifier from, Identifier to);

    RetexturedModelBuilder mapSprite(String from, String to);

    public void completeBlockWithItem();

    void completeBlock();

    void completeItem();
}

Using RetexturedModelBuilder

1. Create and register your blocks/items as you normally would.

2. Identify a block/item to use as a template that will be retextured. The template block/item must have the same properties as the block/item that will use the generated model. This is particularly important for multi-part models - the model logic itself will also be copied and must match for this feature to work correctly.

3. Identify the fully-qualified name of all textures used in the template model, including all sub-parts.

4. During your client mod initializer (or in JmxInitializer.onInitializeJMX() if you are using JMX as a soft dependency) to build and register a model for each block/item using RetexturedModelBuilder.

Here's an example for a new fence block named mymod:myfence:

 RetexturedModelBuilder.builder("minecraft:acacia_fence", "mymod:myfence")
                .mapSprite("minecraft:block/acacia_planks", "mymod:block/myfence").completeBlockWithItem();

The example above assumes the block and items are separately created and registered, and a texture named myfence.png is in the assets/textures/block' for the mymod` mod.

Note that mapSprite() can and should be called as many times as necessary to remap all textures in the model.

JMX will automatically create the appropriate models and ensure all textures are included in the Block/Item texture atlas.

Limitations for Retextured Models

• Only JSON-type models can be used as templates. (Including weighted and multipart models.)
• Can only be used to create new models. Not meant for replacing existing models. (Use a resource pack for that.) Behavior is currently undefined if this is attempted.
• This feature cannot currently remap materials. If, for example, you remap a model with normally-solid faces to use a translucent or cutout texture, it will still render as solid. To workaround, create a new JSON model with the appropriate materials to use as a template.