MinecraftLLMNotifications

Paper-compatible Minecraft plugin that generates customized join/quit messages with an LLM.

Features

• AI-generated messages for:
  • first-time join
  • returning join
  • player quit
• Multiple prompts per event (randomly selected each time)
• Placeholder support so prompts include player/server context
• Configurable providers:
  • Ollama (provider.type: OLLAMA)
  • OpenAI-compatible chat endpoint (provider.type: OPENAI)
  • Anthropic Messages API (provider.type: ANTHROPIC)
• Async network calls (does not block the main server thread)
• Startup LLM connectivity test on plugin enable (logs success/failure to terminal)
• Fallback messages if API calls fail
• Player memory feature for customizing messages with additional player information
  • stored in per-player YAML files
  • loaded into memory on join and unloaded on leave

Compatibility

• Built against Paper API 1.21.11
• Uses Bukkit/Paper event APIs, so it should also run on compatible Spigot/Purpur forks
• Java 21 required (matches current Paper API target)

Build

./gradlew build

Output jar:

• build/libs/MinecraftLLMNotifications-1.0.0.jar

Test

Run tests:

./gradlew test

Run tests with coverage report:

./gradlew test jacocoTestReport

Coverage report:

• build/reports/jacoco/test/html/index.html

Install

1. Build the jar.
2. Put the jar into your server plugins/ directory.
3. Start server once to generate plugins/MinecraftLLMNotifications/config.yml.
4. Edit config and set provider credentials/model.
5. Run /llmnotifyreload or restart.

Config Highlights

• provider.type: OLLAMA, OPENAI, or ANTHROPIC
• provider.ollama.base-url and provider.ollama.model
• provider.openai.base-url, provider.openai.api-key, provider.openai.model
• provider.anthropic.base-url, provider.anthropic.api-key, provider.anthropic.model
• prompts.first-join, prompts.join, prompts.quit (lists; random choice)
• messages.fallback.* fallback pools
• messages.player-memory.enabled: true or false to enable player memory
• messages.player-memory.prefix: prefix to use when adding player memory to prompts

Placeholders

Use these in prompts and fallback messages:

• @player
• @display_name
• @uuid
• @world
• @x, @y, @z
• @health
• @food
• @level
• @gamemode
• @online_count
• @is_op
• @first_join
• @last_played
• @playtime_hours
• @player_memory - includes player memory information when enabled

Also supported: {{player}} style placeholder syntax.

Tips for Better Prompts

• Keep requested output short for chat readability.
• Ask for line limits explicitly, for example: Create exactly 4 lines...
• Mention desired tone and safety constraints.

Command

• /llmnotifyreload - reloads config (permission: llmnotify.reload)
• /llmnotifymemory - manage player memory (permission: llmnotify.memory)
  • works for online and offline players by name
  • /llmnotifymemory add <player> <item> - Add an item to a player's memory
  • /llmnotifymemory list <player> - List a player's memory items as a numbered list (1-indexed)
  • /llmnotifymemory remove <player> <index> - Remove a specific item by its 1-indexed list number
  • /llmnotifymemory clear <player> - Remove all items for a specific player
  • /llmnotifymemory clearall - Remove all items for all players