🦆 DuckySkript

DuckySkript is a powerful, lightweight Spigot/Paper Minecraft plugin that allows administrators to create custom scripts via simple YAML files and execute dynamic commands when players interact with Citizens NPCs or run them manually.

With DuckySkript, you can configure conditional command execution based on player permissions, execute commands as the console, player, or temporary OP, and personalize player interactions effortlessly.

Important: Citizens plugin required!

✨ Features

Citizens Integration: Execute script sequences when players right-click a Citizens NPC.
YAML Scripting: Simple, readable, and highly customizable script creation using standard YAML format.
Conditional Execution: Evaluate script steps in top-to-bottom order based on permission nodes. Supports default fallback blocks.
Flexible Execution Contexts:
- Run commands as the Console sender.
- Run commands as the Player.
- Run commands as Operator (OP) temporarily, bypassing permission restrictions safely.
Placeholder Support: Dynamically inject the interacting player's name using %player%.
Command Fallback & Aliases: Fully backwards compatible with existing setups (supports /duckyskript, /ds, /ducky, and /pn).
Permission Fallback: Seamless support for both legacy parlanpccmd.xxx and new duckyskript.xxx permission structures.
Multi-language Support: English and Hebrew localization files out of the box.

🚀 Installation & Setup

Make sure you have Citizens installed on your server (optional but highly recommended for NPC functionality).
Download DuckySkript.jar and place it in your server's plugins folder.
Restart or reload the server to generate configuration files.
Customize settings in plugins/DuckySkript/config.yml and add scripts in the plugins/DuckySkript/scripts/ directory.

⚙️ Commands & Permissions

Commands

/duckyskript help - Displays the help menu.
/duckyskript reload - Reloads all configuration files and scripts.
/duckyskript run <script> [player] - Manually triggers a script sequence for a player.

Note: You can use the /ds, /ducky, or /pn aliases instead of /duckyskript.

Permissions

duckyskript.use - Required to use the help command. (Default: true)
duckyskript.admin - Required to reload the plugin. (Default: op)
duckyskript.run - Required to manually run a script. (Default: op)

Note: Legacy permissions starting with parlanpccmd. are automatically recognized as fallbacks.

📜 Scripting Guide

All scripts are located in plugins/DuckySkript/scripts/. Each YAML script file can contain different command sequences matched against player permissions. The plugin parses these permissions from top to bottom, executing the first matching block.

Execution Contexts

Console Command (Default): Runs the command from the console console.
```
- "give %player% diamond 5"
```
Player Command: Runs the command as the interacting player.
```
- "say Hello!":
    config:
      asPlayer: true
```
OP Command: Runs the command as the player, temporarily granting them OP status to execute it (ideal for commands requiring admin permissions).
```
- "gamemode creative":
    config:
      asPlayer: true
      asOP: true
```

Example Script (`scripts/example.yml`)

# Example Script for DuckySkript
scripts:
  # Check if player has VIP permission
  duckyskript.vip:
    - "say I am a VIP!":
        config:
           asPlayer: true
           asOP: false
    - "give %player% diamond 5"
    - "broadcast %player% just talked to the VIP NPC!"
    
  # Check if player has member permission
  duckyskript.member:
    - "say Hello, I am a member!":
        config:
           asPlayer: true
    - "give %player% iron_ingot 10"
    
  # Default fallback if no permission nodes match
  default:
    - "say I don't have any special permissions yet.":
        config:
           asPlayer: true

👥 Assigning Scripts to NPCs

To bind a script to a Citizens NPC, select the NPC and apply the metadata using Citizens commands:

/npc select
/npc metadata --set duckyskript-script <script_name>

(Replace <script_name> with the name of your script file, excluding the .yml extension)

For backward compatibility, the plugin also checks the parlanpc-script metadata key.

🌍 Localization

DuckySkript supports Hebrew and English out of the box. You can configure your language in config.yml:

# Language to use for messages
# Supported: en, he
language: en

Customize all messages in messages_en.yml or messages_he.yml.