Fork/Velocitab
2
0
Fork 0
forked from Upstream/Velocitab
Code Pull Requests Actions Releases Activity

Add docs to main repo, docs update action

Browse Source
This commit is contained in:
William 2023-04-21 13:57:24 +01:00
parent 548e47f85a
commit e98ffaf4a6
No known key found for this signature in database
9 changed files with 382 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
.github/workflows/update_docs.yml vendored Normal file
View File

@ -0,0 +1,22 @@
# Update the GitHub Wiki documentation when a push is made to docs/
name: Update Docs
on:
push:
paths:
- 'docs/**'
branches:
- master
jobs:
deploy-wiki:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Push Changes to GitHub Wiki
uses: Andrew-Chen-Wang/github-wiki-action@v3
env:
WIKI_DIR: docs/
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
GH_MAIL: ${{ github.actor }}@users.noreply.github.com
GH_NAME: ${{ github.repository_owner }}

86
docs/Animations.md Normal file
View File

@ -0,0 +1,86 @@
Velocitab lets you create basic animations in the header and footer, which you can combine with some nice [[Formatting]] to create a slick TAB menu for your server. Note you cannot animate player name formats, only headers and footers.
## Creating basic animations
By default, Velocitab headers/footers are static; only containing a single frame of animation and only updating when a user joins/leaves your server, or when permissions are recalcualated by LuckPerms.
### Adding additional frames of animation
To add additional frames of animation to a header format for a [server group](server-groups), add it to the string list for that group. The example below uses the MineDown gradient fade feature to create a simple three-phase animation.
<details>
<summary>Basic header animation (config.yml)</summary>
```yaml
headers:
default:
- '&rainbow&Running Velocitab by William278'
- '&rainbow:10&Running Velocitab by William278'
- '&rainbow:20&Running Velocitab by William278'
```
</details>
By default, the plugin will switch between each frame whenever it is updated. To get this to animate, you must configure your `update_rate` setting.
### Setting the frame rate
The `update_rate` setting in your `config.yml` file&mdash;set to `0` by default&mdash;controls the length (in milliseconds, where `1ms = 1/1000th` of a second) between yoru TAB list being updated. On each update, the header or footer format will use the next frame in the list, looping back to the first after the last one has been displayed.
A good starting value for this could be `1000`, which is equivalent to one second. Once you've changed the value, use `/velocitab reload` to update the TAB menu in-game without restarting your proxy.
## Example: Rainbow fade
![Example rainbow fade animation GIF](https://user-images.githubusercontent.com/31187453/232607366-35d530dc-fb2a-419b-a345-3cc758baa6df.gif)
Wondering how to make something like the above example? Here's how! This example uses MineDown formatting and its' gradient fade feature to create a convincing rainbow fade that's pleasing on the eyes.
<details>
<summary>Example rainbow fade (config.yml)</summary>
Please note this is not a complete config file; you will need to add the relevant sections to the correct part in your own Velocitab `config.yml`.
```yaml
headers:
default:
- '&rainbow&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:2&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:4&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:6&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:8&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:10&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:12&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:14&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:16&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:18&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:20&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:22&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:24&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:26&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:28&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:30&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:32&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:34&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:36&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:38&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:40&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:42&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:44&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:46&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:48&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:50&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:52&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:54&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:56&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:58&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
- '&rainbow:60&Velocitab ⭐ A super-simple (sorted!) Velocity TAB menu plugin\n'
footers:
default:
- |
\n&7For Velocity proxy servers:
&#1bd96a-#6cffa9&https://modrinth.com/plugin/velocitab
&#1bd96a-#6cffa9&https://william278.net/project/veloictab'
formats:
default: '&#999-#fff&[%server%] &f%username%'
formatting_type: MINEDOWN
server_groups:
default:
- server
- server2
update_rate: 100
```
</details>

69
docs/Config-File.md Normal file
View File

@ -0,0 +1,69 @@
This page contains the configuration file reference for Velocitab. The config file is located in `/plugins/velocitab/config.yml`
## Example config
<details>
<summary>config.yml</summary>
```yaml
# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃ Velocitab Config ┃
# ┃ Developed by William278 ┃
# ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
# ┗╸ Placeholders: %players_online%, %max_players_online%, %local_players_online%, %current_date%, %current_time%, %username%, %server%, %ping%, %prefix%, %suffix%, %role%
# Header(s) to display above the TAB list for each server group.
# List multiple headers and set update_rate to the number of ticks between frames for basic animations
headers:
default:
- '&rainbow&Running Velocitab by William278'
# Footer(s) to display below the TAB list for each server group, same as headers.
footers:
default:
- '[There are currently %players_online%/%max_players_online% players online](gray)'
formats:
default: '&7[%server%] &f%prefix%%username%'
# Which text formatter to use (MINEDOWN, MINIMESSAGE, or LEGACY)
formatting_type: MINEDOWN
# The servers in each group of servers
server_groups:
default:
- server
- server2
# All servers which are not in other groups will be put in the fallback group.
# "false" will exclude them from Velocitab.
fallback_enabled: true
# The formats to use for the fallback group.
fallback_group: default
# Only show other players on a server that is part of the same server group as the player.
only_list_players_in_same_group: true
# Define custom names to be shown in the TAB list for specific server names.
# If no custom display name is provided for a server, its original name will be used.
server_display_names:
very-long-server-name: VLSN
enable_papi_hook: true
# If you are using MINIMESSAGE formatting, enable this to support MiniPlaceholders in formatting.
enable_miniplaceholders_hook: true
# Whether to sort players in the TAB list.
sort_players: true
# Ordered list of elements by which players should be sorted. (ROLE_WEIGHT, ROLE_NAME and SERVER are supported)
sort_players_by:
- ROLE_WEIGHT
- ROLE_NAME
# How often in milliseconds to periodically update the TAB list, including header and footer, for all users.
# If set to 0, TAB will be updated on player join/leave instead. (1s = 1000ms)
update_rate: 0
```
</details>
## Details
### Server Groups
Which formatting to use for a player's TAB list is determined by the group they are on. See [[Server Groups]] for more information.
### Formatting
Velocitab supports the full range of modern color formatting, including RGB colors and gradients, through either MineDown or MiniMessage syntax. See [[Formatting]] for more information.
### Animations
Velocitab supports basic header and footer animations by adding multiple frames of animation and setting the update rate to a value greater than 0.
### Placeholders
You can use various placeholders that will be replaced with values (for example, `%username%`) in your config. Support for PlaceholderAPI is also available through [a bridge library plugin](https://modrinth.com/plugin/papiproxybridge), as is the component-based MiniPlaceholders for users of that plugin with the MiniMessage formatter. See [[Placeholders]] for more information.

14
docs/Formatting.md Normal file
View File

@ -0,0 +1,14 @@
Velocitab supports the full range of modern color formatting, including RGB colors and gradients. Both MineDown (_default_) and MiniMessage are supported as formats. To change which formatter is being used, change the `formatting_type` value in `config.yml` to `MINEDOWN` or `MINIMESSAGE` respectively.
Formatting is applied on header, footer and player text for each server group, and is applied after [[Placeholders]] have been inserted.
## MineDown syntax reference
MineDown is the default formatter type. See the [MineDown Syntax Reference](https://github.com/Phoenix616/MineDown) on GitHub for the specification of how to format text with it.
## MiniMessage syntax reference
MiniMessage formatting can be enabled by setting `formatting_type` to `MINIMESSAGE` in `config.yml`. See the [MiniMessage Syntax Reference](https://docs.advntr.dev/minimessage/format.html) on the Adventure Docs for how to format text with it. Using MiniMessage as the formatter also allows compatibility for using MiniPlaceholders in text.
## Legacy formatting
> ⚠️ Option for legacy formatting is provided only for backwards compatibility with other plugins, please consider using MineDown or MiniMessage options instead!
Legacy formatting can be enabled by setting `formatting_type` to `LEGACY` in `config.yml`. Legacy formatter supports Mojang color and formatting codes (e.g. `&d`, `&l`), Adventure-styled RGB color codes (e.g. `&#a25981`), as well as BungeeCord RGB color codes (e.g. `&x&a&2&5&9&8&1`). See the [LegacyComponentSerializer Syntax Reference](https://docs.advntr.dev/serializer/legacy.html) on the Adventure Docs for more technical details.

20
docs/Home.md Normal file
View File

@ -0,0 +1,20 @@
![Velocitab banner](https://raw.githubusercontent.com/WiIIiam278/Velocitab/master/images/banner.png)
Welcome to the plugin documentation for Velocitab. Velocitab is a super-simple Velocity TAB menu plugin that uses scoreboard team client-bound packets to actually sort player lists by role without the need for a backend plugin.
Please click through to the topic you wish to read about.
## Guides
* 📚 [[Setup]]
* 📄 [[Config File]]
## Documentation
* 👥 [[Server Groups]]
* 🎨 [[Formatting]]
* ✍️ [[Placeholders]]
* ✨ [[Animations]]
## Links
* 💻 [GitHub](https://github.com/WiIIiam278/Velocitab)
* 📂 [Download](https://modrinth.com/plugin/velocitab)
* 💬 [Discord Support](https://discord.gg/tVYhJfyDWG)

39
docs/Placeholders.md Normal file
View File

@ -0,0 +1,39 @@
Velocitab supports a number of Placeholders that will be replaced with their respective proper values in-game. In addition to the set of provided default Placeholders, you can make use of PlaceholderAPI and MiniPlaceholder-provided placeholders through special hooks.
## Default placeholders
Placeholders can be included in the header, footer and player name format of the TAB list. The following placeholders are supported out of the box:
| Placeholder | Description | Example |
|--------------------------|-----------------------------------------------|--------------------|
| `%players_online%` | Players online on the proxy | `6` |
| `%max_players_online%` | Player capacity of the proxy | `500` |
| `%local_players_online%` | Players online on the server the player is on | `3` |
| `%current_date%` | Current real-world date of the server | `24 Feb 2023` |
| `%current_time%` | Current real-world time of the server | `21:45:32` |
| `%username%` | The player's username | `William278` |
| `%server%` | Name of the server the player is on | `alpha` |
| `%ping%` | Ping of the player (in ms) | `6` |
| `%prefix%` | The player's prefix (from LuckPerms) | `&4[Admin]` |
| `%suffix%` | The player's suffix (from LuckPerms) | `&c ` |
| `%role%` | The player's primary LuckPerms group | `admin` |
| `%debug_team_name%` | Internal team value, used for list sorting | `1_alpha_William2` |
### Customising server display names
You can make use of the `server_display_names` feature in `config.yml` to customise how server display name appear when using the `%server%` placeholder. In the below example, if the user was connected to a server with the name "`very-long-server-`name" and the player name format for the group that server belongs to included a `%server%` placeholder, the placeholder would be replaced with "`VSLN`" instead of the full name!
<details>
<summary>Server display names (config.yml)</summary>
```yaml
# Define custom names to be shown in the TAB list for specific server names.
# If no custom display name is provided for a server, its original name will be used.
server_display_names:
very-long-server-name: VLSN
```
</details>
## PlaceholderAPI support
To use PlaceholderAPI placeholders in Velocitab, install the [PAPIProxyBridge](https://modrinth.com/plugin/papiproxybridge) library plugin on your Velocity proxy and all Minecraft spigot servers on your network, and ensure the PAPI hook option is enabled in your Velocitab [[Config File]]. You can then include PAPI placeholders in your foramts as you would any of the default placeholders.
## MiniPlaceholders support
If you are using MiniMessage [[Formatting]], you can use [MiniPlaceholders](https://github.com/MiniPlaceholders/MiniPlaceholders) with Velocitab for MiniMessage-styled component placeholders provided by other proxy plugins. Install MiniPlaceholders on your Velocity proxy, set the `formatter_type` to `MINIMESSAGE` and ensure `enable_miniplaceholders_hook` is set to `true`

100
docs/Server-Groups.md Normal file
View File

@ -0,0 +1,100 @@
Velocitab supports defining multiple server groups, each providing distinct formatting for players in the TAB list, alongside unique headers and footers. This is useful if you wish to display different information in TAB depending on the server a player is on.
## Defining groups
Groups are defined in the `server_groups` section of `config.yml`, as a list of servers following the group name (by default, a group `default` will be present, alongside a list of servers on your network.
<details>
<summary>Example of a default config.yml</summary>
```yaml
server_groups:
default:
- lobby1
- lobby2
- lobby3
```
</details>
You can define as many groups as you wish in this section by adding more lists of servers.
<details>
<summary>Adding more groups</summary>
```yaml
server_groups:
lobbies:
- lobby1
- lobby2
creative:
- creative_lobby
- creative1
survival:
- survival1
- survival2
```
</details>
## Mapping headers, footers & player formats to groups
Once you've defined your groups, you can modify the `headers`, `footers` and `formats` section of the file with different formats for each group.
<details>
<summary>Per-group formats</summary>
```yaml
headers:
lobbies:
- 'Welcome, %username%! Join a server to start!'
creative:
- '%username% is playing Creative!'
survival:
- '%username% is playing Survival!'
footers:
lobbies:
- 'There are %players_online%players online!'
creative:
- 'Currently connected to a creative server: %server%!'
survival:
- 'Today is %current_date%!'
formats:
lobbies: '&8[Lobby] &7%username%'
creative: '&e[Creative] &7[%server%] &f%prefix%%username%'
survival: '&2[Survival (%server%)] &f%prefix%%username%'
```
</details>
See [[Placeholders]] for how to use placeholders in these formats, and [[Formatting]] for how to format text with colors, and see [[Animations]] for how to create basic animations by adding more headers/footers to each group's list.
### Adding new lines
If you want to add a new line to your header or footer format, you can use `\n` to insert one &mdash; but since this gets messy quickly, there's an easier way using the YAML markup pipe character to declare a multiline string:
<details>
<summary>Multi-line headers/footers</summary>
```yaml
footers:
lobbies:
- |
There are %players_online%players online!
I'm a second line
Third line, woohoo~!
```
</details>
Player name formats may only utilize one line.
## Default group
If a player isn't connected to a server on your network, their TAB menu will be formatted as per the formats defined by `fallback_group` set in `config.yml`, provided `fallback_enabled` is set to `true`.
If you don't want them to have their TAB handled at all by Velocitab, you can use this to disable Velocitab formatting on certain servers altogether by disabling the `fallback_enabled` setting and excluding servers you do not wish to format from being part of a group.
<details>
<summary>Example in config.yml</summary>
```yaml
# All servers which are not in other groups will be put in the fallback group.
# "false" will exclude them from Velocitab.
fallback_enabled: true
# The formats to use for the fallback group.
fallback_group: 'lobbies'
```
</details>

18
docs/Setup.md Normal file
View File

@ -0,0 +1,18 @@
This page will walk you through installing Velocitab on a Velocity proxy server.
## Requirements
* A Velocity proxy server (running Velocity 3.2.0 or newer)
* Backend Minecraft servers (running Minecraft version 1.16.5 or newer)&dagger;
&dagger;_Servers that support clients with versions older than 1.16 are not supported, as Velocitab relies on dispatching protocol-compatible packets and modern 1.16 RGB chat color formatting. Users attempting to connect on earlier versions will cause errors to display in your proxy server console._
## Installation
1. Download the latest version of [Velocitab](https://modrinth.com/plugin/velocitab)
2. Drag both into the `/plugins/` folder on your Velocity proxy server
3. Download and install additional optional dependencies on your proxy and backend servers as needed:
1. If you'd like Velocitab to display user roles from [LuckPerms](https://luckperms.net/), ensure LuckPerms is installed on your proxy as well, and configured to synchronise role information via MySQL and Plugin Messages or Redis.
2. If you'd like to use [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) placeholders, install [PAPIProxyBridge](https://modrinth.com/plugin/papiproxybridge) on both your Velocity server and Spigot-based Minecraft servers. Also ensure PlaceholderAPI is installed on your spigot servers.
4. Restart your proxy to let Velocitab generate its configuration file
5. Stop your proxy server, modify the `config.yml` file to your liking, and start your server.
Velocitab should now be successfully installed on your proxy.

14
docs/_Sidebar.md Normal file
View File

@ -0,0 +1,14 @@
## Guides
* 📚 [[Setup]]
* 📄 [[Config File]]
## Documentation
* 👥 [[Server Groups]]
* 🎨 [[Formatting]]
* ✍️ [[Placeholders]]
* ✨ [[Animations]]
## Links
* 💻 [GitHub](https://github.com/WiIIiam278/Velocitab)
* 📂 [Download](https://modrinth.com/plugin/velocitab)
* 💬 [Discord Support](https://discord.gg/tVYhJfyDWG)