Unified Entity System Foundation

[FirebrickRed]

Summary

Create the foundation for a unified NPC/Monster/Entity system that replaces the current split between NPCs and Monsters. All entities (townspeople, merchants, monsters, beasts) use the same underlying system with behavior determined by YAML configuration.

Phase: 1 - Foundation
Systems: Entity System, Core

Prerequisites

None - this is a foundational issue

Goals

• Create DndEntity data model (replaces separate NpcData/MonsterData)
• Flexible HP system: hit_dice (roll for variance) OR hit_points (fixed)
• Random name generation from YAML name pools
• Name patterns (prefix + name + suffix combinations)
• Create DndEntityInstance class (template vs spawned entity)
• Create EntityLoader with recursive DMContent/Entities/ scanning
• Support single-entity AND multi-entity YAML files (groups)
• Resource pack model references

HP System Logic

int hp;
if (entity.getHitDice() != null) {
    hp = DiceRoller.roll(entity.getHitDice());  // Roll for variance
} else if (entity.getHitPoints() != null) {
    hp = entity.getHitPoints();  // Use fixed value
} else {
    hp = 10;  // Default fallback
}

Random Name System

id: kobold
name: "Kobold"  # Default fallback

random_names:
  - "Skrix"
  - "Yeek"
  - "Meepo"
  
# Name reuse: If spawning more entities than names available, cycle through pool

File Structure

DMContent/
└── Entities/           (DM can organize however they want)
    ├── town/
    │   ├── blacksmith.yml
    │   └── guard.yml
    ├── wilderness/
    │   └── wolf.yml
    └── my_custom_campaign/
        └── boss.yml

Technical Details

• Recursive loading: Scan ALL subdirectories under DMContent/Entities/
• ID-based lookup: Entity id field is what matters, not filename
• Template pattern: YAML = template, spawned entity = instance
• DM flexibility: No forced folder structure

Example YAML

id: town_guard
name: "Town Guard"
hit_dice: "2d8+4"  # Variance on spawn
random_names: ["Marcus", "Leon", "Thaddeus"]

armor_class: 16
speed: 30
# ... rest of D&D stats

Next Steps

After completing this issue, tackle:

• Entity Spawning Commands (DM-Only) #73: Entity Spawning Commands (uses this foundation)
• Entity Stat Block Display #74: Stat Block Display (displays DndEntity data)

Related Issues

• Entity Spawning Commands (DM-Only) #73 - Entity Spawning Commands
• Entity Stat Block Display #74 - Entity Stat Block Display
• Native Villager Trade GUI Shop System #75 - Shop System (uses DndEntity model)

[FirebrickRed]

✅ Completed in commit f895a2b

All foundation components implemented:

• ✅ DndEntity data model with flexible HP system
• ✅ DndEntityInstance (template vs spawned entity pattern)
• ✅ EntityLoader with recursive DMContent/Entities/ scanning
• ✅ HP rolling system (hit_dice → hit_points → default)
• ✅ Random name generation from YAML pools
• ✅ DndAttack model extracted for reusability
• ✅ Resource pack model support

Example entities created:

• wolf.yml (simple beast with hit_dice)
• town_guard.yml (humanoid with random names)

This foundation is now being used by Issue #73 (Entity Spawning Commands).