Home

Welcome to the Sculk Companion Wiki! 🟣

Sculk Companion is a lightweight, highly optimized Paper/Spigot plugin that introduces an AI-powered assistant directly into your server chat. Using any OpenAI-compatible LLM endpoint (DeepSeek, OpenAI, Ollama, LM Studio, etc.), the plugin allows players to form relationships with a mystical entity, complete quests, offer sacrifices, and let the AI interact with the Minecraft world.

---

📖 Wiki Sections

To help you get the most out of Sculk Companion, the documentation has been organized into the following guides:

1. Commands & Permissions

A complete list of commands (like /ask and /sculk toggle) and the permission nodes required to use them.

2. Configuration & Custom Lore

An in-depth explanation of config.yml settings, connecting to LLMs, and custom personality shaping using lore.txt.

3. Relationship & Sacrifices

Learn how the AI evaluates player interactions, handles affection scores (-100 to +100), and consumes items through the transaction-safe sacrifice engine.

4. Quests & Landmarks

Details on how the AI assigns mob-hunting or item collection quests, and how players can save coordinates to ask Sculk to teleport them later.

5. AI Tools & Security

A technical reference of the 18 in-game tools the AI can invoke, permission levels required for them, and command whitelisting security.

---

⚙️ Quick Start Checklist

1. Download the latest release JAR.
2. Place the JAR into your server's plugins/ directory and start it once.
3. Open plugins/sculk/config.yml and add your API URL and Token.
4. Set up your custom backstory in plugins/sculk/lore.txt.
5. Run /sculk reload and you are ready to query!