NPC-Lib Documentation

The library provides platform-agnostic events to react to NPC interactions.

Important Implementation Details:

• Registration: You must register listeners with the event manager provided by the platform, not the underlying server's event system (e.g., Bukkit).
• Threading: Event listeners can be called from any thread. There is no guarantee of being on the main server thread. If you need to access platform-specific APIs (like Bukkit), you must manually schedule that code to run on the main server thread.
• Type Safety: Because events are not type-safe regarding the player, you must explicitly cast the player object to your desired type (e.g., Player) within your handler.

public final class AttackEventConsumer implements NpcEventConsumer<AttackNpcEvent> {
  @Override
  public void handle(AttackNpcEvent event) {
    // event.player() returns Object; cast it to your specific Player type
    Player goodPlayer = (Player) event.player(); 
  }
}

To spawn an NPC, use the newNpcBuilder() method provided by your platform instance. The builder allows you to configure the entity's identity, position, and profile.

Required Configuration:

• .position(): The location where the NPC should be spawned. This must be set before spawning.

Optional Configuration:

• .entityId(): The unique ID for the entity. If omitted, a random integer is generated.
• .profile(): Sets the NPC's skin/profile. If an unresolved profile is used, the method returns a future that completes when the profile is resolved.
• .npcSettings(): Configures tracking rules (which players see the NPC) and profile resolvers.
• .flag(): Sets specific flags on the NPC (see NPC Flags).

Building the NPC: There are two ways to finalize the build:

1. build(): Returns a raw NPC instance. You are responsible for all subsequent actions and tracking.
2. buildAndTrack(): Builds the NPC and registers it with the platform's NPC tracker. This enables the action controller and packet listeners to function for this NPC.

platform.newNpcBuilder()
  .entityId(12345)
  .position(location)
  .profile(profile)
  .buildAndTrack();

NPC-Lib is modular. You should primarily use npc-lib-api to keep your code platform-agnostic. Choose a platform-specific implementation module based on your server software (Bukkit, Minestom, or Fabric).

Available Modules

Maven Configuration

<dependency>
  <groupId>io.github.juliarn</groupId>
  <artifactId>(module name from the list above)</artifactId>
  <version>(latest version)</version>
  <scope>compile</scope>
</dependency>

Gradle Configuration

implementation("io.github.juliarn", "(module name from the list above)", "(latest version)")

<!-- Example Maven dependency for the API -->
<dependency>
  <groupId>io.github.juliarn</groupId>
  <artifactId>npc-lib-api</artifactId>
  <version>3.0.0-beta9</version>
  <scope>compile</scope>
</dependency>

To spawn an NPC, use the Platform instance to create a new NPC builder. You must specify a position and a profile. Using buildAndTrack() will spawn the NPC and automatically handle visibility for players within the configured range (default is 50 blocks if the action controller is enabled). Use npc.unlink() to completely remove the NPC when it is no longer needed.

public final class TestPlugin extends JavaPlugin {
  private final Platform<World, Player, ItemStack, Plugin> platform = BukkitPlatform
    .bukkitNpcPlatformBuilder()
    .extension(this)
    .actionController(builder -> {}) // enable action controller
    .build();

  public void spawnNpc(Location location) {
    this.platform.newNpcBuilder()
      .position(BukkitPlatformUtil.positionFromBukkitLegacy(location))
      .profile(Profile.unresolved("derklaro"))
      .thenAccept(builder -> {
        var npc = builder.buildAndTrack();
        // continue using the npc...
        npc.unlink(); // remove the npc
      });
  }
}

The platform builder allows you to customize how the library interacts with your server software. While many options have defaults, some are critical.

Key Configuration Methods

BukkitPlatform.bukkitNpcPlatformBuilder()
  .debug()
  .extension(myPlugin)
  .logger(myLogger)
  .actionController(builder -> builder
    .flag(NpcActionController.SPAWN_DISTANCE, 5))
  .build();