Entity API

Overview

The Entity API provides the foundation for all moving and interactive objects in Minecraft Community Edition. This includes players, mobs, items, projectiles, and vehicles.

Class Hierarchy

Entity (abstract)
  ├── Mob
  │     ├── Player
  │     │     ├── LocalPlayer
  │     │     └── MultiplayerLocalPlayer
  │     ├── Monster
  │     ├── Animal
  │     └── WaterAnimal
  ├── ItemEntity
  ├── PrimedTnt
  ├── FallingTile
  ├── Boat
  ├── Minecart
  ├── Arrow
  └── ExperienceOrb

Entity Class

Abstract base class for all entities. Header: Minecraft.World/Entity.h
Inherits: enable_shared_from_this<Entity>

Constants

static const short TOTAL_AIR_SUPPLY = 300;  // 20 * 15 seconds

Core Members

int entityId;                    // Unique entity ID

Level *level;                    // World containing this entity

// Position
double x, y, z;                  // Current position
double xo, yo, zo;               // Previous tick position
double xd, yd, zd;               // Velocity/motion

// Rotation
float yRot, xRot;                // Current rotation (yaw, pitch)
float yRotO, xRotO;              // Previous tick rotation

// Bounding box
AABB *bb;                        // Collision bounding box
float bbWidth, bbHeight;         // Bounding box dimensions

// State flags
bool onGround;                   // Is entity on ground?
bool removed;                    // Is entity marked for removal?
bool inChunk;                    // Is entity in a chunk?
bool noPhysics;                  // Disable physics?

// Collision state
bool horizontalCollision;        // Hit wall this tick?
bool verticalCollision;          // Hit floor/ceiling this tick?
bool collision;                  // Any collision this tick?

// Movement
float walkDist, walkDistO;       // Walk animation distance
float fallDistance;              // Distance fallen

// Fire & damage
int flameTime;                   // Ticks on fire
int invulnerableTime;            // Ticks of invulnerability

// Riding
shared_ptr<Entity> riding;       // Entity being ridden
weak_ptr<Entity> rider;          // Entity riding this

// Misc
int tickCount;                   // Age in ticks
bool slide;                      // Slippery movement?
float heightOffset;              // Render Y offset

Constructor

Entity(Level* level, bool useSmallId)

constructor

Creates a new entity in the specified world.Parameters:

level - World to spawn in
useSmallId - Use optimized small ID (for most entities)

Note: Abstract class - cannot be instantiated directly

Position & Movement

setPos(double x, double y, double z)

void

Sets entity position and updates bounding box.Parameters:

x, y, z - New world coordinates

moveTo(double x, double y, double z, float yRot, float xRot)

void

Moves entity to position with rotation.Parameters:

yRot - Yaw rotation in degrees
xRot - Pitch rotation in degrees

absMoveTo(double x, double y, double z, float yRot, float xRot)

void

Absolute move without interpolation (teleport).

move(double xa, double ya, double za, bool noEntityCubes)

void

Moves entity with collision detection.Parameters:

xa, ya, za - Movement delta
noEntityCubes - Ignore entity collisions

Updates xd, yd, zd based on actual movement after collisions.

turn(float xo, float yo)

void

Rotates entity.Parameters:

xo - Pitch change
yo - Yaw change

setRot(float yRot, float xRot)

void

Sets rotation directly.

moveRelative(float xa, float za, float speed)

void

Applies relative movement based on current rotation.Parameters:

xa, za - Strafe and forward movement
speed - Movement multiplier

Use case: Player WASD movement, mob pathfinding

Collision & Physics

isFree(double xa, double ya, double za)

bool

Checks if entity can move to an offset position.Returns: true if no collision at new position

getCollideBox()

AABB*

Gets the collision bounding box.Returns: Pointer to AABB or null if non-solid

getCollideAgainstBox(shared_ptr<Entity> entity)

AABB*

Gets the box other entities collide against.Returns: AABB for entity-entity collisions

push(shared_ptr<Entity> e)

void

Handles entity-to-entity collision.

push(double xa, double ya, double za)

void

Applies push/knockback force.

Size & Bounding Box

setSize(float w, float h)

void

Sets entity dimensions.Parameters:

w - Width (X and Z)
h - Height (Y)

Note: Protected - called in entity constructors

getHeadHeight()

float

Gets eye/camera height.Returns: Height offset from feet to eyes

Distance Calculations

distanceTo(shared_ptr<Entity> e)

float

Calculates distance to another entity.Returns: Distance in blocks

distanceToSqr(shared_ptr<Entity> e)

double

Calculates squared distance (faster - no sqrt).

distanceTo(double x2, double y2, double z2)

double

Calculates distance to coordinates.

distanceToSqr(double x2, double y2, double z2)

double

Calculates squared distance to coordinates.

Tick & Update

tick()

void

Updates entity for one game tick (1/20 second).Override: Implement entity-specific behavior

baseTick()

void

Performs common tick operations.

Updates position history
Handles fire damage
Updates air supply
Manages invulnerability frames

Damage & Death

hurt(DamageSource* source, int damage)

bool

Applies damage to entity.Parameters:

source - Source of damage (entity, lava, fall, etc.)
damage - Damage amount

Returns: true if damage was applied

burn(int dmg)

void

Applies fire damage.Parameters:

dmg - Damage amount

Note: Protected - called by fire tick logic

setOnFire(int numberOfSeconds)

void

Sets entity on fire.Parameters:

numberOfSeconds - Duration in seconds

clearFire()

void

Extinguishes fire.

isFireImmune()

bool

Checks if entity is immune to fire.

Water & Breathing

isInWater()

bool

Checks if entity is in water.

isInLava()

bool

Checks if entity is in lava.

isInWaterOrRain()

bool

Checks if entity is wet.

updateInWaterState()

bool

Updates water collision state.Returns: true if in water

getAirSupply()

int

Gets remaining air ticks while underwater.Returns: Air ticks (max 300)

setAirSupply(int supply)

void

Sets air supply.

Fall Damage

causeFallDamage(float distance)

void

Applies fall damage based on distance.Parameters:

distance - Fall distance in blocks

Note: Protected - override for custom fall damage

Interaction

interact(shared_ptr<Player> player)

bool

Handles player right-click interaction.Returns: true if interaction was handledExamples: Riding minecart, breeding animal, trading with villager

playerTouch(shared_ptr<Player> player)

void

Handles player collision/touch.Examples: Item pickup, damage from cactus/mob

isPickable()

bool

Checks if entity can be clicked/targeted.

isPushable()

bool

Checks if entity can be pushed by other entities.

isShootable()

bool

Checks if entity can be hit by projectiles.

Riding & Vehicles

ride(shared_ptr<Entity> e)

void

Mounts another entity.Parameters:

e - Entity to ride (minecart, pig, boat, etc.)

rideTick()

void

Updates riding state each tick.

positionRider()

void

Positions the rider entity.Override: Customize rider position on vehicle

getRidingHeight()

double

Gets height offset for rider.

getRideHeight()

double

Gets mount point height.

isRiding()

bool

Checks if entity is riding something.

Rendering & Display

shouldRender(Vec3* c)

bool

Checks if entity should be rendered from camera position.Parameters:

c - Camera position

shouldRenderAtSqrDistance(double distance)

double

Checks if entity should render at distance.

getBrightness(float a)

float

Gets lighting brightness for rendering.Parameters:

a - Partial tick (0.0-1.0)

Returns: Brightness multiplier (0.0-1.0)

getLightColor(float a)

int

Gets packed light color value.Returns: Combined sky and block light

Flags & State

isOnFire()

bool

Checks if entity is burning.

isSneaking()

bool

Checks if entity is sneaking.

setSneaking(bool value)

void

Sets sneaking state.

isSprinting()

bool

Checks if entity is sprinting.

setSprinting(bool value)

void

Sets sprinting state.

isInvisible()

bool

Checks if entity is invisible.

setInvisible(bool value)

void

Sets invisibility.

Lifecycle

remove()

void

Marks entity for removal from world.

isAlive()

bool

Checks if entity is alive (not removed).

Data Persistence

save(CompoundTag* entityTag)

bool

Saves entity to NBT tag.Returns: true if saved successfully

load(CompoundTag* tag)

void

Loads entity from NBT tag.

readAdditionalSaveData(CompoundTag* tag)

void

Reads entity-specific NBT data.Note: Abstract - must be implemented

addAdditonalSaveData(CompoundTag* tag)

void

Writes entity-specific NBT data.Note: Abstract - must be implemented

Type System

GetType()

eINSTANCEOF

Gets entity type enum.Returns: Type constant (eTYPE_PLAYER, eTYPE_MOB, etc.)Use case: Fast type checking without dynamic_cast

Entity Damage Types

enum EEntityDamageType {
    eEntityDamageType_Entity,      // Attacked by entity
    eEntityDamageType_Fall,        // Fall damage
    eEntityDamageType_Fire,        // Fire/lava surface
    eEntityDamageType_Lava,        // Inside lava
    eEntityDamageType_Water,       // Drowning
    eEntityDamageType_Suffocate,   // Inside block
    eEntityDamageType_OutOfWorld,  // Void damage
    eEntityDamageType_Cactus       // Cactus contact
};

Example Usage

Creating & Spawning

// Spawn an item at position
auto itemEntity = make_shared<ItemEntity>(level, x, y, z, itemStack);
level->addEntity(itemEntity);

// Spawn with velocity
itemEntity->xd = 0.1;
itemEntity->yd = 0.2;
itemEntity->zd = 0.0;

Movement & Collision

// Move entity with collision
entity->move(entity->xd, entity->yd, entity->zd);

if (entity->horizontalCollision) {
    // Hit a wall
    entity->xd = 0;
    entity->zd = 0;
}

if (entity->onGround) {
    // On ground - apply friction
    entity->xd *= 0.91;
    entity->zd *= 0.91;
}

Proximity Checks

// Find nearest player
shared_ptr<Player> nearest = nullptr;
double minDist = 16.0 * 16.0;  // Squared distance

for (auto& player : level->players) {
    double dist = entity->distanceToSqr(player);
    if (dist < minDist) {
        minDist = dist;
        nearest = player;
    }
}

Type Checking

// Fast type check
if (entity->GetType() == eTYPE_PLAYER) {
    auto player = dynamic_pointer_cast<Player>(entity);
    // Do player-specific logic
}

// Alternative with dynamic_cast
auto player = dynamic_pointer_cast<Player>(entity);
if (player) {
    // It's a player
}

Client

World

Rendering

Networking

Overview

Class Hierarchy

Entity Class

Constants

Core Members

Constructor

Position & Movement

Collision & Physics

Size & Bounding Box

Distance Calculations

Tick & Update

Damage & Death

Water & Breathing

Fall Damage

Interaction

Riding & Vehicles

Rendering & Display

Flags & State

Lifecycle

Data Persistence

Type System

Entity Damage Types

Example Usage

Creating & Spawning

Movement & Collision

Proximity Checks

Type Checking

See Also

Build docs developers (and LLMs) love

Client

World

Rendering

Networking

​Overview

​Class Hierarchy

​Entity Class

​Constants

​Core Members

​Constructor

​Position & Movement

​Collision & Physics

​Size & Bounding Box

​Distance Calculations

​Tick & Update

​Damage & Death

​Water & Breathing

​Fall Damage

​Interaction

​Riding & Vehicles

​Rendering & Display

​Flags & State

​Lifecycle

​Data Persistence

​Type System

​Entity Damage Types

​Example Usage

​Creating & Spawning

​Movement & Collision

​Proximity Checks

​Type Checking

​See Also

Build docs developers (and LLMs) love

Overview

Class Hierarchy

Entity Class

Constants

Core Members

Constructor

Position & Movement

Collision & Physics

Size & Bounding Box

Distance Calculations

Tick & Update

Damage & Death

Water & Breathing

Fall Damage

Interaction

Riding & Vehicles

Rendering & Display

Flags & State

Lifecycle

Data Persistence

Type System

Entity Damage Types

Example Usage

Creating & Spawning

Movement & Collision

Proximity Checks

Type Checking

See Also