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:

• Monster for Zombies, Creepers and Skeletons
• Animal for Sheep, Cows and Pigs
• WaterAnimal for things that swim
• AbstractFish for fish (use instead of WaterAnimal 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:

• Mob
• PathfinderMob

Mob has AI logic and movement controls. PathfinderMob 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 PathfinderMob. This entity will have a model & texture. Movement and mechanics will be covered in a future tutorial.

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

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

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 MobCategory#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(
            BuiltInRegistries.ENTITY_TYPE,
            Identifier.fromNamespaceAndPath("entitytesting", "cube"),
            EntityType.Builder.create(CubeEntity::new, MobCategory.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 Zombie#createAttributes). Our custom entity doesn't have any unique properties, for now, so we can use Mob#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. Zombie#createAttributes) 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. MobRenderer 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 MobRenderer<CubeEntity, CubeEntityRenderState, CubeEntityModel> {
 
    public CubeEntityRenderer(EntityRendererProvider.Context context) {
        super(context, new CubeEntityModel(context.bakeLayer(EntityTestingClient.MODEL_CUBE_LAYER)), 0.5f);
    }
 
    @Override
	public CubeEntityRenderState createRenderState() {
		return new CubeEntityRenderState();
	}
 
	@Override
	public Identifier getTextureLocation(CubeEntityRenderState livingEntityRenderState) {
		return Identifier.fromNamespaceAndPath("entitytesting", "textures/entity/cube/cube.png");
	}
}

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

public class EntityTestingClient implements ClientModInitializer {
    public static final ModelLayerLocation MODEL_CUBE_LAYER = new ModelLayerLocation(Identifier.fromNamespaceAndPath("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).
         */
        EntityRenderers.register(EntityTesting.CUBE, (context) -> {
            return new CubeEntityRenderer(context);
        });
 
        EntityModelLayerRegistry.registerModelLayer(MODEL_CUBE_LAYER, CubeEntityModel::getTexturedModelData);
    }
}

The render state is a class that can be used to store data for the renderer. It is passed into the renderer and model, and can be used to store data about the entity, like the entity's variant or other properties that affect rendering.

public class CubeEntityRenderState extends EntityRenderState {
    // You can add fields here to store data for the renderer and model.
}

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<CubeEntityRenderState> {
 
    private final ModelPart base;
 
    public CubeEntityModel(ModelPart modelPart) {
        this.base = modelPart.getChild(PartNames.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<CubeEntityRenderState> {
 
    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 LayerDefinition getTexturedModelData() {
		MeshDefinition modelData = new MeshDefinition();
		PartDefinition modelPartData = modelData.getRoot();
		modelPartData.addOrReplaceChild(PartNames.CUBE, CubeListBuilder.create().texOffs(0, 0).addBox(-6F, 12F, -6F, 12F, 12F, 12F), PartPose.rotation(0F, 0F, 0F));
		return LayerDefinition.create(modelData, 64, 64);
	}

Our entity model now has a single cube that is 12x12x12 wide (75% of a block) centered around 0, 0, 0. setupAnim is used for animating the model, but we will keep it empty for now.

public class CubeEntityModel extends EntityModel<CubeEntityRenderState> {
 
    private final ModelPart base;
 
    public CubeEntityModel() [...]
 
    public static LayerDefinition getTexturedModelData() [...]
 
    @Override
    public void setupAnim(CubeEntityRenderState entity) {
    }
}

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

public class CubeEntityModel extends EntityModel<CubeEntityRenderState> {
 
    private final ModelPart base;
 
    [...]
 
    public static LayerDefinition getTexturedModelData() {
        [...]
        return LayerDefinition.create(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 ClientPacketListener#handleAddEntity

To add activities see here.