VillageAI

[3.2.0] - 2026-04-28 — Debugging & Permission System Improvements

🐛 Bug Fixes

High Priority

• Poor debug output — ChunkCoord and VillageId displayed unreadable default toString() output. Now override toString() for clear logging and debugging.
• Incomplete permission system — Missing permission nodes for players to use economy, trade, and quest features. Added villageai.trade and villageai.quest permissions.
• Unsafe null handling in VillageCommand — getUnlockedUpgrades() could return null, causing NPE. Added proper null checks in info display.

Medium Priority

• Configuration documentation unclear — Time unit specifications (milliseconds vs game ticks) not consistently documented. Added explicit comments for all time-based configuration.
• Inconsistent state management — RAID state not properly synchronized during raid events. State transitions now properly managed.

🚀 Improvements

Debugging & Logging

• ChunkCoord.toString(): Now displays ChunkCoord{world=<uuid>, x=<x>, z=<z>} for clear chunk identification in logs
• VillageId.toString(): Returns formatted <world>-<x>-<y>-<z> for easy village identification
• Better error diagnosis: Improved readability for spatialIndex tracking and village location debugging

Permission System

• New Permissions:
  • villageai.trade — Trade with village NPCs (default: true for players)
  • villageai.quest — Accept and complete village quests (default: true for players)
• Existing Permissions Unchanged:
  • villageai.admin — Full admin access (default: op)
  • villageai.economy — View economy information (default: true)
  • villageai.upgrade — Contribute to village upgrades (default: true)

Code Quality

• Null safety improvements: Added defensive checks in command handlers
• Better code documentation: Configuration comments clarify time units throughout
• Consistent logging patterns: toString() overrides prevent confusing object reference logs

🔧 Technical Details

Thread Safety Review

• interactCooldowns: Confirmed main-thread-only access (safe with ConcurrentHashMap)
• Village state transitions: Properly synchronized during night/defense/raid state changes
• Quest completion: CopyOnWriteArrayList prevents ConcurrentModificationException during concurrent operations

Configuration Examples

Time Units in config.yml:

reputation:
  decay_interval: 30000          # milliseconds (30 seconds)
  
village:
  tick_interval: 40              # game ticks (50ms per tick = 2 seconds total)

night:
  enabled: true
  # Note: No world_blacklist yet (planned for v3.3.0)

Permission Usage:

permissions:
  villageai.trade: true           # Allow trading
  villageai.quest: true           # Allow quests
  villageai.upgrade: true         # Allow upgrades
  villageai.economy: true         # View economy
  villageai.admin: false          # Admin only

📊 Performance Impact

• No performance regression
• toString() methods called only during logging, minimal overhead
• Permission checks use existing Bukkit API (standard performance)

🔮 Roadmap for v3.3.0

• Auto-generation of missing economy_config.yml
• Full economy data persistence (VillageEconomy snapshot serialization)
• World blacklist for night mode (disable night in specific worlds)
• Configuration validation utility for startup checks
• Extended quest types (Harvest, Combat, Breeding)

---