Skip to content

Configuration and Lore

Jump to bottom
emkacz edited this page Jun 21, 2026 · 1 revision

Configuration & Custom Lore ⚙️

Sculk Companion is highly customizable, letting you define how it connects to your AI provider, how it formats chat outputs, and its baseline personality and server lore context.

📄 config.yml Guide

The configuration file is located at plugins/sculk/config.yml. Below is an explanation of each section:

1. API Connection (api)

This section handles connection details to your LLM API.

  • url: The endpoint for Chat Completions. Must be OpenAI-compatible (e.g. https://api.deepseek.com/chat/completions or local server endpoints like http://localhost:11434/v1/chat/completions).
  • token: The API authorization key (e.g. Bearer sk-xxx). Leave empty if using local APIs without authentication (like Ollama or LM Studio).
  • model: The model identifier (e.g. deepseek-v4-flash, gpt-4o, llama3).
  • timeout-seconds: Connection timeout limit. If using a slow local LLM, increase this to 60 or more to prevent timeouts.
  • chat-history-size: The number of previous message pairs (User + AI) remembered in conversation. Higher values increase AI context awareness but consume more API tokens.
  • cooldown-seconds: Cooldown time between player queries to prevent chat spam.

2. Chat Formatting (formatting)

Supports Kyori MiniMessage styles (colors, tags).

  • prefix: The prefix displayed before Sculk’s response (e.g. <dark_purple>[Sculk]</dark_purple>).
  • thinking-message: The obfuscated pulsing text shown on the player's action bar while waiting for the AI response.
  • error-message: The error feedback shown to players if the request fails or times out.

3. Sensory Feedback (feedback)

  • play-sound: Plays a sculk clicking sound when Sculk is queried.
  • spawn-particles: Spawns sculk charges around the player.

4. Allowed Commands (actions)

  • enable-actions: Enables or disables AI tool executions.
  • allowed-commands: A list of console command prefixes the AI is allowed to run via the execute_console_command tool. Use %player% as a placeholder for the querying player's username.

    [!WARNING] These are prefix matches! A prefix like "give" allows the AI to run any give command. Keep these as specific as possible (e.g., "give %player% cookie").

📜 Custom Lore (lore.txt)

The lore.txt file lets you inject server rules, world descriptions, and character backstories into Sculk’s memory.

How it works:

  1. When a query is made, the contents of lore.txt are loaded from disk.
  2. The plugin appends this text to the baseline system-prompt defined in config.yml.
  3. This compiled prompt is sent as the system role instructions in the API payload.

Sample lore.txt contents:

Sculk Helper Lore & Knowledge Base:
- You are a mystical, quiet helper manifested from the Sculk.
- You reside inside a Minecraft server and speak from the shadows of the deep dark.
- The server rules: No griefing, be respectful, and keep exploration fun.
- Keep your replies brief, and under 2 sentences.

Clone this wiki locally