百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
N

npc-lib

> 编程语言
开源

用于 1.8-1.21 服务器的异步、高性能 Minecraft NPC 库。

376 stars0 点赞2 次浏览
访问官网GitHub

工具介绍

用于 1.8-1.21 服务器的异步、高性能 Minecraft NPC 库。

Features

  • Bukkit & Forks (including Folia) supported via ProtocolLib or PacketEvents
  • Full Minestom & Fabric support (latest version only)
  • Skin (Static and Dynamic loading)
  • Attributes (Status, Pose, Skin Layers)
  • Equipment (Main & Off-Hand, Armor)
  • Interaction (Interact & Attack)
  • Action Controller (Automatic Looking at Player, Player Imitation & Spawning etc.)
  • LabyMod Extension (Sending Emotes & Sprays)
  • ...

There are some images down below showcasing the use and features of this library.

Installation

All modules are available in maven central, a precompiled version of the fabric module can be downloaded from modrinth:

Module artifact name Module description
npc-lib-api General NPC-Lib API without platform specific class usage. This module should be used when the underlying implementation does not matter.
npc-lib-common Abstract implementation of the api module. This module should be used when a new platform implementation is made.
npc-lib-bukkit Platform specific implementation for Bukkit. This module implements the complete API (and common) to support Bukkit (and forks).
npc-lib-minestom Platform specific implementation for Minestom. This module implements the complete API (and common) to support Minestom (and forks).
npc-lib-fabric Platform specific implementation for Fabric. This module implements the complete API (and common) to support Fabric and must be installed as a mod on the server.
npc-lib-labymod This module contains helper methods for accessing LabyMod NPC features (such as emotes and stickers). See the LabyMod documentation for more information.

How to include a module

Maven:

xml

  io.github.juliarn
  (module name from the list above)
  (latest version)
  compile

Gradle:

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

Repositories

Depending on your setup you might need to add the following repositories as well to download all the transitive dependencies coming from the modules:

  • https://repository.derklaro.dev/releases/ (You can also use https://jitpack.io instead, used e.g. for ProtocolLib).
  • https://repo.codemc.io/repository/maven-releases/ (For PacketEvents)

Shading

This library is specifically made in a way that it can be shaded into your plugin jar. Below is a list of packages that are used by this library and that you probably want to relocate to prevent dependency issues with other plugins including the same libraries. You can use the gradle or maven shade plugin to achieve this:

  • net.kyori
  • io.leangen.geantyref
  • io.github.retrooper
  • com.github.retrooper
  • com.github.juliarn.npclib

Example Usage

Platform specific (server software specific) code is only needed to obtain a platform instance. The platform instance can then be used to create NPCs, without knowing which underlying platform is actually used.

Usually all classes you need provide a builder and shouldn't be instantiated directly. To obtain a platform builder use the following:

On Bukkit

java
BukkitPlatform.bukkitNpcPlatformBuilder()

On Minestom

java
MinestomPlatform.minestomNpcPlatformBuilder()

On Fabric

java
FabricPlatform.fabricNpcPlatformBuilder()

Configuring the Platform

In all further examples bukkit will be used as a reference, but the api is the same on all other platforms:

…

The action controller

The standard action controller controls stuff like automatic npc spawning, player imitation and more. The action controller implementations are controlled by flags which can be dynamically adjusted as needed. Custom flags can also be added to control extra stuff that isn't directly available using the default action controller. The default action controller flags are the following (all located as constants in the NpcActionController class):

Flag Name Default Value Description
AUTO_SYNC_POSITION_ON_SPAWN true Controls if the npc head rotation should automatically be set when the npc is spawned for a player. This only does something when the npc is set up to look at the player.
SPAWN_DISTANCE 50 The distance (in blocks) in which the npc will be shown to a player.
TAB_REMOVAL_TICKS 30 The ticks before the player removal packet is sent when spawning an npc. This can be lowered on newer versions (1.19.3+) as the player isn't added to the tablist at all due to new protocol options.
IMITATE_DISTANCE 20 The distance (in blocks) in which the npc will start imitating the player actions.

Spawning a NPC

The platform object constructed in the last step contains a method to construct a NPC builder: newNpcBuilder. This builder can be used to customize and spawn a npc:

…

There are two ways to build a final npc instance: build and buildAndTrack. The first option only builds a raw NPC instance, leaving the full control to the caller which actions should be executed on the NPC. The second one uses the npc tracker of the base platform to track the npc, allowing the action controller and packet listeners to call actions for the NPC.

NPC flags

Some action controller related settings can also be done by using the npc flags (provided as constants in NPC). However, flags can also be used to add custom markers or settings to any flagged object, for example to store the base configuration from which a NPC was created.

Flag Name Default Value Description
LOOK_AT_PLAYER false Controls if tracked NPCs should automatically look at the player (only has an effect if the action controller is enabled on the platform)
HIT_WHEN_PLAYER_HITS false Controls if tracked NPCs should swing their main hand in case the player swings his main hand (only has an effect if the action controller is enabled on the platform)
SNEAK_WHEN_PLAYER_SNEAKS false Controls if tracked NPCs should sneak when the player sneaks (only has an effect if the action controller is enabled on the platform)

Events

This library provides some events to catch when certain actions are executed. Note that all events shown below are not platform specific. Event listeners must be registered into the event manager provided by the platform and not, for example, into the bukkit event system. Note that event listeners can be called from any thread, there is no guarantee that events happen on a specific thread (such as the main server thread). For example, if you need to access the Bukkit api, make sure that you manually execute the corresponding code on the main server thread.

Event Class Name Description
AttackNpcEvent Fired when a player hits (attacks) a NPC
InteractNpcEvent Fired when the player interacts with a NPC. Note that due to Minecraft weirdness this event is always called for both player hands at the moment.
ShowNpcEvent.Pre Fired before a NPC is spawned for a player. This event can be cancelled to prevent this action.
ShowNpcEvent.Post Fired after a NPC was successfully spawned to a player.
HideNpcEvent.Pre Fired before a NPC is despawned for a player. This event can be cancelled to prevent this action.
HideNpcEvent.Post Fired after a NPC was successfully despawned for a player.

Unfortunately events cannot be fired typesafe. Therefore, the player instance must be known to the event receiver and must be put into a typed variable to give it a specific type rather than object:

java
public final class AttackEventConsumer implements NpcEventConsumer {
  @Override
  public void handle(AttackNpcEvent event) {
    var badPlayer = event.player(); // player type is object as the type couldn't be inferred
    Player goodPlayer = event.player(); // player type is Player, but it must be known at compile time
  }
}

Code Examples

Minimal Example

The following code is a minimal example how a platform object is created and an NPC is spawned. In this example the default action controller is enabled which means that after spawning the npc using buildAndTrack the npc will automatically be spawned and shown to players in a 50 block range:

…

Configuring the action controller

As mentioned above the action controller can be changed using flags. In this example the action controller of the platform is configured in a way that NPCs are shown to players being 100 blocks away and simulation already starts when the player is 50 block away:

java
public final class TestPlugin extends JavaPlugin {
  private final Platform platform = BukkitPlatform
    .bukkitNpcPlatformBuilder()
    .extension(this)
    .actionController(builder -> builder
      .flag(NpcActionController.SPAWN_DISTANCE, 100)
      .flag(NpcActionController.IMITATE_DISTANCE, 50))
    .build();
}

Explicitly setting the protocol adapter and world resolver

Sometimes it's crucial that specific stuff is always setup the same, which isn't th

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Javaminecraftminecraft-npc-librarynpcnpc-lib

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言