From 677ce884f64f962ca62e7d7b36f9a14ce2e8c849 Mon Sep 17 00:00:00 2001 From: Jitse Boonstra Date: Tue, 19 Feb 2019 22:55:24 +0100 Subject: [PATCH] Added DOCUMENTATION, CREDITS and changed README. --- CREDITS.md | 15 ++++++++ DOCUMENTATION.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 29 ++------------- 3 files changed, 115 insertions(+), 26 deletions(-) create mode 100644 CREDITS.md create mode 100644 DOCUMENTATION.md diff --git a/CREDITS.md b/CREDITS.md new file mode 100644 index 0000000..f9c122a --- /dev/null +++ b/CREDITS.md @@ -0,0 +1,15 @@ +![Banner](https://i.imgur.com/WL6QeUA.png) +NPCLib – Basic non-player character library.
+= + +This is an API made specifically for spigot servers (Minecraft). Current supported versions: **1.7.10\* - 1.13.2**. Lightweight replacement for Citizens. NPCLib only uses packets instead of registering the entity in the actual Minecraft server. + +\*NPCLib has basic support for 1.7.10, as it not currently support multi-line text for this version (yet). + +## Credits + +### [TinyProtocol](https://github.com/aadnk/ProtocolLib/tree/master/modules/TinyProtocol) by Kristian Stangeland +I used this module of ProtocolLib to intercept packets sent by players whilst interacting with NPCs. After retrieving the data from these packets, I can call a new [NPCInteractEvent](https://github.com/JitseB/NPCLib/blob/master/commons/src/main/java/net/jitse/npclib/events/NPCInteractEvent.java). + +### [MineSkin](https://mineskin.org) by Haylee Schäfer +I integrated MineSkin into NPCLib as an easy way for developers to give NPCs a custom skin without buying multiple Minecraft accounts or saving the skin data themselves. \ No newline at end of file diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..2133e4c --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,97 @@ +![Banner](https://i.imgur.com/WL6QeUA.png) +NPCLib – Basic non-player character library.
+= + +This is an API made specifically for spigot servers (Minecraft). Current supported versions: **1.7.10\* - 1.13.2**. Lightweight replacement for Citizens. NPCLib only uses packets instead of registering the entity in the actual Minecraft server. + +\*NPCLib has basic support for 1.7.10, as it not currently support multi-line text for this version (yet). + +## Documentation + +### Creating a library instance + +To start using NPCLib, you will first need to create a new instance of the library. Do this in your `onEnable` method, as it will register some event listeners. + +```Java +private NPCLib library; + +@Override +public void onEnable() { + this.library = new NPCLib(this); +} +``` + +Do not create a new NPCLib instance for every class! Instead, create a getter for the library instance: + +```Java +public NPCLib getNPCLib() { + return library; +} +``` + + +### Creating your first NPC + +Now you have an instance of the library, it is time to create your first NPC! You may create NPCs after your plugin and NPCLib have enabled. + +If you want your NPC to have a custom skin, either [create your own Skin object](#create-skin-object) or fetch the data from [mineskin.org](https://mineskin.org) using the [SkinFetcher](#skin-fetcher) class. + +```Java +// Skin parameter: The skin you would like the NPC to have (may be null). +// AutoHideDistance parameter: The distance NPCLib will use to automatically hide the NPC (default = 50). +// Lines parameter: The text you would like to display above the NPC's head (may be null). +NPC npc = library.createNPC(Skin skin, double autoHideDistance, List lines); +``` + +Even though you have created the NPC object now, you will not be able to see it just yet. We first need to show it to the player. The NPC does not show up to players automatically because NPCLib relies on packets rather than registering the actual entity in the Minecraft server. + +```Java +npc.show(Player player); +``` + +When you want to hide the NPC from the player **temporary**, you can hide it: + +```Java +npc.hide(Player player); +``` + +When you are done using the NPC, you will have to destroy all NPCs accordingly: + +```Java +npc.destroy(); +``` + +If you're destroying NPCs, because you are reloading your plugin. I recommend using the following method (as it does not use any schedulers): + +```Java +npc.destroy(true); +``` + +#### NPC handling + +Every NPC is given a unique identifier (`NPC#getEntityId`)that should be used throughout your plugin to identify which NPC has been interacted with. + +#### Create skin object + +The values used for the Skin object originate from the [Mojang sessionserver](https://wiki.vg/Mojang_API#UUID_-.3E_Profile_.2B_Skin.2FCape). +```Java +Skin skin = new Skin(String value, String signature); +``` + +#### Skin fetcher + +The Mojang sessionsserver can only be requested a limited amount of times. Furthermore, the skin data is saved in a profile that is linked to a UUID. We cannot save multiple skins without overly costly solutions. Therefore, saving the values and signatures (of the skin) in a third party database is the ultimate solution. Which is exactly what MineSkin is. + +I wrote a little utility [class](https://github.com/JitseB/NPCLib/blob/master/commons/src/main/java/net/jitse/npclib/skin/MineSkinFetcher.java) that fetches the skin data from MineSkin. Here is how you use that class: + +```Java +MineSkinFetcher.fetchSkinFromIdAsync(int id, skin -> { + // Create your NPC. +}) +``` + +The ID in this method is the ID that is in the URL of your MineSkin skin (e.g. https://mineskin.org/725954 has ID 725954). + +### Useful events + +Events you may want to use are `NPCSpawnEvent`, `NPCDestroyEvent` and `NPCInteractEvent`. \ No newline at end of file diff --git a/README.md b/README.md index 445a17a..f7ae739 100755 --- a/README.md +++ b/README.md @@ -47,32 +47,7 @@ Alternatively, you can put `npclib-plugin-v*.jar` under your `plugins` folder. B [Click here](https://github.com/JitseB/NPCLib/releases/latest) to download the latest release. -```Java - // First we define our (global) library variable. - // This is usually done in the onEnable method. - NPCLib lib = new NPCLib(plugin); -``` - -```Java - - // Creating a new NPC instance. - // MC 1.7.10 (1.7 R4) only supports single-line text. - NPC npc = lib.createNPC(skin, lines); - - // Then let the library generate the necessary packets. - npc.create(location); - - // You are all set! You can now show/hide it to/from players. - npc.show(player); - npc.hide(player); - - // If you do not wish to use the NPC anymore, destroy it accordingly. - npc.destroy(); -``` - -### Events - -Events you may want to use are `NPCSpawnEvent`, `NPCDestroyEvent` and `NPCInteractEvent`. +[Click here](https://github.com/JitseB/NPCLib/blob/master/DOCUMENTATION.md) for an elaborate explanation on how to use NPCLib in your next project. ### Building your own version @@ -95,6 +70,8 @@ Plugin(s) using NPCLib: We thank all those who have [contributed](https://github.com/JitseB/NPCLib/graphs/contributors) to the creation of what NPCLib is today. +Please view the credits [here](https://github.com/JitseB/NPCLib/blob/master/CREDITS.md). + ## Copyright Copyright (c) Jitse Boonstra 2018 All rights reserved.