CraftHub
Sculk Companion

Sculk Companion

An AI companion plugin that interacts with players and executes in-game commands asynchronously using any OpenAI-compatible API.

95 downloads 0 followers

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](https://api.deepseek.com/chat/completions)" # Your endpoint
     token: "your-api-key-here"                       # Your API key
     model: "deepseek-v4-flash"                       # LLM Model
  1. Customize plugins/sculk/lore.txt with your own server rules, backstory, and guidelines.
  2. 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.

No gallery available for this project.

Version Minecraft Loader Download

Sculk Companion 1.1.0

1.1.0

26.1, 26.1.1, 26.1.2, 26.2
bukkit, paper, purpur, spigot
Download

Sculk Companion 1.0.0

1.0.0

26.1, 26.1.1, 26.1.2, 26.2
bukkit, paper, purpur, spigot
Download