59
edits
Changes
From Forge Community Wiki
Basic information about entities, entity types, and spawning
{{Under construction}}
Entities are core to the Minecraft world and make up all movable objects that do not fall under [[Making Blocks|Blocks]] or [[Block Entities]]. Entities can tick and be controlled by AI or player input. This article serves as a guide for setting up a basic entity. It does not involve setting up the rendering for an entity, which is a required step to be able to see an entity in-game without crashing. See [[Entity Renderer]] for more information on entity rendering and setup.
== Entity Type ==
Much of the identity of an entity is determined by its '''entity type'''. This contains information universal to an entity. An entity type must exist and be [[Registration|registered]] for the corresponding entity to be summonable.
=== Creating the Builder ===
The primary way to make an <code>EntityType</code> is to create and configure an <code>EntityType$Builder</code>. Creating an entity type builder is done using the static factory <code>EntityType.Builder#of</code>. It requires two parameters: an <code>EntityType.EntityFactory</code> and a <code>MobCategory</code>.
The entity factory is usually an entity class with a constructor taking its own <code>EntityType</code> and <code>Level</code> of the form <code>MyEntity::new</code>. This requires a class of the name <code>MyEntity</code> to actually exist (see [[#Entity Class|the entity class section]] for more info).
The mob category is an enum describing mostly spawning properties about a category of mobs. This includes:
<ul>
<li>How many entities in a given mob category can spawn per chunk</li>
<li>Whether the entity is friendly (and therefore will spawn in peaceful difficulty)</li>
<li>Whether the entity is persistent (and therefore will save to disk and be reloaded)</li>
<li>How many blocks away a player must be for an entity in a given mob category to despawn</li>
</ul>
=== Configuring the Builder ===
An entity type builder by itself is not very useful. It must be configured to match the desired properties of the entity.
The possible properties that can be configured are listed below:
{| class="wikitable" border=1
! Method !! Default Value !! Description
|-
| <code><nowiki>sized</nowiki></code> || 0.6 meters wide by 1.8 meters tall (player dimensions) || Sets the default pose dimensions of the entity in order of square base width then height in meters/blocks. A value of 1.0 would be equivalent to the length of 1 full block. The base cannot be configured with a separate width and length.
|-
| <code><nowiki>noSummon</nowiki></code> || Can summon || Calling this prevents spawning the entity through <code>/summon</code>; intended for internal entities that a user should not be able to create. This also prevents summoning through natural spawning in biomes, if it is configured.
|-
| <code><nowiki>noSave</nowiki></code> || Can save || Calling this prevents the entity from ever saving to disk. Unloading a chunk with a <code>noSave</code> entity will effectively delete the entity.
|-
| <code><nowiki>fireImmune</nowiki></code> || Vulnerable to fire || Calling this prevents the entity from taking any fire/lava damage.
|-
| <code><nowiki>clientTrackingRange</nowiki></code> || 5 chunks || Sets the maximum range in chunks in which players should be sent update packet information about the entity. Sending update information about an entity to a player is known as the player ''tracking'' that entity. If the player is outside this chunk range, they will not know of the entity's existence.
|-
| <code><nowiki>immuneTo</nowiki></code> || Empty set of blocks || Effectively useless for modding purposes.
|-
| <code><nowiki>canSpawnFarFromPlayer</nowiki></code> || True for <code>MobCategory.CREATURE</code> and <code>MobCategory.MISC</code>, false otherwise. || Calling this allows an entity to spawn outside of the despawn distance of its mob category.
|-
| <code><nowiki>updateInterval</nowiki></code> || 3 ticks || How often, in ticks, update packets should be sent to all client players tracking this entity (see <code>clientTrackingRange</code>). The update packets contain information like position, rotation, and velocity. They may be sent more quickly than this interval during specific actions.
|-
| <code><nowiki>setShouldReceiveVelocityUpdates</nowiki></code> || true || Sets whether tracking client players should receive velocity information in update interval packets. If false, velocity information will not be sent to clients unless necessary.
|}
=== Building the Builder ===
After creating and configuring the entity type builder, it must be built. This requires the modid and name of the entity type. For an entity type with the name "example_monster" in the mod "examplemod", this would look like <code>builder.build("examplemod:example_monster")</code>.
=== Tying It Together ===
Given the above information, a basic EntityType might look like the following:
{{Tabs/Code Snippets
|java=EntityType.Builder.of(ExampleMonsterEntity::new, MobCategory.MONSTER)
.sized(1.0F, 2.0F)
.fireImmune()
.updateInterval(1)
.build("examplemod:example_monster")
}}
To function, this example requires that an entity class of the name <code>ExampleMonsterEntity</code> exist along with the entity type being [[Registration|registered]].
== Entity Class ==
Alongside an entity type, an entity requires a class outlining its behavior and any information that may change from one instance to another. All entities must extend from the base class <code>Entity</code>. However, some entities should extend from specific subclasses instead. For a completely generic entity, use <code>Entity</code>. For a living entity with health, potion effects, and an inventory, use <code>LivingEntity</code>. For a living entity with movement AI and AI goals, use <code>Mob</code>. There are also many other entity subclasses which can be found through your IDE and picked depending on the scenario.
Once picking a target superclass to extend, an entity class should be created and the constructor should be setup. It should look something like this:
{{Tabs/Code Snippets|
java=public class ExampleMonsterEntity extends Mob {
public ExampleMonsterEntity(EntityType<? extends Mob> entityType, Level level) {
super(entityType, level);
}
}
}}
To define custom behavior, methods must be overriden. Your IDE should have a feature to list all possible methods to override, although some common ones might be: <code>customServerAiStep</code> for server AI, <code>tick</code> for code to execute each tick on client/server, and <code>registerGoals</code> to setup AI goals.
== Natural Spawning ==
To make entities naturally spawn, they must be added to the spawn list for each biome that the entity should spawn in. This can be achieved with a [[Biome_Modifiers#Add_Spawns|<code>forge:add_spawns</code> biome modifier]].
Entities are core to the Minecraft world and make up all movable objects that do not fall under [[Making Blocks|Blocks]] or [[Block Entities]]. Entities can tick and be controlled by AI or player input. This article serves as a guide for setting up a basic entity. It does not involve setting up the rendering for an entity, which is a required step to be able to see an entity in-game without crashing. See [[Entity Renderer]] for more information on entity rendering and setup.
== Entity Type ==
Much of the identity of an entity is determined by its '''entity type'''. This contains information universal to an entity. An entity type must exist and be [[Registration|registered]] for the corresponding entity to be summonable.
=== Creating the Builder ===
The primary way to make an <code>EntityType</code> is to create and configure an <code>EntityType$Builder</code>. Creating an entity type builder is done using the static factory <code>EntityType.Builder#of</code>. It requires two parameters: an <code>EntityType.EntityFactory</code> and a <code>MobCategory</code>.
The entity factory is usually an entity class with a constructor taking its own <code>EntityType</code> and <code>Level</code> of the form <code>MyEntity::new</code>. This requires a class of the name <code>MyEntity</code> to actually exist (see [[#Entity Class|the entity class section]] for more info).
The mob category is an enum describing mostly spawning properties about a category of mobs. This includes:
<ul>
<li>How many entities in a given mob category can spawn per chunk</li>
<li>Whether the entity is friendly (and therefore will spawn in peaceful difficulty)</li>
<li>Whether the entity is persistent (and therefore will save to disk and be reloaded)</li>
<li>How many blocks away a player must be for an entity in a given mob category to despawn</li>
</ul>
=== Configuring the Builder ===
An entity type builder by itself is not very useful. It must be configured to match the desired properties of the entity.
The possible properties that can be configured are listed below:
{| class="wikitable" border=1
! Method !! Default Value !! Description
|-
| <code><nowiki>sized</nowiki></code> || 0.6 meters wide by 1.8 meters tall (player dimensions) || Sets the default pose dimensions of the entity in order of square base width then height in meters/blocks. A value of 1.0 would be equivalent to the length of 1 full block. The base cannot be configured with a separate width and length.
|-
| <code><nowiki>noSummon</nowiki></code> || Can summon || Calling this prevents spawning the entity through <code>/summon</code>; intended for internal entities that a user should not be able to create. This also prevents summoning through natural spawning in biomes, if it is configured.
|-
| <code><nowiki>noSave</nowiki></code> || Can save || Calling this prevents the entity from ever saving to disk. Unloading a chunk with a <code>noSave</code> entity will effectively delete the entity.
|-
| <code><nowiki>fireImmune</nowiki></code> || Vulnerable to fire || Calling this prevents the entity from taking any fire/lava damage.
|-
| <code><nowiki>clientTrackingRange</nowiki></code> || 5 chunks || Sets the maximum range in chunks in which players should be sent update packet information about the entity. Sending update information about an entity to a player is known as the player ''tracking'' that entity. If the player is outside this chunk range, they will not know of the entity's existence.
|-
| <code><nowiki>immuneTo</nowiki></code> || Empty set of blocks || Effectively useless for modding purposes.
|-
| <code><nowiki>canSpawnFarFromPlayer</nowiki></code> || True for <code>MobCategory.CREATURE</code> and <code>MobCategory.MISC</code>, false otherwise. || Calling this allows an entity to spawn outside of the despawn distance of its mob category.
|-
| <code><nowiki>updateInterval</nowiki></code> || 3 ticks || How often, in ticks, update packets should be sent to all client players tracking this entity (see <code>clientTrackingRange</code>). The update packets contain information like position, rotation, and velocity. They may be sent more quickly than this interval during specific actions.
|-
| <code><nowiki>setShouldReceiveVelocityUpdates</nowiki></code> || true || Sets whether tracking client players should receive velocity information in update interval packets. If false, velocity information will not be sent to clients unless necessary.
|}
=== Building the Builder ===
After creating and configuring the entity type builder, it must be built. This requires the modid and name of the entity type. For an entity type with the name "example_monster" in the mod "examplemod", this would look like <code>builder.build("examplemod:example_monster")</code>.
=== Tying It Together ===
Given the above information, a basic EntityType might look like the following:
{{Tabs/Code Snippets
|java=EntityType.Builder.of(ExampleMonsterEntity::new, MobCategory.MONSTER)
.sized(1.0F, 2.0F)
.fireImmune()
.updateInterval(1)
.build("examplemod:example_monster")
}}
To function, this example requires that an entity class of the name <code>ExampleMonsterEntity</code> exist along with the entity type being [[Registration|registered]].
== Entity Class ==
Alongside an entity type, an entity requires a class outlining its behavior and any information that may change from one instance to another. All entities must extend from the base class <code>Entity</code>. However, some entities should extend from specific subclasses instead. For a completely generic entity, use <code>Entity</code>. For a living entity with health, potion effects, and an inventory, use <code>LivingEntity</code>. For a living entity with movement AI and AI goals, use <code>Mob</code>. There are also many other entity subclasses which can be found through your IDE and picked depending on the scenario.
Once picking a target superclass to extend, an entity class should be created and the constructor should be setup. It should look something like this:
{{Tabs/Code Snippets|
java=public class ExampleMonsterEntity extends Mob {
public ExampleMonsterEntity(EntityType<? extends Mob> entityType, Level level) {
super(entityType, level);
}
}
}}
To define custom behavior, methods must be overriden. Your IDE should have a feature to list all possible methods to override, although some common ones might be: <code>customServerAiStep</code> for server AI, <code>tick</code> for code to execute each tick on client/server, and <code>registerGoals</code> to setup AI goals.
== Natural Spawning ==
To make entities naturally spawn, they must be added to the spawn list for each biome that the entity should spawn in. This can be achieved with a [[Biome_Modifiers#Add_Spawns|<code>forge:add_spawns</code> biome modifier]].