MemoryVillager

MemoryVillager is a lightweight, persistent villager memory system for Paper servers.
It makes villagers remember each player’s trade history, applies loyalty-based discounts, and adds immersive dialogue behavior without breaking vanilla progression.
--------------------------------------------------
WHAT IT DOES
--------------------------------------------------
- Tracks villager-to-player trade history persistently.
- Gives discount tiers based on loyalty (number of trades).
- Shows discount + price preview during trading.
- Preserves vanilla villager progression behavior.
- Keeps memory data across restarts using SQLite.
- Supports villager identity persistence using PDC.
- Handles zombie villager cure transitions by preserving identity.
- Ignores NPC-backed villagers (such as Citizens-style villager NPCs) so fake/quest NPCs are not affected.
- Includes configurable dialogue and message visibility options.
--------------------------------------------------
CORE FEATURES
--------------------------------------------------
- Loyalty Discount System
- Trade count per player per villager
- Configurable trades-per-tier and discount-per-tier
- Configurable maximum discount cap
- Non-compounding discount logic (prevents price drift over repeated updates)
- Price preview support (base -> discounted)
- Persistent Villager Identity
- Each real villager gets a stable unique ID via PersistentDataContainer
- Memory survives rename/restart/reload cases
- ID transferred on zombie-villager cure flow
- Dialogue + Messaging
- Optional chat dialogue
- Optional action-bar status
- Configurable cooldown to avoid spam
- Rate-limited warning logs for cleaner console output
- Data Storage
- SQLite database backend
- Auto-save scheduler
- Safe load/save/close flow
- Suitable for survival/economy servers with persistent worlds
--------------------------------------------------
NPC SAFETY (IMPORTANT)
--------------------------------------------------
This plugin distinguishes real villagers from common villager NPC systems:
- Filters entities with common NPC metadata/tag markers
- Skips Citizens-like NPC villagers
- Prevents NPC shopkeepers/quest NPCs from being renamed or memory-tracked by this plugin
--------------------------------------------------
COMPATIBILITY
--------------------------------------------------
- Platform: Paper
- Native Major MC Version: 1.21
- Supported Runtime Range: 1.21.x through 1.26.1+ (with explicit runtime compatibility handling for 1.26.1+)
- Java: 21+
--------------------------------------------------
COMMANDS
--------------------------------------------------
- /villager info
Shows memory stats for the villager you are looking at.
- /villager name <name>
Sets a custom name for the villager you are looking at.
- /villager reset
Resets memory for the villager you are looking at (admin).
- /villager reload
Reloads dialogues/config-related runtime dialogue data (admin).
--------------------------------------------------
PERMISSIONS
--------------------------------------------------
- memoryvillager.use
Default: true
Access to regular villager commands.
- memoryvillager.admin
Default: op
Access to reset/reload admin commands.
--------------------------------------------------
INSTALLATION
--------------------------------------------------
1. Stop your server.
2. Place the plugin jar into your plugins folder.
3. Start the server once to generate default files.
4. Edit config.yml and dialogues.yml as needed.
5. Use /villager reload (or restart) after changes.
--------------------------------------------------
CONFIG HIGHLIGHTS
--------------------------------------------------
discount-system:
- enabled
- max-discount
- trades-per-tier
- discount-per-tier
dialogue:
- enabled
- cooldown-seconds
- show-in-chat
- show-action-bar
moral-system:
- enabled
- warn-threshold
- block-threshold
storage:
- auto-save-interval
- database-name
messages:
- prefix and user-facing text keys
--------------------------------------------------
WHY THIS PLUGIN IS SAFE FOR ECONOMY SERVERS
--------------------------------------------------
- Discount application avoids compounding errors.
- Trade overcounting mitigation applied.
- Preserves recipe progression metadata.
- Log spam reduced with warning rate limits.
- NPC filtering avoids accidental edits to non-vanilla villager systems.
--------------------------------------------------
NOTES
--------------------------------------------------
- Designed to feel vanilla-friendly while adding progression and personality.
- Best used on survival/economy/community SMP servers.
- If your NPC plugin uses custom metadata/tag markers not currently recognized, they can be added easily in an update.