Fabric Wiki

The source code for this project can be found here.

Entities are a movable object in a world with logic attached to them. A few examples include:

• Minecarts
• Arrows
• Boats

Living Entities are Entities that have health and can deal damage. There are various classes that branch off `LivingEntity` for different purposes, including:

• HostileEntity for Zombies, Creepers and Skeletons
• AnimalEntity for Sheep, Cows and Pigs
• WaterCreatureEntity for things that swim
• FishEntity for fishies (use instead of WaterCreatureEntity for schooling behavior)

What you extend depends on what your needs and goals are. As you get further down the chain, the entity logic becomes more specific and curated to certain tasks. The two generic entity classes that come after LivingEntity are:

• MobEntity
• PathAwareEntity

MobEntity has AI logic and movement controls. PathAwareEntity provides extra capabilities for pathfinding favor, and various AI tasks require this to operate.

In this tutorial, we will look at creating a cube entity that extends PathAwareEntity. This entity will have a model & texture. Movement and mechanics will be covered in a future tutorial.

Create a class that extends PathAwareEntity. This class serves as the brains and main hub for our custom entity.

/*
 * Our Cube Entity extends PathAwareEntity, which extends MobEntity, which extends LivingEntity.
 *
 * LivingEntity has health and can deal damage.
 * MobEntity has movement controls and AI capabilities.
 * PathAwareEntity has pathfinding favor and slightly tweaked leash behavior.
 */
public class CubeEntity extends PathAwareEntity {
 
    public CubeEntity(EntityType<? extends PathAwareEntity> entityType, World world) {
        super(entityType, world);
    }
}

You can register this entity under the ENTITY_TYPE registry category. Fabric provides a FabricEntityTypeBuilder class, which is an extension of the vanilla EntityType.Builder class. The Fabric builder class provides extra methods for configuring your entities' tracking values.

public class EntityTesting implements ModInitializer {
 
    /*
     * Registers our Cube Entity under the ID "entitytesting:cube".
     *
     * The entity is registered under the SpawnGroup#CREATURE category, which is what most animals and passive/neutral mobs use.
     * It has a hitbox size of .75x.75, or 12 "pixels" wide (3/4ths of a block).
     */
    public static final EntityType<CubeEntity> CUBE = Registry.register(
            Registries.ENTITY_TYPE,
            Identifier.of("entitytesting", "cube"),
            EntityType.Builder.create(CubeEntity::new, SpawnGroup.CREATURE).dimensions(0.75f, 0.75f).build("cube")
    );
 
    @Override
    public void onInitialize() {
 
    }
}

Entities need Attributes, and a Renderer to function.

Attributes define the properties of the mob: how much health does it have? How much damage does it do? Does it have any default armor points?

Most vanilla entities have a static method that returns their attributes (such as ZombieEntity#createZombieAttributes). Our custom entity doesn't have any unique properties, for now, so we can use MobEntity#createMobAttributes.

Vanilla has a DefaultAttributeRegistry class for registering these properties. It isn't publicly exposed or easily available, so Fabric provides a FabricDefaultAttributeRegistry class. The registration of default attributes should occur somewhere in your mod's initialization phase:

public class EntityTesting implements ModInitializer {
 
    public static final EntityType<CubeEntity> CUBE = [...];
 
    @Override
    public void onInitialize() {
        /*
         * Register our Cube Entity's default attributes.
         * Attributes are properties or stats of the mobs, including things like attack damage and health.
         * The game will crash if the entity doesn't have the proper attributes registered in time.
         *
         * In 1.15, this was done by a method override inside the entity class.
         * Most vanilla entities have a static method (eg. ZombieEntity#createZombieAttributes) for initializing their attributes.
         */
        FabricDefaultAttributeRegistry.register(CUBE, CubeEntity.createMobAttributes());
    }
}

The last requirement of an entity is a Renderer. Renderers define *what* the entity looks like, generally by providing a model. MobEntityRenderer is the best choice for MobEntities. The class has one required method override for providing a texture, and wants 3 parameters for the super constructor:

• EntityRenderDispatcher instance
• Model of our entity
• shadow size of our entity as a float

The following code showcases a simple entity renderer with a shadow size of 0.5f and texture at resources/assets/entitytesting/textures/entity/cube/cube.png. Note that the texture and model class will be created in the next step.

/*
 * A renderer is used to provide an entity model, shadow size, and texture.
 */
public class CubeEntityRenderer extends MobEntityRenderer<CubeEntity, CubeEntityModel> {
 
    public CubeEntityRenderer(EntityRendererFactory.Context context) {
        super(context, new CubeEntityModel(context.getPart(EntityTestingClient.MODEL_CUBE_LAYER)), 0.5f);
    }
 
    @Override
    public Identifier getTexture(CubeEntity entity) {
        return new Identifier("entitytesting", "textures/entity/cube/cube.png");
    }
}

To register this renderer, use EntityRendererRegistry in a client initializer:

@Environment(EnvType.CLIENT)
public class EntityTestingClient implements ClientModInitializer {
    public static final EntityModelLayer MODEL_CUBE_LAYER = new EntityModelLayer(new Identifier("entitytesting", "cube"), "main");
    @Override
    public void onInitializeClient() {
        /*
         * Registers our Cube Entity's renderer, which provides a model and texture for the entity.
         *
         * Entity Renderers can also manipulate the model before it renders based on entity context (EndermanEntityRenderer#render).
         */
        EntityRendererRegistry.INSTANCE.register(EntityTesting.CUBE, (context) -> {
            return new CubeEntityRenderer(context);
        });
        // In 1.17, use EntityRendererRegistry.register (seen below) instead of EntityRendererRegistry.INSTANCE.register (seen above)
        EntityRendererRegistry.register(EntityTesting.CUBE, (context) -> {
            return new CubeEntityRenderer(context);
        });
 
        EntityModelLayerRegistry.registerModelLayer(MODEL_CUBE_LAYER, CubeEntityModel::getTexturedModelData);
    }
}

The final step to finishing our entity is creating a model and texture. Models define the structure of the entity, while the texture provides the color.

Standard models define “parts”, or ModelPart instances at the top of the class, initialize them in the constructor, obtain data in the getTexturedModelData method, and render them in the render method. Note that setAngles and render are both required overrides of the EntityModel class.

public class CubeEntityModel extends EntityModel<CubeEntity> {
 
    private final ModelPart base;
 
    public CubeEntityModel(ModelPart modelPart) {
        this.base = modelPart.getChild(EntityModelPartNames.CUBE);
    }
 
    [...]
}

After creating a part, we need to add a shape to it. To do so, we must add a child to the root. The texture location for the new part is located in .uv, the offset for it is located in the first 3 numbers of .cuboid, and the size is the last 3 numbers in .cuboid. Note that the origin of a model starts at the corner, so you will need to offset the part to center it:

public class CubeEntityModel extends EntityModel<CubeEntity> {
 
    private final ModelPart base;
 
    public CubeEntityModel() {
        [...]
    }
 
    // You can use BlockBench, make your model and export it to get this method for your entity model.
    public static TexturedModelData getTexturedModelData() {
        ModelData modelData = new ModelData();
    	ModelPartData modelPartData = modelData.getRoot();
        modelPartData.addChild(EntityModelPartNames.CUBE, ModelPartBuilder.create().uv(0, 0).cuboid(-6F, 12F, -6F, 12F, 12F, 12F), ModelTransform.pivot(0F, 0F, 0F));
        return TexturedModelData.of(modelData, 64, 64);
    }

Our entity model now has a single cube that is 12x12x12 wide (75% of a block) centered around 0, 0, 0. setAngles is used for animating the model, but we will keep it empty for now. render is where we tell our cube to show up. Note that standard vanilla models appear higher than the entity hitbox, so we translate the model down to account for this.

public class CubeEntityModel extends EntityModel<CubeEntity> {
 
    private final ModelPart base;
 
    public CubeEntityModel() [...]
 
    public static TexturedModelData getTexturedModelData() [...]
 
    @Override
    public void setAngles(CubeEntity entity, float limbAngle, float limbDistance, float animationProgress, float headYaw, float headPitch) {
    }
 
    @Override
    public void render(MatrixStack matrices, VertexConsumer vertices, int light, int overlay, float red, float green, float blue, float alpha) {
        ImmutableList.of(this.base).forEach((modelRenderer) -> {
            modelRenderer.render(matrices, vertices, light, overlay, red, green, blue, alpha);
        });
    }
}

To complete our model, we need to add a texture file. The default texture size is 64 wide and 32 tall; you can change this by adding a return of your texturedModelData We will set it to 64×64 for our texture:

public class CubeEntityModel extends EntityModel<CubeEntity> {
 
    private final ModelPart base;
 
    [...]
 
    public static TexturedModelData getTexturedModelData() {
        [...]
        return TexturedModelData.of(modelData, 64, 64);
    }
 
    [...]
} 

Be sure to add your client entrypoint to fabric.mod.json. You can do this like so:

  "entrypoints": {
    "main": [
      "mod.fabricmc.entitytesting.EntityTesting"
    ],
    "client": [
      "mod.fabricmc.entitytesting.EntityTestingClient"
    ]
  },

You can spawn your entity by typing /summon entitytesting:cube in-game. Press f3+b to view hitboxes:

NOTE: If your entity does not extend LivingEntity you have to create your own spawn packet handler. Either do this through the networking API, or mixin to ClientPlayNetworkHandler#onEntitySpawn

To add activities see here.