112 lines
5.4 KiB
Markdown
112 lines
5.4 KiB
Markdown
# Mob AI & Goal System
|
|
|
|
Pumpkin implements a modular, priority-driven Artificial Intelligence (AI) goal system for computer-controlled mobs, located in [`crates/pumpkin/src/entity/ai/`](https://github.com/Pumpkin-MC/Pumpkin/tree/master/crates/pumpkin/src/entity/ai) and [`crates/pumpkin/src/entity/mob/`](https://github.com/Pumpkin-MC/Pumpkin/tree/master/crates/pumpkin/src/entity/mob).
|
|
|
|
---
|
|
|
|
## The Goal System Architecture
|
|
|
|
Mob behaviors are decomposed into independent modular tasks called **Goals**. Each mob possesses a **GoalSelector** that maintains an ordered collection of goals evaluated on every server tick.
|
|
|
|
### Goal Priority Hierarchy
|
|
|
|
Goals are assigned an integer priority (where lower numbers represent higher precedence). During each tick, higher-priority actions preempt lower-priority background tasks:
|
|
|
|
| Priority | Goal Type | Evaluation Condition | Behavior |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **1 (Highest)** | `SwimGoal` | Entity is submerged in water | Jump repeatedly to swim to the water surface and avoid drowning. |
|
|
| **2** | `MeleeAttackGoal` | Valid hostile target in sight/range | Navigate towards target entity and execute melee attacks. |
|
|
| **3** | `WanderAroundGoal` | No active combat target | Pick a random nearby navigable voxel and walk to it. |
|
|
| **4 (Lowest)** | `LookAtEntityGoal` | Player or mob within observation radius | Rotate head and body pitch/yaw towards the target entity. |
|
|
|
|
### Execution Flow
|
|
|
|
1. **Evaluation**: On every game tick, `GoalSelector::tick()` iterates through registered goals in order of priority.
|
|
2. **Activation**: If an inactive goal satisfies `can_start()`, it is activated via `start()`.
|
|
3. **Execution**: Active goals run their per-tick logic in `tick()`.
|
|
4. **Preemption & Termination**: If `should_continue()` returns `false`, or a mutually exclusive goal with higher priority activates, `stop()` is called and the goal resets.
|
|
|
|
### The `Goal` Lifecycle
|
|
|
|
Every AI behavior implements the `Goal` trait:
|
|
|
|
```rust
|
|
pub trait Goal: Send + Sync {
|
|
/// Evaluates preconditions to determine if this goal can activate.
|
|
fn can_start(&self) -> bool;
|
|
|
|
/// Called once when the goal transitions from inactive to active.
|
|
fn start(&mut self) {}
|
|
|
|
/// Evaluates whether the goal should continue executing on subsequent ticks.
|
|
fn should_continue(&self) -> bool {
|
|
self.can_start()
|
|
}
|
|
|
|
/// Executes the continuous behavior on each server tick.
|
|
fn tick(&mut self) {}
|
|
|
|
/// Called when the goal completes, fails, or is preempted by a higher priority goal.
|
|
fn stop(&mut self) {}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Standard Built-in Goals
|
|
|
|
Pumpkin provides standard vanilla AI behaviors in `crates/pumpkin/src/entity/ai/`:
|
|
|
|
| Goal | Description | Target Mobs |
|
|
| :--- | :--- | :--- |
|
|
| **`SwimGoal`** | Jumps repeatedly while submerged in water to prevent drowning. | Almost all land mobs |
|
|
| **`MeleeAttackGoal`** | Navigates towards an attack target and executes a strike when within reach. | Zombies, Spiders, Iron Golems |
|
|
| **`RangedAttackGoal`** | Stays at range and shoots projectiles (arrows, snowballs). | Skeletons, Pillagers, Blazes |
|
|
| **`FleeSunGoal`** | Seeks shade or water during daytime to prevent combustion. | Zombies, Skeletons |
|
|
| **`PanicGoal`** | Sprints in random directions when taking damage. | Cows, Pigs, Sheep, Chickens |
|
|
| **`WanderAroundGoal`** | Selects random accessible coordinates nearby when idle. | Passive & neutral mobs |
|
|
| **`LookAtEntityGoal`** | Rotates head to face nearby players within sensory range. | Villagers, Mobs |
|
|
|
|
---
|
|
|
|
## Navigation & Pathfinding
|
|
|
|
Mobs navigate the block world using Pumpkin's 3D grid pathfinder:
|
|
|
|
1. **Path Calculation**: Resolves a path from the mob's origin to target coordinates using an A* algorithm optimized for Minecraft block geometries.
|
|
2. **Obstacle Avoidance**:
|
|
- Avoids hazardous blocks (lava, fire, sweet berry bushes).
|
|
- Prevents walking off ledges higher than the mob's fall threshold.
|
|
- Computes jumping steps over 1-block obstacles.
|
|
3. **Waypoint Steering**: The navigation engine updates the mob's velocity vectors per tick to smoothly guide the entity along waypoints.
|
|
|
|
---
|
|
|
|
## Entity Attributes System
|
|
|
|
Mob capabilities and stats are governed by the **Attributes** system in [`crates/pumpkin/src/entity/attributes.rs`](https://github.com/Pumpkin-MC/Pumpkin/blob/master/crates/pumpkin/src/entity/attributes.rs):
|
|
|
|
```rust
|
|
use pumpkin_data::entity::attribute::EntityAttribute;
|
|
|
|
// Common vanilla attributes
|
|
EntityAttribute::GENERIC_MAX_HEALTH; // Base hit points (e.g. 20.0 for Zombies)
|
|
EntityAttribute::GENERIC_MOVEMENT_SPEED; // Base walking velocity (e.g. 0.23)
|
|
EntityAttribute::GENERIC_ATTACK_DAMAGE; // Melee attack damage (e.g. 3.0)
|
|
EntityAttribute::GENERIC_FOLLOW_RANGE; // Sensory detection range in blocks (e.g. 35.0)
|
|
EntityAttribute::GENERIC_KNOCKBACK_RESISTANCE; // Resistance against knockback (0.0 to 1.0)
|
|
```
|
|
|
|
### Modifiers
|
|
Attributes support dynamic modifiers with additive or multiplicative calculations (e.g., speed bonuses from Swiftness potions or armor attribute boosts).
|
|
|
|
---
|
|
|
|
## Ageable & Passive Entities
|
|
|
|
Passive animals (cows, sheep, pigs) implement the `Ageable` trait:
|
|
|
|
- **Baby State**: Renders with smaller collision boxes and oversized heads.
|
|
- **Growing Age**: A negative tick timer counting upward to `0`. When it reaches `0`, the entity matures into an adult.
|
|
- **Breeding Cooldown**: Positive tick timer tracking cooldowns between successful matings.
|