78 lines
4.9 KiB
Markdown
78 lines
4.9 KiB
Markdown
# 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/`](https://github.com/Pumpkin-MC/Pumpkin/tree/master/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`](https://github.com/Pumpkin-MC/Pumpkin/blob/master/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.
|