Features

Installation

How to include a module

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

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

Repositories

Shading

Example Usage

On Bukkit

BukkitPlatform.bukkitNpcPlatformBuilder()

On Minestom

MinestomPlatform.minestomNpcPlatformBuilder()

On Fabric

FabricPlatform.fabricNpcPlatformBuilder()

Configuring the Platform

BukkitPlatform.bukkitNpcPlatformBuilder()// enables debug logging in the platform. this mostly enables errors// to be printed into the console directly instead of being held back// to prevent spamming the console.// Defaults to false (debug disabled).  .debug()// sets the extension of the platform, which is usually the plugin that// uses the plugin. on bukkit this is for example used to schedule sync// tasks using the bukkit scheduler.// This option has no default and must be set.  .extension()// the logger to use for internal logging of the library. while this logger// has the possibility to log info messages, the level won't be used unless// information relevant to the user are being printed.// Defaults to a platform-specific logger instance, on bukkit it uses an// implementation which is backed by the plugin logger.  .logger()// the event manager to use for the platform. all events, such as npc interacts// or spawns are propagated using this event manager.// Defaults to an internal default implementation.  .eventManager()// the tracker for npcs that are created by this library. as explained below// a spawned npc can either be tracked or kept untracked if not needed.// the tracker is used to store all spawned npcs and automatically execute// actions on them, for example automatic spawning when a player moves into// their spawn distance. it's also used to fire npc events such as interact when// an interact packet is received.// Defaults to an internal default implementation.  .npcTracker()// a scheduler for tasks that need to be executed either sync or async. the// implementation depends on the platform, for bukkit it's backed by the bukkit// scheduler, on minestom the minestom scheduler is used.// Defaults to a platform-specific implementation.  .taskManager()// the resolver to use for npc profiles. the resolver is given an unresolved// version of a profile (for example only an uuid or name) and completes the// profile data (name, uuid, textures).// see BukkitProfileResolver for the available resolvers on bukkit (paper or spigot)// Defaults to a platform-specific implementation.  .profileResolver()// the resolver for worlds of npcs. each npc position contains a world identifier// which is resolved using this resolver. the resolver can also provide the// identifier of a world using the world instance.// see BukkitWorldAccessor for the available resolvers on bukkit (name or key based)// see MinestomWorldAccessor for the available resolver on minestom (uuid based)// Defaults to a platform-specific implementation.  .worldAccessor()// the provider for version information about the current platform. it's internally// used to determine which features can be used. an example is the profile resolver:// when on paper 1.12 or later the paper profile resolver is used, when on spigot// 1.18.2 or later the spigot profile resolver is used, else a fallback mojang api// based access is used.// see BukkitVersionAccessor for the bukkit implementations (PaperLib based)// see MinestomVersionAccessor for the minestom implementation// Defaults to a platform-specific implementation.  .versionAccessor()// the factory for packets that need to be sent in order to spawn and manage npcs.// see BukkitProtocolAdapter for the available options on Bukkit (ProtocolLib or PacketEvents)// see MinestomProtocolAdapter for the minestom implementation// Defaults to a platform-specific implementation.  .packetFactory()// configures the default action controller for the platform. if this method isn't called// during the build process, the default action controller is disabled. the method provides// a builder which can be used to modify the settings of the action controller. if the default// values should be used, don't call any methods and just provide an empty lambda.  .actionController(builder ->builder    .flag(NpcActionController.SPAWN_DISTANCE,5))// builds the final platform object which can then be used to spawn and manage npcs  .build();

The action controller

Spawning a NPC

platform.newNpcBuilder()// the id to use for the entity. if not provided a random integer is generated and used instead.  .entityId()// the position where the npc should be spawned and located.// this option is required and must be set before spawning the npc.  .position()// sets resolved or unresolved profile for the npc. if an unresolved profile is used the method// returns a future completed with the current build when the profile was resolved. a specific// profile resolver to use can be provided as well.  .profile()// allows to add additional settings to the npc://  - a tracking rule to select the players which should be tracked automatically by the npc//  - a profile resolver which can dynamically resolve the npc profile when it gets spawned// if no builder callback is provided default npc settings are applied. this means that the npc will be// spawned to all players in range and the skin (via the profile) provided to this builder will always be used.  .npcSettings()// sets a value for a flag on the npc.  .flag();

NPC flags

Events

publicfinalclassAttackEventConsumerimplementsNpcEventConsumer<AttackNpcEvent> {@Overridepublicvoidhandle(AttackNpcEventevent) {varbadPlayer =event.player();// player type is object as the type couldn't be inferredPlayergoodPlayer =event.player();// player type is Player, but it must be known at compile time  }}

Code Examples

Minimal Example

publicfinalclassTestPluginextendsJavaPlugin {privatefinalPlatform<World,Player,ItemStack,Plugin>platform =BukkitPlatform    .bukkitNpcPlatformBuilder()    .extension(this)    .actionController(builder -> {})// enable action controller without changing the default config    .build();publicvoidspawnNpc(Locationlocation) {this.platform.newNpcBuilder()      .position(BukkitPlatformUtil.positionFromBukkitLegacy(location))      .profile(Profile.unresolved("derklaro"))      .thenAccept(builder -> {varnpc =builder.buildAndTrack();// continue using the npc...npc.unlink();// when the npc is no longer needed it can be completely removed using this method      });  }}

Configuring the action controller

publicfinalclassTestPluginextendsJavaPlugin {privatefinalPlatform<World,Player,ItemStack,Plugin>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

publicfinalclassTestPluginextendsJavaPlugin {privatefinalPlatform<World,Player,ItemStack,Plugin>platform =BukkitPlatform    .bukkitNpcPlatformBuilder()    .extension(this)    .packetFactory(BukkitProtocolAdapter.packetEvents())    .worldAccessor(BukkitWorldAccessor.nameBasedAccessor())    .build();}

Using the NPC settings to use player skins and only track specific players

publicfinalclassTestPluginextendsJavaPlugin {publicvoidspawnNpc(Locationlocation) {this.platform.newNpcBuilder()      .position(BukkitPlatformUtil.positionFromBukkitLegacy(location))      .npcSettings(builder ->builder        .profileResolver((player,npc) -> {// copy the profile properties into the profile of the npc to preserve the name// and uuid of the npc and not use the player name / uuid instead.varplayerProfile =Profile.unresolved(player.getUniqueId());returnthis.platform.profileResolver()            .resolveProfile(playerProfile)            .thenApply(profile ->npc.profile().withProperties(profile.properties()));        })        .trackingRule((npc,player) ->player.getExp() >=50))      .profile(Profile.unresolved("derklaro"))      .thenAccept(builder -> {varnpc =builder.buildAndTrack();// continue using the npc...      });  }}

Adding a custom flag to a NPC

publicfinalclassTestPluginextendsJavaPlugin {privatestaticfinalNpcFlag<NpcEntry>CONFIG_ENTRY_FLAG =NpcFlag.flag("npc_config_entry",null);publicvoidspawnNpc(NpcEntryconfigEntry) {this.platform.newNpcBuilder()      .flag(CONFIG_ENTRY_FLAG,configEntry)      .position(BukkitPlatformUtil.positionFromBukkitLegacy(configEntry.location()))      .profile(Profile.unresolved(configEntry.profileName()))      .thenAccept(builder -> {varnpc =builder.buildAndTrack();varconfigEntry =npc.flagValue(CONFIG_ENTRY_FLAG).orElseThrow();// continue using the npc...      });  }}

Customizing the imitation actions of the NPC

publicfinalclassTestPluginextendsJavaPlugin {publicvoidspawnNpc(Locationlocation) {this.platform.newNpcBuilder()      .flag(Npc.LOOK_AT_PLAYER,true)// look at the player      .flag(Npc.HIT_WHEN_PLAYER_HITS,true)// swing main hand when the player does so      .flag(Npc.SNEAK_WHEN_PLAYER_SNEAKS,true)// sneak when the player does so      .position(BukkitPlatformUtil.positionFromBukkitLegacy(location))      .profile(Profile.unresolved("derklaro"))      .thenAccept(builder -> {varnpc =builder.buildAndTrack();// continue using the npc...      });  }}

Handling interactions with a NPC

publicfinalclassTestPluginextendsJavaPlugin {privatefinalPlatform<World,Player,ItemStack,Plugin>platform =BukkitPlatform    .bukkitNpcPlatformBuilder()    .extension(this)    .actionController(builder -> {})// enable action controller without changing the default config    .build();publicvoidregisterNpcListeners() {vareventManager =this.platform.eventManager();eventManager.registerEventHandler(AttackNpcEvent.class,attackEvent -> {varnpc =attackEvent.npc();Playerplayer =attackEvent.player();player.sendMessage("You attacked NPC " +npc.profile().name() +"! That's not nice!");    });eventManager.registerEventHandler(InteractNpcEvent.class,interactEvent -> {varnpc =interactEvent.npc();Playerplayer =interactEvent.player();player.sendMessage("[" +npc.profile().name() +"]: Move along citizen!");    });  }}

Enabling skin layers & changing the entity status

publicfinalclassTestPluginextendsJavaPlugin {privatefinalPlatform<World,Player,ItemStack,Plugin>platform =BukkitPlatform    .bukkitNpcPlatformBuilder()    .extension(this)    .actionController(builder -> {})// enable action controller without changing the default config    .build();publicvoidregisterNpcListeners() {vareventManager =this.platform.eventManager();eventManager.registerEventHandler(ShowNpcEvent.Post.class,showEvent -> {varnpc =showEvent.npc();Playerplayer =showEvent.player();// enable all skin playersnpc.changeMetadata(EntityMetadataFactory.skinLayerMetaFactory(),true).schedule(player);// set the npc on fire// note: the glowing entity status must be sent in order for the entity to appear glowing. The logic of adding// the npc into a team and setting the glowing color must be handled by your plugin.varentityStatus =EnumSet.of(EntityStatus.ON_FIRE);npc.changeMetadata(EntityMetadataFactory.entityStatusMetaFactory(),entityStatus).schedule(player);    });  }}

Adding items into the inventory of a npc

publicfinalclassTestPluginextendsJavaPlugin {privatefinalPlatform<World,Player,ItemStack,Plugin>platform =BukkitPlatform    .bukkitNpcPlatformBuilder()    .extension(this)    .actionController(builder -> {})// enable action controller without changing the default config    .build();publicvoidregisterNpcListeners() {vareventManager =this.platform.eventManager();eventManager.registerEventHandler(ShowNpcEvent.Post.class,showEvent -> {varnpc =showEvent.npc();Playerplayer =showEvent.player();// puts a dragon egg into the main hand of the npcvardragonEggItem =newItemStack(Material.DRAGON_EGG);npc.changeItem(ItemSlot.MAIN_HAND,dragonEggItem).schedule(player);    });  }}

Additional protocol-related methods in NPC

publicfinalclassTestPluginextendsJavaPlugin {privatefinalPlatform<World,Player,ItemStack,Plugin>platform =BukkitPlatform    .bukkitNpcPlatformBuilder()    .extension(this)    .actionController(builder -> {})// enable action controller without changing the default config    .build();publicvoidregisterNpcListeners() {vareventManager =this.platform.eventManager();eventManager.registerEventHandler(ShowNpcEvent.Post.class,showEvent -> {varnpc =showEvent.npc();Playerplayer =showEvent.player();// let the NPC look into the direction of 0, 50, 0varspawnLocation =Position.position(0,50,0,npc.position().worldId());npc.lookAt(spawnLocation).schedule(player);// lets the NPC swing his main armnpc.playAnimation(EntityAnimation.SWING_MAIN_ARM).schedule(player);// sets the player head rotation to yaw=0 & pitch=90npc.rotate(0,90).schedule(player);    });  }}

Manually (de-) spawning a NPC

publicfinalclassTestPluginextendsJavaPlugin {publicvoidspawnNpcToPlayer(Npc<World,Player,ItemStack,Plugin>npc,Playerplayer) {// use this method if you want to spawn the npc to the player, but only if all preconditions// (such as the player tracking rule) are met. You can manually check if a player would be// tracked by a npc by calling: `npc.shouldIncludePlayer(player)`.npc.trackPlayer(player);// Use this method if you want to spawn the npc to the player even is preconditions aren't met.// Note: this still calls the ShowNpc.Pre event which can still be cancelled by one of your event// listeners causing the npc to not get spawned for the player.npc.forceTrackPlayer(player);  }publicvoidremoveNpcForPlayer(Npc<World,Player,ItemStack,Plugin>npc,Playerplayer) {// despawns the npc for the given player unless the npc is not spawned for the player. you can always// check the players for which a NPC is spawned by calling `npc.trackedPlayers()` or check for a// specific player by using `npc.tracksPlayer(player)`.// Note: this method calls the HideNpcEvent.Pre event which means that an event listener can// prevent the npc despawn process from being executed.npc.stopTrackingPlayer(player);  }}

Letting the NPC do a LabyMod emote

publicfinalclassTestPluginextendsJavaPlugin {publicvoidplayLabyModEmoteForPlayer(Npc<World,Player,ItemStack,Plugin>npc,Playerplayer,int...emoteIds) {LabyModExtension.createEmotePacket(npc.platform().packetFactory(),emoteIds).schedule(player,npc);  }}

Compiling from source

git clone https://github.com/juliarn/npc-lib.gitcd npc-libgradlew publishToMavenLocal

Images