用于 1.8-1.21 服务器的异步、高性能 Minecraft NPC 库。
There are some images down below showcasing the use and features of this library.
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. |
Maven:
io.github.juliarn
(module name from the list above)
(latest version)
compile
Gradle:
implementation("io.github.juliarn", "(module name from the list above)", "(latest version)")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)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.kyoriio.leangen.geantyrefio.github.retroopercom.github.retroopercom.github.juliarn.npclibPlatform 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:
BukkitPlatform.bukkitNpcPlatformBuilder()MinestomPlatform.minestomNpcPlatformBuilder()FabricPlatform.fabricNpcPlatformBuilder()In all further examples bukkit will be used as a reference, but the api is the same on all other platforms:
…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. |
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.
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) |
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:
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
}
}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:
…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:
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();
}Sometimes it's crucial that specific stuff is always setup the same, which isn't th
暂无开放 Issues,或尚未同步最近议题。