From ad3183fca1786409da860987c97655b2b5e3c876 Mon Sep 17 00:00:00 2001 From: William Date: Wed, 18 Oct 2023 19:29:31 +0100 Subject: [PATCH] docs: Add API docs --- docs/API-Examples.md | 59 ++++++++++++++++ docs/API.md | 155 +++++++++++++++++++++++++++++++++++++++++++ docs/Home.md | 2 + docs/_Sidebar.md | 2 + 4 files changed, 218 insertions(+) create mode 100644 docs/API-Examples.md create mode 100644 docs/API.md diff --git a/docs/API-Examples.md b/docs/API-Examples.md new file mode 100644 index 0000000..b252b31 --- /dev/null +++ b/docs/API-Examples.md @@ -0,0 +1,59 @@ +Velocitab provides an API for vanishing (hiding) and modifying the names of players as they appear in the TAB list for other players. + +This page assumes you have read the general [[API]] introduction and that you have both imported Velocitab into your project and added it as a dependency. + +## 1. Vanishing/Un-vanishing a player + +### 1.1 Vanishing a player +Use `VelocitabAPI#vanishPlayer` to vanish a player. This method takes a Velocity `Player` as a parameter. + +This will hide a user from all TAB lists (they will not be shown). Note this will not remove them at a packet level; Vanish plugins should use this API feature as a utility that forms part of their Vanish implementation. + +
+Example — Vanishing a player + +```java +// Vanishing a proxy Player +VelocitabAPI.vanishPlayer(player); +``` +
+ +### 1.2 Un-vanishing a player +Use `VelocitabAPI#unvanishPlayer` to un-vanish a player. This method takes a Velocity `Player` as a parameter. + +This will allow the user to be shown in all TAB lists again. + +
+Example — Un-vanishing a player + +```java +// Un-vanishing a proxy Player +VelocitabAPI.unvanishPlayer(player); +``` +
+ +### 1.3 Providing a Vanish Integration +You can provide a Vanish integration to provide a managed class to Vanish/Unvanish a player through the `VelocitabAPI#setVanishIntegration` instance. + +## 2. Modifying a player's name +You can set a custom name for a player that will be displayed in `%name%` placeholders in the TAB list. This can be used to display a player's nickname, for example. This is done through `VelocitabAPI#setCustomPlayerName()`, which accepts a Velocity `Player` and a `String` custom name + +
+Example — Setting a custom name for a player + +```java +// Setting a custom name for a proxy Player +VelocitabAPI.setCustomPlayerName(player, "CustomName"); +``` +
+ +You can also use `VelocitabAPI#getCustomPlayerName(Player)` to get a player's custom name, wrapped in an `Optional` that will return with the String of the player's custom name if one has been set (otherwise `Optional#empty`) + +
+Example — Getting a player's custom name + +```java +// Getting a player's custom name +Optional customName = VelocitabAPI.getCustomPlayerName(player); +``` +
\ No newline at end of file diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..71591fe --- /dev/null +++ b/docs/API.md @@ -0,0 +1,155 @@ +The Velocitab API provides methods for vanishing ("hiding") and modifying usernames on the TAB list. + +The API is distributed on Maven through [repo.william278.net](https://repo.william278.net/#/releases/net/william278/velocitab/) and can be included in any Maven, Gradle, etc. project. JavaDocs are [available here](https://repo.william278.net/javadoc/releases/net/william278/velocitab/latest). + +## Compatibility +[![Maven](https://repo.william278.net/api/badge/latest/releases/net/william278/velocitab?color=00fb9a&name=Maven&prefix=v)](https://repo.william278.net/#/releases/net/william278/velocitab/) + +The Velocitab API shares version numbering with the plugin itself for consistency and convenience. Please note minor and patch plugin releases may make API additions and deprecations, but will not introduce breaking changes without notice. + +| API Version | Velocitab Versions | Supported | +|:-----------:|:----------------------:|:---------:| +| v1.x | _v1.5.1—Current_ | ✅ | + +## Table of contents +1. Adding the API to your project +2. Adding Velocitab as a dependency +3. Next steps + +## API Introduction +### 1.1 Setup with Maven +
+Maven setup information + +Add the repository to your `pom.xml` as per below. You can alternatively specify `/snapshots` for the repository containing the latest development builds (not recommended). +```xml + + + william278.net + https://repo.william278.net/releases + + +``` +Add the dependency to your `pom.xml` as per below. Replace `VERSION` with the latest version of Velocitab (without the v): ![Latest version](https://img.shields.io/github/v/tag/WiIIiam278/Velocitab?color=%23282828&label=%20&style=flat-square) +```xml + + net.william278 + velocitab + VERSION + provided + +``` +
+ +### 1.2 Setup with Gradle +
+Gradle setup information + +Add the dependency as per below to your `build.gradle`. You can alternatively specify `/snapshots` for the repository containing the latest development builds (not recommended). +```groovy +allprojects { + repositories { + maven { url 'https://repo.william278.net/releases' } + } +} +``` +Add the dependency as per below. Replace `VERSION` with the latest version of Velocitab (without the v): ![Latest version](https://img.shields.io/github/v/tag/WiIIiam278/Velocitab?color=%23282828&label=%20&style=flat-square) + +```groovy +dependencies { + compileOnly 'net.william278:velocitab:VERSION' +} +``` +
+ +### 2. Adding Velocitab as a dependency +Add Velocitab as a dependency in your main class annotation: + +```java +@Plugin( + id = "myplugin", + name = "My Plugin", + version = "0.1.0", + dependencies = { + @Dependency(id = "velocitab", optional = true) + } +) +public class MyPlugin { + // ... +} +``` + +
+Alternative method: Adding to `velocity-plugin.json` + +```json +{ + "dependencies": [ + { + "id": "velocitab", + "optional": true + } + ] +} +``` +
+ +## 3. Creating a class to interface with the API +- Unless your plugin completely relies on Velocitab, you shouldn't put Velocitab API calls into your main class, otherwise if Velocitab is not installed you'll encounter `ClassNotFoundException`s + +```java +public class VelocitabAPIHook { + + public VelocitabAPIHook() { + // Ready to do stuff with the API + } + +} +``` +## 4. Checking if Velocitab is present and creating the hook +- Check to make sure the Velocitab plugin is present before instantiating the API hook class + +```java + +@Plugin( + id = "myplugin", + name = "My Plugin", + version = "0.1.0", + dependencies = { + @Dependency(id = "velocitab", optional = true) + } +) +public class MyPlugin { + + public VelocitabAPIHook velocitabHook; + + @Subscribe + public void onProxyInitialization(@NotNull ProxyInitializeEvent event) { + if (event.getProxy().getPluginManager().getPlugin("velocitab").isPresent()) { + velocitabHook = new VelocitabAPIHook(); + } + } + +} +``` + +## 5. Getting an instance of the API +- You can now get the API instance by calling `VelocitabAPI#getInstance()` + +```java +import net.william278.velocitab.api.BukkitVelocitabAPI; + +public class VelocitabAPIHook { + + private final VelocitabAPI velocitabApi; + + public VelocitabAPIHook() { + this.velocitabApi = VelocitabAPI.getInstance(); + } + +} +``` + +### 6. Next steps +Now that you've got everything ready, you can start doing stuff with the Velocitab API! +- [[API Examples]] \ No newline at end of file diff --git a/docs/Home.md b/docs/Home.md index a608b1e..ba429c6 100644 --- a/docs/Home.md +++ b/docs/Home.md @@ -16,6 +16,8 @@ Please click through to the topic you wish to read about. * ✍️ [[Placeholders]] * ✨ [[Animations]] * 🖼️ [[Custom Logos]] +* 📦 [[API]] + * 📝 [[API Examples]] ## Links * 💻 [GitHub](https://github.com/WiIIiam278/Velocitab) diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md index 180bf75..f5e83c5 100644 --- a/docs/_Sidebar.md +++ b/docs/_Sidebar.md @@ -10,6 +10,8 @@ * ✍️ [[Placeholders]] * ✨ [[Animations]] * 🖼️ [[Custom Logos]] +* 📦 [[API]] + * 📝 [[API Examples]] ## Links * 💻 [GitHub](https://github.com/WiIIiam278/Velocitab)