Entity Architecture & Hierarchy

Entities in Minecraft represent all dynamic, living and non-living objects that exist within a world—ranging from dropped item stacks and arrows to zombies, villagers, and players.

In Pumpkin, entity systems are implemented in crates/pumpkin/src/entity/. The architecture leverages object-oriented trait composition on top of concurrency-safe, cache-friendly data structures.

---

Entity Trait Hierarchy

Pumpkin structures entities into an inheritance hierarchy using Rust traits:

Trait / Type	Parent Trait	Core Capabilities & State
Entity	(None / Base Struct)	Entity ID, UUID, atomic position and velocity vectors, bounding box, pose
EntityBase	(Root Trait)	Dynamic runtime downcasting (get_living_entity, etc.), world tick, damage, teleportation
LivingEntity	EntityBase	Health, absorption, potion effects, equipment slots, attribute containers
Mob	LivingEntity	AI goal selector, navigation, pathfinding, target tracking, death loot
Player	LivingEntity	Network client session, inventory, crafting screens, hunger, advancements

1. Entity (Base Struct)

Contains fundamental physics, geometry, and spatial state common to all entities:

• entity_id: Fast 32-bit unique integer identifier used across network packets.
• uuid: 128-bit persistent UUID.
• position & velocity: Thread-safe vectors (AtomicCell<Vector3<f64>>) allowing concurrent reading without lock contention.
• bounding_box: 3D axis-aligned bounding box (AABB) used for collision resolution and raycast targeting.
• pose: Current pose (Standing, Crouching, Sleeping, FallFlying, etc.).

2. EntityBase (Foundation Trait)

The root dynamic trait implemented by every entity in the server:

• Supports safe runtime downcasting via helper methods (get_living_entity(), get_mob(), get_player()).
• Provides hooks for world interaction: tick(), damage(), teleport(), on_lightning_strike(), is_immune_to_explosion().

3. LivingEntity (Biological Trait)

Extends EntityBase for entities with health, combat, and animation states:

• Manages health bars, absorption, invulnerability ticks, and fall damage.
• Tracks active potion effects (crates/pumpkin/src/entity/effect/).
• Handles equipment slots (MainHand, OffHand, Helmet, Chestplate, Leggings, Boots).
• Encapsulates attribute containers (max health, movement speed, knockback resistance).

4. Mob (AI Trait)

Extends LivingEntity for computer-controlled mobs:

• Manages AI goal selectors (attacking, wandering, fleeing, looking around).
• Controls navigation and pathfinding over blocks.
• Spawns configured loot tables upon death.

5. Player (Human Client)

Represents a human player connected through a game client:

• Links to network socket handlers (JavaClient or BedrockClient).
• Manages container screen handlers, ender chests, player inventory, and crafting.
• Tracks hunger, saturation, exhaustion, experience levels, and advancement criteria.

---

Physics & Movement Simulation

On every server tick, Pumpkin simulates entity physics through a deterministic sequence:

1. Apply Velocity & Gravity: Evaluates current velocity and adds downward gravitational acceleration unless has_gravity() is false or the entity is flying.
2. Resolve Block Collisions: Checks the entity's 3D axis-aligned bounding box (bounding_box) against solid block voxels in the surrounding chunk; velocity along colliding axes is dampened or zeroed.
3. Apply Fluid Drag & Buoyancy: Evaluates whether the entity intersects water or lava fluids, applying drag coefficients and buoyant upward force.
4. Synchronize & Broadcast: Persists the updated coordinates in atomic position cells and broadcasts relative delta movement packets to observing players.
5. Void Death: Non-player entities falling below $Y = -128$ are automatically despawned.

---

Combat & Damage System

Damage calculations reside in crates/pumpkin/src/entity/combat.rs:

1. Damage Types: Damage is categorized by DamageType (e.g., GENERIC, PLAYER_ATTACK, FALL, FIRE, MAGIC, EXPLOSION, LIGHTNING_BOLT).
2. Damage Scaling:
   • Armor defense points mitigate incoming physical damage according to the vanilla formula: $$\text{damage} = \text{damage} \times \left(1 - \frac{\min(20, \max(\text{armor} / 5, \text{armor} - \frac{\text{damage}}{2 + \text{toughness} / 4}))}{25}\right)$$
   • Resistance status effects and Protection enchantments apply secondary reductions.
3. Knockback: When damage is dealt, a directional impulse vector is added to the victim's velocity, modulated by their knockback resistance attribute.
4. Hurt Animations: Triggers hurt sounds and broadcasts red-tint flash metadata to all observers.