Fabric Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
~~REDIRECT>https://docs.fabricmc.net/develop/entities/first-entity~~

===== Creating an Entity =====

//The source code for this project can be found [[https://github.com/Draylar/entity-testing/tree/entity|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.

===== Creating & Registering an Entity =====

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

<code java [enable_line_numbers="true"]>
/*
 * 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);
    }
}
</code>

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.

<code java [enable_line_numbers="true"]>
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() {
        
    }
}
</code>

Entities need //Attributes//, and a //Renderer// to function. 

===== Registering Entity Attributes =====

~~REDIRECT>https://docs.fabricmc.net/develop/entities/attributes#reading-modifying-attributes~~

**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:

<code java [enable_line_numbers="true"]>
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());
    }
}
</code>

===== Registering Entity Renderer =====

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.

<code java [enable_line_numbers="true"]>
/*
 * 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");
	}
}
</code>

To register this renderer, use ''EntityRenderers'' in a **client initializer**:
<code java [enable_line_numbers="true"]>
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);
    }
}
</code>

===== Creating a Render State =====

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.
<code java [enable_line_numbers="true"]>

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

===== Creating a Model and Texture =====

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.

<code java [enable_line_numbers="true"]>
public class CubeEntityModel extends EntityModel<CubeEntityRenderState> {

    private final ModelPart base;

    public CubeEntityModel(ModelPart modelPart) {
        this.base = modelPart.getChild(PartNames.CUBE);
    }
    
    [...]
}
</code>

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:

<code java [enable_line_numbers="true"]>
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);
	}
</code>

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.

<code java [enable_line_numbers="true"]>
public class CubeEntityModel extends EntityModel<CubeEntityRenderState> {
    
    private final ModelPart base;
    
    public CubeEntityModel() [...]
    
    public static LayerDefinition getTexturedModelData() [...]

    @Override
    public void setupAnim(CubeEntityRenderState entity) {
    }
}
</code>

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 64x64 for our texture:

{{https://i.imgur.com/JdF9zjf.png}}
 
<code java [enable_line_numbers="true"]>
public class CubeEntityModel extends EntityModel<CubeEntityRenderState> {

    private final ModelPart base;

    [...]
    
    public static LayerDefinition getTexturedModelData() {
        [...]
        return LayerDefinition.create(modelData, 64, 64);
    }

    [...]
} 
</code>

===== Spawning your Entity =====

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

  "entrypoints": {
    "main": [
      "mod.fabricmc.entitytesting.EntityTesting"
    ],
    "client": [
      "mod.fabricmc.entitytesting.EntityTestingClient"
    ]
  },
</code>
You can spawn your entity by typing ''/summon entitytesting:cube'' in-game. Press f3+b to view hitboxes:
{{https://i.imgur.com/MmQvluB.png}}

**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''
===== Adding tasks & activities =====

To add activities see [[tutorial:villager_activities|here]].