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
sculkkeyword 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.ymlandlore.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
- Place the
Sculk-1.0.0.jarinto your server'splugins/directory. - Start the server to generate default configurations.
- Open
plugins/sculk/config.ymland insert your API URL and Token:
api:
url: "[https://api.deepseek.com/chat/completions](https://api.deepseek.com/chat/completions)" # Your endpoint
token: "your-api-key-here" # Your API key
model: "deepseek-v4-flash" # LLM Model
- Customize
plugins/sculk/lore.txtwith your own server rules, backstory, and guidelines. - Reload config using
/sculk reloador 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.
