AI Tools and Security

AI Tools & Security 🛡️

To let Sculk interact directly with Minecraft, the plugin uses a Recursive Tool Execution Loop. This allows the AI to run server-side actions, read outputs, and make subsequent decisions all in a single query turn.

---

🔁 The Tool Loop

1. Player Message: The player sends a query (e.g. "I'm hurt and hungry, help me!").
2. AI Choice: The LLM receives the prompt and decides to execute a function: heal_player.
3. Execution: The server intercepts this call, checks permissions, executes the heal action, and converts the result to JSON (e.g. {"success": true, "message": "Player has been fully healed."}).
4. Recursion: The JSON result is sent back to the AI. The AI reviews the result and can either call another tool or generate its final response to the player (e.g. "The sculk energy has mended your wounds.").
5. The loop supports up to 5 tool iterations per chat query.

---

🧰 Full Tools Reference

Below is the list of all 18 actions the AI can call. Some tools require specific player permissions or affection levels.

Helper Tools

• heal_player (Requires 30+ Affection)
  • Restores player health and hunger to maximum.
• apply_potion_effect (Requires 10+ Affection)
  • Applies an active potion effect (Speed, Invisibility, Night Vision, etc.) for a specified duration and level.
• gift_item_to_player (Requires 20+ Affection)
  • Drops a specified Material item stack at the player's feet.
• play_sound (Requires 0+ Affection)
  • Triggers a Bukkit sound locally.
• spawn_particles (Requires 0+ Affection)
  • Spawns cosmetic particles (Sculk Soul, Heart, Dragon Breath) around the player.

Administrative Tools

• kick_player (Requires target to have sculk.sudo permission, 0+ Affection)
  • Kicks a specified player from the server.
• teleport_player (Requires target to have sculk.sudo.teleport permission, 0+ Affection)
  • Teleports a player to another player.
• get_server_status (Requires querying player to have sculk.sudo.monitor permission, 0+ Affection)
  • Returns TPS, RAM usage, loaded chunks, and total entity count.
• broadcast_announcement (Requires querying player to have sculk.sudo.broadcast permission, 0+ Affection)
  • Broadcasts a server-wide announcement prefix in red chat.

RPG Core Tools

• start_quest (Requires 0+ Affection)
  • Assigns a mob-hunting or item collection quest.
• check_quest_status
  • Checks quest goals. For items, scans inventory and deducts them if complete.
• complete_quest
  • Clears the completed quest from the player profile.
• save_landmark (Requires 0+ Affection)
  • Saves player coordinates under a specific name.
• teleport_to_landmark (Requires 0+ Affection)
  • Teleports the player to a saved location name.
• modify_relationship
  • Manually updates player affection.
• sacrifice_held_item
  • Deducts hand item and boosts relationship (if off cooldown).
• remember_player_fact
  • Stores a summary detail in player's long-term memory.

---

🛡️ Security Gates

To prevent the AI from executing unauthorized commands or abusing powers, three layers of security are enforced:

1. Permission Gating

For advanced tools (like kick_player, teleport_player, get_server_status, broadcast_announcement), the plugin verifies permissions:

• The player must have the matching permission node (e.g. sculk.sudo).
• If they do not, the tool will not be registered/visible to the AI during that query, or the execution will be blocked.

2. Command Whitelisting

The execute_console_command tool is strictly sandboxed. The AI can only execute commands that match the prefixes defined in the actions.allowed-commands list in config.yml.

• Example Whitelist:

  allowed-commands:
    - "summon firework_rocket"
    - "give %player% cookie"

• If the AI tries to run op %player% or stop, the server blocks the action, logs a warning in the console, and returns an error payload to the LLM.

3. Affection Verification

Even if a player has permission to request an action, the AI checks the player's affection level. If the player is hostile or neutral, the AI will refuse the request inside the conversation loop.