Examples

📚 Examples

This page shows how to use the NPC API in real scenarios. These examples are focused, easy to follow, and use common flags, settings, and event handlers.

---

🔌 Basic Bukkit Platform

Creates a simple Bukkit platform, with default values.

val platform = BukkitPlatform.bukkitNpcPlatformBuilder()
  .extension(this)
  .actionController {  }
  .build()

---

🎭 Basic NPC

Creates a simple NPC and tracks it.

platform.newNPCBuilder()
  .position(player.location)
  .profile(Profile.unresolved("Test"))
  .thenAccept {
    val npc = it.buildAndTrack()
  }

🧍 Profile Per Viewer

Use NPCProfileResolver.ofViewer() to show different skins to each player.

platform.newNPCBuilder()
  .position(player.location)
  .npcSettings {
    it.profileResolver(NPCProfileResolver.ofViewer())
  }
  .profile(Profile.unresolved("Test"))
  .thenAccept {
    val npc = it.buildAndTrack()
  }

👀 Custom Tracking Rule

Only show NPC to players in survival mode:

val trackingRule = NPCTrackingRule<Player> { npc, player ->
    player.gameMode == GameMode.SURVIVAL
}

Use it in your builder:

platform.newNPCBuilder()
  .position(player.location)
  .npcSettings {
    it.trackingRule(trackingRule)
  }
  .profile(Profile.unresolved("Test"))
  .thenAccept {
    val npc = it.buildAndTrack()
  }

⚔️ Event Handling

React to player interaction:

platform.newNPCBuilder()
  .position(player.location)
  .eventHandler {
    bind<InteractNPCEvent> {
      val player = bukkitPlayer()
      player.sendMessage("[${bukkitNPC().profile.name}] Hello, ${player.name}!")
    }

    bind<ShowNPCEvent.Post> {
      bukkitNPC().changeMetadata(skinLayerMetaFactory(), true).schedule(bukkitPlayer())
      bukkitNPC().changeItem(ItemSlot.MAIN_HAND, ItemStack(Material.GOLDEN_SWORD)).schedule(bukkitPlayer())
    }
  }
  .profile(Profile.unresolved("Test"))
  .thenAccept {
    val npc = it.buildAndTrack()
  }

📋 Hologram-ready NPC

Creates a NPC with hidden name tag.

platform.newNPCBuilder()
  .position(player.location)
  .profile(Profile.unresolved("Test"))
  .flag(NPC.HIDE_NAME_TAG, true)
  .thenAccept {
    val npc = it.buildAndTrack()
  }

📋 Copycat NPC

Creates a NPC that imitates the viewer.

platform.newNPCBuilder()
  .position(player.location)
  .profile(Profile.unresolved("Test"))
  .flags(
    NPC.LOOK_AT_PLAYER to true,
    NPC.HIT_WHEN_PLAYER_HITS to true,
    NPC.SNEAK_WHEN_PLAYER_SNEAKS to true
  )
  .thenAccept {
    val npc = it.buildAndTrack()
  }