Sculk Companion: AI-Powered Server Helper

Sculk Companion integrates Large Language Models directly into your server chat, creating an interactive companion that remembers players, tracks relationships, assigns quests, handles sacrifices, and runs in-game commands. The plugin is powered by any OpenAI-compatible LLM API like DeepSeek, OpenAI, Ollama, LM Studio, or vLLM.

---

Key Features

AI Chat with Persistent Memory

• Talk to Sculk via server chat using the sculk keyword or commands (/ask <question> or /sculk ask <question>).
• Toggle Chat Mode (/sculk toggle) to route all your messages straight to Sculk.
• Per-player persistent conversation history stored locally as JSON profiles.
• Free-form personality and lore injection via config.yml and lore.txt.

Dynamic Relationship & Affection System

• Tracks a player affection score ranging from -100 (Hostile) to +100 (Devoted).
• The AI dynamically updates this score based on player interactions.
• High affection levels unlock helpful actions like healing, item gifting, and buffs.
• Low affection makes Sculk hostile, cold, or sarcastic.
• Positive relationship changes have a 2-minute cooldown to prevent spam, which is bypassed for high-value items.

Interactive Sacrifice System

• Hold any item in your hand and ask Sculk to accept it as a sacrifice.
• The AI evaluates the item's worth and modifies your relationship score accordingly.
• Transaction Safety: Items are only consumed if the relationship update succeeds. If the cooldown blocks it, your item stays safe in your hand.

In-Game Questing

• Sculk can assign you KILL_MOB or COLLECT_ITEM quests.
• Progress is tracked automatically for objectives like killing zombies or collecting copper.
• Displays real-time progress via action-bar notifications with custom particle and sound feedback.

Landmarks & Teleportation

• Save coordinates under a custom name during conversation (e.g., "my base", "portal").
• Ask Sculk to teleport you back to any of your saved landmarks.

---

AI Tool Permissions & System (18 Actions)

Sculk has access to standard in-game commands and tools it can execute during chat loops:

Tool Name	Affection Required	Description
heal_player	30+	Fully restores health and feeds the player
gift_item_to_player	20+	Drops requested items at the player's feet
apply_potion_effect	10+	Gives potion buffs (Speed, Night Vision, etc.)
play_sound	0+	Triggers a Bukkit sound locally
spawn_particles	0+	Spawns cosmetic particles
execute_console_command	0+	Runs whitelisted commands
save_landmark	0+	Saves current location under a name
teleport_to_landmark	0+	Teleports player to a saved location
start_quest	0+	Assigns a new mob-hunting or collecting quest
check_quest_status	Any	Checks/refreshes active quest progress
complete_quest	Any	Clears active quest after completion
modify_relationship	Any	Adjusts affection score
sacrifice_held_item	Any	Consumes hand item to gain affection
remember_player_fact	Any	Remembers details (long-term memory)
kick_player	0+	Kicks player (requires sculk.sudo permission)
teleport_player	0+	Teleports players (requires sculk.sudo.teleport permission)
get_server_status	0+	Displays TPS and RAM (requires sculk.sudo.monitor permission)
broadcast_announcement	0+	Broadcasts announcements (requires sculk.sudo.broadcast permission)

---

Configuration & Setup

Requirements

• Server Engine: Paper, Spigot, or compatible forks (e.g., Purpur).
• Minecraft Version: 1.20+ (Targeted for 1.20 - 1.26.x+)
• Java Version: 25+
• LLM API Provider: Any OpenAI-compatible API (local or cloud-hosted).

Installation Steps

1. Place the Sculk-1.0.0.jar into your server's plugins/ directory.
2. Start the server to generate default configurations.
3. Open plugins/sculk/config.yml and insert your API URL and Token:

   api:
     url: "https://api.deepseek.com/chat/completions" # Your endpoint
     token: "your-api-key-here"                       # Your API key
     model: "deepseek-v4-flash"                       # LLM Model

4. Customize plugins/sculk/lore.txt with your own server rules, backstory, and guidelines.
5. Reload config using /sculk reload or restart your server.

---

Permissions

• sculk.use (Default: true) - Allows players to talk to Sculk.
• sculk.admin (Default: op) - Access to config reloading.
• sculk.sudo (Default: op) - Allows AI to kick players on request.
• sculk.sudo.teleport (Default: op) - Allows AI to teleport players.
• sculk.sudo.monitor (Default: op) - Allows AI to access server status metrics.
• sculk.sudo.broadcast (Default: op) - Allows AI to send announcements.