### 🧍 NPC Management
* **Creation & Removal**: Easily create new NPCs at your location and remove existing ones.
* **Selection**: Select the nearest NPC to manage its properties.
* **Persistence**: All NPCs are automatically saved and loaded, ensuring they remain across server restarts.
* **Basic Control**: Teleport, clone (future feature), spawn, despawn (future feature).
* **Display Name**: Customize NPC names, including support for color codes.
* **Entity Type**: Change the visual type of the NPC (e.g., player, zombie, villager - *currently defaults to Player*).
* **Ownership**: Assign ownership to NPCs (future feature).
### 🎭 Appearance
* **Mojang Skin System**: Apply any player's skin to an NPC by fetching it directly from Mojang's API.
* `/npc skin <player>`: Fetches and applies a player's skin.
* `/npc skin update`: Refreshes the selected NPC's skin.
* `/npc skin clear`: Resets the NPC to a default skin.
* **Custom Names**: Set display names with color codes.
* **Equipment GUI**: Open a graphical interface to equip NPCs with armor and items.
### 🧠 Behavior & AI
* **Look at Player**: Toggle whether an NPC automatically turns its head to look at nearby players.
* **Pathfinding Patrols**:
* `/npc path add`: Add your current location as a waypoint for the selected NPC.
* `/npc path start`: Command the NPC to begin patrolling its defined path.
* `/npc path stop`: Halt the NPC's current patrol.
* `/npc path clear`: Remove all waypoints from the NPC's path.
* **Player Following**:
* `/npc follow <player>`: Make the NPC follow a specific player.
* `/npc follow off`: Stop the NPC from following.
* **Pose Control**:
* `/npc sit`: Make the selected NPC sit down.
* `/npc stand`: Make the selected NPC stand up.
* **Physics Control**:
* `/npc gravity`: Enable gravity for the NPC.
* `/npc fly`: Disable gravity, allowing the NPC to float or fly.
* **Automatic Respawn**: NPCs automatically respawn in the world upon server startup.
### 💬 Interaction
* **Dialogue System**:
* `/npc text add <message>`: Add lines of dialogue that the NPC will say when interacted with.
* `/npc text list`: View all dialogue lines for the selected NPC.
* `/npc text clear`: Remove all dialogue lines.
* `/npc text remove <index>`: Remove a specific dialogue line by its number.
* **Command Execution**:
* `/npc cmdadd <command>`: Add commands that the server will execute when a player interacts with the NPC. Use `%player%` as a placeholder for the interacting player's name.
* `/npc cmdremove <index>`: Remove a specific command.
* `/npc cmdclear`: Clear all commands.
* **Interaction Triggers**:
* `/npc trigger <type>`: Define how players activate NPC interactions.
* `right_click`: Interact by right-clicking the NPC.
* `left_click`: Interact by left-clicking (attacking) the NPC.
* `proximity`: Interact when a player comes within a certain range of the NPC.
### ⚔️ Combat (Optional)
* **Player Guarding**:
* `/npc guard <player>`: Command the NPC to guard a specific player.
* `/npc guard off`: Disable guarding.
* **Range Setting**:
* `/npc range <blocks>`: Set the follow or attack range for the NPC.
### 🧰 Utility
* **List NPCs**:
* `/npc list [page]`: Display a paginated list of all active NPCs, showing their IDs and names.
* **NPC Information**:
* `/npc info`: Show detailed information about the currently selected NPC.
* **Save Data**:
* `/npc save`: Force the plugin to save all NPC and skin data immediately.
* **Reload Plugin**:
* `/npc reload`: Reload the plugin's configuration, NPC data, and skin cache.
* **Debug Mode**:
* `/npc debug`: Toggle debug messages (future feature).
## Core Systems
### Skin System
* Fetches player skins directly from Mojang's API using usernames.
* Extracts skin data (value and signature) and applies it to the NPC's appearance.
* Caches skin data locally in `skins.yml` to minimize API requests and improve performance.
* All skin fetching operations are performed asynchronously to prevent server lag.
* Supports updating or clearing NPC skins via commands.
### Persistence
* **NPC Data**: All NPC configurations (UUID, name, location, skin data, entity type, path points, equipment, behavior settings, interaction details) are stored persistently in `npcs.yml`.
* **Skin Cache**: Downloaded skin data is cached in `skins.yml`.
* **Automatic Loading**: All NPCs are automatically loaded and spawned when the plugin starts.
### Command Handling
* A robust command system with clear subcommands for all NPC management tasks.
* Includes full tab completion for ease of use.
* Comprehensive error handling for invalid commands or missing selections.
### Interaction Triggers
* Supports various methods for players to interact with NPCs: right-click, left-click, and proximity detection.
* When triggered, NPCs can display dialogue and execute server commands.
### Pathfinding & Movement
* NPCs can be configured with patrol paths consisting of multiple waypoints.
* NPCs can be commanded to follow specific players.
### Equipment Management
* A dedicated graphical user interface (GUI) allows server admins to visually equip NPCs with armor and items.
## Commands
All commands start with `/npc` or `/advnpcs`.
* `/npc create <name>`: Creates an NPC named `<name>` at your current location.
* `/npc remove`: Removes the currently selected NPC.
* `/npc select`: Selects the nearest NPC to your position.
* `/npc skin <player_name>`: Sets the selected NPC's skin to that of `<player_name>`.
* `/npc skin update`: Refreshes the selected NPC's skin from the cached username.
* `/npc skin clear`: Resets the selected NPC to a default skin.
* `/npc name <new_name>`: Changes the selected NPC's display name. Supports color codes.
* `/npc equip`: Opens an inventory GUI to equip the selected NPC.
* `/npc look`: Toggles whether the selected NPC looks at nearby players.
* `/npc path add`: Adds your current location as a waypoint to the selected NPC's patrol path.
* `/npc path start`: Starts the selected NPC patrolling its path.
* `/npc path stop`: Stops the selected NPC's patrol.
* `/npc path clear`: Clears all waypoints from the selected NPC's path.
* `/npc follow <player_name>`: Makes the selected NPC follow `<player_name>`.
* `/npc follow off`: Stops the selected NPC from following.
* `/npc sit`: Makes the selected NPC sit.
* `/npc stand`: Makes the selected NPC stand.
* `/npc gravity`: Enables gravity for the selected NPC.
* `/npc fly`: Disables gravity for the selected NPC, allowing it to float.
* `/npc text add <message>`: Adds a dialogue line to the selected NPC.
* `/npc text list`: Lists all dialogue lines for the selected NPC.
* `/npc text clear`: Clears all dialogue lines for the selected NPC.
* `/npc text remove <index>`: Removes the dialogue line at the specified `<index>`.
* `/npc cmdadd <command>`: Adds a server command to be executed when the selected NPC is interacted with. Use `%player%` as a placeholder for the interacting player's name.
* `/npc cmdremove <index>`: Removes the command at the specified `<index>`.
* `/npc cmdclear`: Clears all commands for the selected NPC.
* `/npc trigger <type>`: Sets the interaction trigger for the selected NPC (`right_click`, `left_click`, `proximity`).
* `/npc guard <player_name>`: Makes the selected NPC guard `<player_name>`.
* `/npc guard off`: Stops the selected NPC from guarding.
* `/npc range <blocks>`: Sets the follow/attack range for the selected NPC.
* `/npc list [page]`: Displays a paginated list of all created NPCs.
* `/npc info`: Shows detailed information about the currently selected NPC.
* `/npc save`: Forces all NPC and skin data to be saved to disk.
* `/npc reload`: Reloads the plugin's configuration, NPC data, and skin cache.
* `/npc debug`: Toggles debug messages (currently not implemented).
## Permissions
All permissions start with `advnpcs.`.
* `advnpcs.admin`: Grants access to all AdvNPCs commands (default: op).
* `advnpcs.create`: Allows players to create new NPCs (default: op).
* `advnpcs.remove`: Allows players to remove NPCs (default: op).
* `advnpcs.skin`: Allows players to manage NPC skins (default: op).
* `advnpcs.behavior`: Allows players to manage NPC behavior (default: op).
* `advnpcs.dialogue`: Allows players to manage NPC dialogue and commands (default: op).
## Data Storage
* `plugins/AdvNPCs/npcs.yml`: Stores all persistent NPC data, including their UUIDs, names, locations, skin data, entity types, path points, equipment, and behavior/interaction settings.
* `plugins/AdvNPCs/skins.yml`: Stores cached Mojang skin data (username, UUID, value, signature) to reduce API calls.
## Installation
1. Download the `AdvNPCs-1.0.0.jar` file.
2. Place the `AdvNPCs-1.0.0.jar` file into the `plugins` folder of your Spigot/Paper Minecraft server.
3. Start or restart your Minecraft server.
4. The plugin will create its data folders and configuration files (`npcs.yml`, `skins.yml`) in `plugins/AdvNPCs/`.
## Usage Examples
* `/npc create Steve`: Creates an NPC named "Steve" at your current location.
* `/npc select`: Selects the nearest NPC.
* `/npc skin Notch`: Sets the selected NPC's skin to Notch's skin.
* `/npc text add Hello, traveler!`: Adds a dialogue line to the selected NPC.
* `/npc path add`: Adds your current location to the selected NPC's path.
* `/npc path start`: Makes the selected NPC start patrolling its path.
* `/npc follow Player123`: Makes the selected NPC follow the player "Player123".
