Skip to content

Commit

Permalink
Merge pull request #79 from EssentialsX/misc/merge-wiki
Browse files Browse the repository at this point in the history 
Merge wiki content and history
  • Loading branch information
@JRoy
JRoy committed Oct 31, 2022
2 parents be93b92 + 1a1a78a commit 397313d
Show file tree
Hide file tree
Showing 48 changed files with 1,362 additions and 4 deletions.
3 changes: 0 additions & 3 deletions .gitmodules
View file

This file was deleted.

1 change: 0 additions & 1 deletion pages/wiki
Submodule wiki deleted from f55d79
18 changes: 18 additions & 0 deletions pages/wiki/BannerMeta.md
View file
@@ -0,0 +1,18 @@
# BannerMeta
BannerMeta lets you create custom flag designs for banners and shields. Each banner can have unlimited patterns and patterns listed first will show underneath patterns listed later.

![BannerMeta example](https://user-images.githubusercontent.com/1917406/63939958-5f891000-ca60-11e9-8025-32808f018757.png)

## Base Color
Base color should be the first thing listed for a banner. It will be displayed as RGB. Base color will show below all patterns.

Note that on 1.13 and above, you don't need to specify a base color for banners, as banners already have a base color.

## Patterns
Patterns will be listed after the base color and will include the type with the color listed after a comma.
[PatternTypes can be found here.](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/block/banner/PatternType.html)

### Example Syntax
An example banner:

`- BANNER:13 1 basecolor:11685080 SQUARE_TOP_RIGHT:14188339`
54 changes: 54 additions & 0 deletions pages/wiki/Color-Permissions.md
View file
@@ -0,0 +1,54 @@
# Color Permissions

<!-- alternative title: Colo_u_r Permissions -->

EssentialsX includes permissions that let you control the individual formatting codes players can use in some commands.

This works for the following:
* Sending a PM with `/msg`: `essentials.msg.<suffix>`
* Sending mails with `/mail`: `essentials.mail.<suffix>`
* Setting your own nickname with `/nick`: `essentials.nick.<suffix>`
* Sending chat messages **(requires EssentialsX Chat)**: `essentials.chat.<suffix>`
* Editing a sign with `/editsign`: `essentials.editsign.<suffix>`
* Colors on signs **(requires color signs to be enabled)**: `essentials.signs.<suffix>`

Below is a list of valid permissions suffixes. Note that some codes are only available on EssentialsX 2.16.1.169 and
above:

| Suffix | Color codes | EssentialsX version |
|------------------|---------------------------------------------------|---------------------|
| `color` (group) | `&0 &1 &2 &3 &4 &5 &6 &7 &8 &9 &a &b &c &d &e &f` | All versions |
| `format` (group) | `&l &m &n &o &r` | All versions |
| `magic` (group) | `&k` | All versions |
| `rgb` | `&#RRGGBB` | 2.18.0+ |
| `black` | `&0` | 2.16.1.169+ |
| `dark_blue` | `&1` | 2.16.1.169+ |
| `dark_green` | `&2` | 2.16.1.169+ |
| `dark_aqua` | `&3` | 2.16.1.169+ |
| `dark_red` | `&4` | 2.16.1.169+ |
| `dark_purple` | `&5` | 2.16.1.169+ |
| `gold` | `&6` | 2.16.1.169+ |
| `gray` | `&7` | 2.16.1.169+ |
| `dark_gray` | `&8` | 2.16.1.169+ |
| `blue` | `&9` | 2.16.1.169+ |
| `green` | `&a` | 2.16.1.169+ |
| `aqua` | `&b` | 2.16.1.169+ |
| `red` | `&c` | 2.16.1.169+ |
| `light_purple` | `&d` | 2.16.1.169+ |
| `yellow` | `&e` | 2.16.1.169+ |
| `white` | `&f` | 2.16.1.169+ |
| `bold` | `&l` | 2.16.1.169+ |
| `strikethrough` | `&m` | 2.16.1.169+ |
| `underline` | `&n` | 2.16.1.169+ |
| `italic` | `&o` | 2.16.1.169+ |
| `reset` | `&r` | 2.16.1.169+ |

The individual permissions take priority over the "group" permissions. For example, if you set `essentials.nick.color`
to `true` then set `essentials.nick.black` to `false`, players will be able to set their nicknames to any color
except black.

## Nicknames

If you want players to be able to change the color of their nickname but not the text itself, set the permission
`essentials.nick.changecolors` to `true`. This will let them use color codes in their nickname, but the text will still
have to match their own username.
46 changes: 46 additions & 0 deletions pages/wiki/Command-Cooldowns.md
View file
@@ -0,0 +1,46 @@
**This feature was added in [build 369](https://ci.ender.zone/job/EssentialsX) ([09acbcd](https://github.com/drtshock/Essentials/commit/09acbcdb05f34e0043116f1866904b0ff0f03ddd)).**
_Requested in [#110](/drtshock/Essentials/issues/110). PR in [#692](/drtshock/Essentials/pull/692)._

This feature introduces the highly demanded ability to apply cooldowns to commands. If you want to limit how often a player can `/feed` or go `/home`, all you have to do is simply add that command to the config:

```yaml
command-cooldowns:
feed: 10 # 10 seconds
home: 70 # 1 minute 10 seconds
```

**Advanced users** are able to apply more control to their command matching by using wildcards. Wildcards are specified using asterisks '*'. For example, to match all commands that include the word `potato`, you would simply wrap the world potato in asterisks:
```yaml
command-cooldowns:
'*potato*': 30
```

**NOTE**: Due to YAML's design, any command starting with * must be wrapped in quotation marks (single or double, ' ")

For **highly technical users** who understand Regex (Regular Expressions), this feature also supports Regex. In order for EssentialsX to begin interpreting regex, the command must start with a caret '^'. Followed by the explicit regex pattern that EssentialsX should match.

```yaml
command-cooldowns:
'^^ban([^ip])?( .*)?': 30 # match any ban command that isn't `banip`.
```

**NOTE**: The leading caret is not part of the regex and is simply removed when parsing the regex. So `'^ban([^ip])?( .*)?'` actually becomes `'ban([^ip])?( .*)?'`.

**NOTE 2**: If a plugin command starts with a caret e.g. `^mycommand`, then the caret must be escaped using a blackslash '\' to prevent EssentialsX from interpreting the command as Regex.

# Persistence
By default, EssentialsX will store all existing cooldowns across server sessions. This means when the server shuts down the player cooldowns will be saved and loaded for the next startup. This is especially useful for cooldowns that last any more than a few minutes.

However, this feature can be disabled, making EssentialsX store cooldowns only until the server shuts down. Resetting all cooldowns when the server starts up.

To disable command cooldown persistence simply apply the following change to your config:
```yaml
command-cooldown-persistence: false
```

**NOTE:** If the `command-cooldown-persistence` is not present in the config then it can be added anywhere in the config, as long as it is not indented.

# Bypass
**This feature was added in build 377**

Users can be set to bypass all command cooldowns by giving them the `essentials.commandcooldowns.bypass` permission.
202 changes: 202 additions & 0 deletions pages/wiki/Common-Issues.md
View file
@@ -0,0 +1,202 @@
# Common issues with EssentialsX

## Signs don't work
In your `plugins/Essentials/config.yml` file, you need to uncomment the lines under `enabledSigns` for each type of sign by removing the `#` before it:
```yaml
enabledSigns:
#- color
- balance
#- buy
```
In this example, the `[balance]` sign is enabled but the `[buy]` sign is not.
Note that enabling `color` means that players will be allowed to use color codes in the sign text, but still requires that another sign type is enabled.

## EssentialsX overrides a command from Spigot or another plugin
**Related issues: [#1458](/EssentialsX/Essentials/issues/1458)**
You can create an alias for commands using Bukkit's `commands.yml` file, which should be in your server root.

The example below does the following:
* Overrides `/gc` with [spark](https://github.com/lucko/spark)'s `/profiler` command
* Overrides `/tell` with the [vanilla `/tell`](https://minecraft.gamepedia.com/Commands/tell) command
* Forces `/msg` to run EssentialsX's `/msg` command
```yaml
aliases:
gc:
- "spark:profiler $1-"
tell:
- "minecraft:tell $1-"
msg:
- "essentials:msg $1-"
```

See the [Bukkit wiki page](https://bukkit.gamepedia.com/Commands.yml#aliases) for more information.

## Another plugin is overriding an EssentialsX command
Typically, if EssentialsX finds another plugin providing a command with the same name as one of EssentialsX's own commands, it will try and hand over that command to the other plugin. However, you can force EssentialsX to handle commands that are also provided by another plugin using the [`overridden-commands` section](https://github.com/EssentialsX/Essentials/blob/2.x/Essentials/src/main/resources/config.yml#L162) of your `config.yml`. This will tell EssentialsX not to "give up" the command to the other plugin.

For example, to force EssentialsX to handle the `/msg` command instead of passing it over to another plugin, your section should look like this:
```yaml
overridden-commands:
- msg
```

Note that in some cases, you may also need to alias the command to the `essentials:` version of the command. [See above](https://github.com/EssentialsX/Essentials/wiki/Common-Issues#essentialsx-overrides-a-command-from-spigot-or-another-plugin) for details. In addition, if you have a plugin running on your proxy ([BungeeCord](https://www.spigotmc.org/wiki/bungeecord/)/[Waterfall](https://github.com/PaperMC/Waterfall) or [Velocity](https://velocitypowered.com)), the command may not even reach the server. EssentialsX can't do anything about this - you need to fix this on the proxy.

## Tab completion doesn't work for commands that override an EssentialsX command
**Related issues: [#1384](/EssentialsX/Essentials/issues/1384)**
You can alias the command to the version from the other plugin, which should fix tab complete behaviour - see above.

## I need help with GroupManager! <br /> Where's the updated GroupManager?
EssentialsX does not support GroupManager as it is an outdated and broken plugin. We recommend you switch to [LuckPerms](https://github.com/lucko/LuckPerms) as it is still an actively maintained and regularly updated plugin.

## How do I build EssentialsX?
Once you've ensured you have an up-to-date JDK and Maven installed, you need to build a few different Spigot versions using [Spigot BuildTools](https://www.spigotmc.org/wiki/buildtools/):
```bash
java -jar BuildTools.jar --rev 1.8
java -jar BuildTools.jar --rev 1.8.3
java -jar BuildTools.jar --rev 1.9
java -jar BuildTools.jar --rev 1.9.4
```

This is required to allow EssentialsX's compatibility providers can build against older versions of the Spigot server, and only needs to be done once.

Next, [download or clone EssentialsX](https://github.com/EssentialsX/Essentials), open a terminal in the root of the EssentialsX source and run:
```bash
./gradlew build
```

If this completes with no errors, you will be able to find each plugin jar in the `jars/` directory or, in `build/libs/` inside each module's directory.

## How do I add EssentialsX as a dependency?
### Repositores
Do you want to integrate with EssentialsX in your plugin? You can use the EssentialsX Maven repo to build against EssentialsX's API.

Releases are hosted on the Maven repo at `https://repo.essentialsx.net/releases/`, while snapshots (including dev builds) are hosted at `https://repo.essentialsx.net/snapshots/`.

To add EssentialsX to your build system, you should use the following artifacts:

| Type | Group ID | Artifact ID | Version |
| :-------------- | :-------------- | :---------- | :-------------- |
| Latest release | net.essentialsx | EssentialsX | 2.19.0
| Snapshots | net.essentialsx | EssentialsX | 2.19.1-SNAPSHOT |
| Older releases | net.ess3 | EssentialsX | 2.18.2 |

Note: up until 2.18.2, EssentialsX used the net.ess3 group ID, but starting with 2.19.0 snapshots, the group ID is now net.essentialsx. When updating your plugin, make sure you use the correct group ID.

### Releases
#### Maven
Under `repositories` in your `pom.xml`, you need to add a new `repository` for the EssentialsX CI server:
```xml
<repositories>
...
<repository>
<id>essentials-releases</id>
<url>https://repo.essentialsx.net/releases/</url>
</repository>
<repository>
<id>paper-repo</id>
<url>https://papermc.io/repo/repository/maven-public/</url>
</repository>
</repositories>
```

Next, add EssentialsX as a `dependency` under `dependencies`:
```xml
<dependencies>
...
<dependency>
<groupId>net.essentialsx</groupId>
<artifactId>EssentialsX</artifactId>
<version>2.19.0</version>
<scope>provided</scope>
</dependency>
</dependencies>
```

Make sure the dependency is `provided` - you don't want to include the whole of EssentialsX inside your plugin.

You should now be able to build against EssentialsX's API in your IDE - you may need to reimport your project for this to work.

#### Gradle
First, add the repository to your `build.gradle`:
```groovy
repositories {
maven {
name "essentialsx-releases"
url "https://repo.essentialsx.net/releases/"
}
maven {
name "papermc"
url "https://papermc.io/repo/repository/maven-public/"
}
}
```

Next, add the dependency as a `compileOnly` dependency:
```groovy
dependencies {
...
compileOnly 'net.essentialsx:EssentialsX:2.19.0'
}
```

You should now be able to build against EssentialsX's API in your IDE.

### Snapshots
#### Maven
Under `repositories` in your `pom.xml`, you need to add a new `repository` for the EssentialsX CI server:
```xml
<repositories>
...
<repository>
<id>essentials-snapshots</id>
<url>https://repo.essentialsx.net/snapshots/</url>
</repository>
<repository>
<id>paper-repo</id>
<url>https://papermc.io/repo/repository/maven-public/</url>
</repository>
</repositories>
```

Next, add EssentialsX as a `dependency` under `dependencies`:
```xml
<dependencies>
...
<dependency>
<groupId>net.essentialsx</groupId>
<artifactId>EssentialsX</artifactId>
<version>2.19.1-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
</dependencies>
```

Make sure the dependency is `provided` - you don't want to include the whole of EssentialsX inside your plugin.

You should now be able to build against EssentialsX's API in your IDE - you may need to reimport your project for this to work.

#### Gradle
First, add the repository to your `build.gradle`:
```groovy
repositories {
maven {
name "essentialsx-snapshots"
url "https://repo.essentialsx.net/snapshots/"
}
maven {
name "papermc"
url "https://papermc.io/repo/repository/maven-public/"
}
}
```

Next, add the dependency as a `compileOnly` dependency:
```groovy
dependencies {
...
compileOnly 'net.essentialsx:EssentialsX:2.19.1-SNAPSHOT'
}
```

You should now be able to build against EssentialsX's API in your IDE.

0 comments on commit 397313d

Please sign in to comment.