✅SuperiorIslandNPC [1.21-26.2]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

SuperiorIslandNPC adds one interactive NPC to every SuperiorSkyblock2 island.

The NPC is created automatically when an island is created and can execute any configured player or console command when right-clicked. Island owners manage everything through a polished GUI, including its location, form, name, glow, click effect and player-looking behavior.

Every island keeps its own settings. The exact placement and all customization choices remain saved across restarts, chunk unloads and periods where the NPC is disabled.

The plugin uses normal Minecraft entities and a lightweight TextDisplay. Citizens, DecentHolograms and PlaceholderAPI are not required.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Automatic island NPCs
  Creates one NPC when a new SuperiorSkyblock2 island is created.
  
• Complete GUI manager
  A polished 45-slot menu lets island owners control the NPC without remembering commands.
  
• 36 NPC forms
  Choose villagers, golems, illagers, monsters, animals and more from a paginated 54-slot gallery.
  
• Exact saved placement
  Move the NPC to a precise location and facing direction on the island. Re-enabling it restores that same position.
  
• Persistent island settings
  Location, enabled state, form, custom name, name visibility, glow, click effect and player-looking choice are saved separately for every island.
  
• Two-line floating title
  Displays ✦ ISLAND ASSISTANT ✦ with Right-click to open underneath.
  
• Easy chat renaming
  Click the sign inside the GUI and type the new first line directly in chat. No rename command is required.
  
• Look at nearby players
  Each island can decide whether its NPC turns toward the nearest player.
  
• Glowing outline
  Enable or disable the Minecraft glowing effect independently for every island.
  
• Particles and sounds
  Includes No Effect, Emerald Sparkle, Magic, Flame, Soul Fire, Ender and Aqua presets.
  
• Configurable right-click action
  Run any player or console command and use the <player> placeholder.
  
• No forced chunk loading
  NPC chunks unload normally, so the plugin does not keep island farms, redstone or spawners active.
  
• Automatic recovery and duplicate cleanup
  Missing NPCs are restored when their saved chunk loads, while orphaned, travelling and duplicate copies are removed.
  
• Teleport ghost protection
  Prevents the NPC and its floating title from briefly appearing at /spawn after a player teleports.
  
• Safe island cleanup
  The NPC and its saved island data are removed when the SuperiorSkyblock2 island is disbanded.
  
• Administrator tools
  Inspect, repair or remove plugin NPCs without touching normal Minecraft mobs.
  
• Fully configurable
  Messages, GUI items, menu positions, forms, sounds, particles, title settings and interaction behavior can all be changed.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Open the Island NPC Manager with:

You can also use:

The manager contains:

• Island NPC Overview — view status, form, name, effect and exact saved location.
• Enable / Disable — remove or restore the NPC without losing its settings.
• Look at Players — toggle player tracking for this island.
• Move NPC Here — save the player's current island position and facing direction.
• Reset to Island Spawn — restore the NPC placement to the island spawn.
• Click Effect — choose a saved particle-and-sound preset.
• Glowing — toggle the NPC's glowing outline.
• NPC Form — open the 54-slot form gallery.
• NPC Name — left-click to rename in chat or right-click to show or hide both title lines.

Only the island owner can manage the NPC by default. This can be changed in config.yml.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. A new island is created through SuperiorSkyblock2.
2. SuperiorIslandNPC finds the island spawn and creates one stationary assistant.
3. The owner opens /is npc to customize it.
4. The selected settings and exact location are written to npcs.yml.
5. Right-clicking the NPC executes the command configured in config.yml.
6. When the chunk unloads, the NPC unloads normally and returns with the same UUID and settings.

The NPC has no AI and cannot walk away. Its saved location is always treated as the authoritative position.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Minecraft: 1.21, 26.1 and 26.2
• Native API version: 1.21
• Java: 21
• Server software: Paper
• Required dependency: SuperiorSkyblock2
• Tested SuperiorSkyblock2 version: 2026.1

Not required: Citizens, PlaceholderAPI, ProtocolLib or a hologram plugin.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Stop the Minecraft server completely.
2. Install SuperiorSkyblock2.
3. Place SuperiorIslandNPC.jar inside the server's plugins directory.
4. Make sure no older SuperiorIslandNPC JAR remains in that directory.
5. Start the server.
6. Edit plugins/SuperiorIslandNPC/config.yml.
7. Configure the command that should run when an NPC is right-clicked.
8. Run /is npc reload or restart the server.
9. Create or visit an island and open /is npc.

Existing npcs.yml data can be kept when updating. Do not delete it unless you intentionally want to remove every saved island NPC setting.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Legacy aliases /islandnpc location and /islandnpc delete are also supported.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━









━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• One active NPC and one title display are stored for each enabled island.
• The NPC and title use persistent Minecraft entity data and survive normal chunk unloads and server restarts.
• The plugin does not force-load NPC chunks.
• Periodic checks only inspect already loaded saved NPC chunks.
• Entity creation, scanning, removal and repair are executed on the main server thread.
• Disabled islands retain their placement and customization without keeping an entity loaded.
• Duplicate and orphaned plugin entities are cleaned automatically.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
The plugin creates:

• config.yml — GUI, NPC forms, title, effects, interaction and message settings.
• npcs.yml — saved island preferences, exact placements and active entity UUIDs.

It is recommended to stop the server before manually editing npcs.yml.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• Use a tested Paper version: 1.21, 26.1 or 26.2, with Java 21.
• Make sure SuperiorSkyblock2 loads successfully before testing the NPC plugin.
• Keep only one SuperiorIslandNPC JAR inside the plugins directory.
• Use a complete server restart after installing or replacing the JAR.
• Run /islandnpc admin info to inspect the current island record.
• Run /islandnpc admin repair to recreate an enabled NPC from its saved data.
• Include the Paper version, SuperiorSkyblock2 version, SuperiorIslandNPC version and complete console error when requesting support.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Questions, bug reports and feature suggestions are welcome in the resource discussion thread or on the support Discord.

Please include your server version, plugin version, SuperiorSkyblock2 version, configuration without private information and the complete relevant console error when reporting a problem.