Skip to content

Commit f565d24

Browse files
RhythmicSysRhythmicSys
committed
Update README and move username protection options under the nickname protection options
1 parent 5f5367c commit f565d24

File tree

4 files changed

+253
-79
lines changed

4 files changed

+253
-79
lines changed

‎README.md‎

Lines changed: 230 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -1,90 +1,262 @@
11
# Simple Nicks
22

3-
A standalone nickname plugin that supports Mini-Message.
3+
A standalone nickname plugin that supports [MiniMessage](https://docs.advntr.dev/minimessage/)
44

5-
Mini-Message comes prepackaged with Paper and all forks of Paper support Mini-Message.
5+
MiniMessage comes prepackaged with Paper, and all forks of Paper support MiniMessage.
6+
7+
This plugin now uses **MySQL** or **SQLite** for saving nicknames, allowing faster indexing and improved nickname protection.
8+
9+
10+
## Features
11+
12+
- Set and reset nicknames with MiniMessage formatting.
13+
- Save nicknames for later use.
14+
- SQL-based storage (MySQL or SQLite).
15+
- Nickname protection system:
16+
- Protect nicknames of players who are online
17+
- Protect nicknames of players who are offline
18+
- Protect usernames of players from being used as nicknames
19+
- Configurable options for if nickname functionality requires permissions
620

721
## Commands
822

23+
### Player Commands
924

25+
`/nick set <nickname>`
26+
- Sets your nickname using MiniMessage tags (`<gray>`, `<gradient:red:blue>`, etc.).
1027

11-
`/nick set <nickname> [player]`
28+
`/nick save [nickname]`
29+
- Saves your current nickname for later use by just doing `/nick save`
30+
- You can also provide a nickname to save directly
1231

13-
- Sets the nickname of the player.
14-
- Uses Mini-Message Tags such as `<gray>` and `<gradient:red:green>`
15-
- Allows users with permission `simplenick.admin` to change the nickname of another player using the optional [player]
16-
argument.
32+
`/nick delete <nickname>`
33+
- Deletes one of your saved nicknames.
1734

18-
`/nick save [player]`
35+
`/nick reset`
36+
- Resets your nickname to your original username.
1937

20-
- Saves the player's current nickname for future use
38+
`/nick who <nickname>`
39+
- Displays the username of the player with the supplied nickname.
2140

22-
`/nick delete [player|nick] <nick>`
41+
`/nick help`
42+
- Displays help text.
2343

24-
- Deletes the specified nickname from the player's saved names
44+
### Admin Commands
2545

26-
`/nick reset [player]`
46+
`/nick admin set <username> <nickname>`
47+
- Sets another player’s nickname, using the **admin’s permissions** for formatting.
2748

28-
- Sets the nickname of the player back to the original username, unformatted.
29-
- Allows users with permission `simplenick.admin` to reset the nickname of another player using the optional [player]
30-
argument.
49+
`/nick admin reset <username>`
50+
- Resets another player’s nickname.
3151

32-
`/nick reload`
52+
`/nick admin delete <username> <nickname>`
53+
- Deletes a saved nickname from a player’s list.
3354

55+
`/nick admin lookup <username>`
56+
- Displays a player’s current nickname and all saved nicknames.
57+
58+
`/nick reload`
3459
- Reloads the configuration and locale.
3560

36-
`/nick help`
61+
## Permissions
3762

38-
- Provides help text.
63+
### Player Permissions
3964

40-
### Admin Permissions
65+
| Permission | Description | Default |
66+
|--------------------------|--------------------------------------------------|---------|
67+
| `simplenick.nick.set` | Set your own nickname. | `op` |
68+
| `simplenick.nick.reset` | Reset your own nickname. | `op` |
69+
| `simplenick.nick.delete` | Delete one of your saved nicknames. | `op` |
70+
| `simplenick.nick.who` | Use `/nick who <nickname>` to look up usernames. | `true` |
4171

42-
| Permission | Admin permission to: |
43-
|:-------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
44-
| `simplenick.bypass.` | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
45-
| `simplenick.bypass.username` | Use another player's username as their own nickname on the server |
46-
| `simplenick.bypass.length` | Set a nickname longer than the max character limit |
47-
| `simplenick.bypass.regex` | Set a nickname that doesn't match the configured regex |
48-
| ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ | ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ |
49-
| `simplenick.reload` | Reload the plugin configuration and locale |
50-
| ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ | ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓ |
51-
| `simplenick.admin.` | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
52-
| `simplenick.admin.reset` | Reset a target player's nickname |
53-
| `simplenick.admin.save` | Save a target player's nickname to **the target player's** saved nicknames |
54-
| `simplenick.admin.delete` | Delete a target player's saved name from **the target player's** <br>list of saved nicknames |
55-
| `simplenick.admin.restrictive` | Set a target player's nickname, only using the formats the target player has permissions for<br/>(This is a very niche permission, likely not what most servers are looking for) |
56-
| `simplenick.admin.basic` | Set a target player's nickname, using the formats the Admin has permission to use<br>(This is the permission most servers will need for admins) |
57-
| `simplenick.admin.full` | Set a target player's nickname with zero regard for formatting, full permission for all formatting. <br>(Not recommended) |
72+
**Color Permissions**
5873

59-
### Player Permissions
74+
| Permission | Description | Default |
75+
|-----------------------------|----------------------------------------------|---------|
76+
| `simplenick.color.basic` | Use color tags (`<red>`, `<color:#aabbcc>`). | `op` |
77+
| `simplenick.color.gradient` | Use gradient tags (`<gradient:red:blue>`). | `op` |
78+
| `simplenick.color.rainbow` | Use `<rainbow>`. | `op` |
79+
| `simplenick.color.reset` | Use `<reset>`. | `op` |
80+
81+
**Format Permissions**
82+
83+
| Permission | Description | Default |
84+
|-----------------------------------|-----------------------|---------|
85+
| `simplenick.format.bold` | Use `<b>`/`</b>`. | `op` |
86+
| `simplenick.format.italic` | Use `<i>`/`</i>`. | `op` |
87+
| `simplenick.format.underline` | Use `<u>`/`</u>`. | `op` |
88+
| `simplenick.format.strikethrough` | Use `<st>`/`</st>`. | `op` |
89+
| `simplenick.format.obfuscated` | Use `<obf>`/`</obf>`. | `op` |
90+
91+
### Admin Permissions
92+
93+
| Permission | Description | Default |
94+
|---------------------------|------------------------------------------------|---------|
95+
| `simplenick.admin.set` | Set another player’s nickname. | `op` |
96+
| `simplenick.admin.reset` | Reset another player’s nickname. | `op` |
97+
| `simplenick.admin.delete` | Delete a saved nickname from another player. | `op` |
98+
| `simplenick.admin.lookup` | Lookup a player’s current and saved nicknames. | `op` |
99+
| `simplenick.reload` | Reload plugin configuration and locale. | `op` |
60100

61-
| Permission | Permission to: |
62-
|:---------------------------------------|:---------------------------------------------------------|
63-
| `simplenick.nick` | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
64-
| `simplenick.nick.set` | Set own nickname |
65-
| `simplenick.nick.reset` | Reset own nickname |
66-
| `simplenick.nick.save` | Save current nickname for later use |
67-
| `simplenick.nick.delete` | Delete a previously saved nickname |
68-
| `simplenick.nick.color` | Use color formatting tags (`<color:#aabbcc>` or `<red>`) |
69-
| `simplenick.nick.gradient` | Use gradient formatting tags (`<gradient:red:blue>`) |
70-
| `simplenick.nick.rainbow` | Use rainbow formatting tags (`<rainbow>`) |
71-
| `simplenick.nick.format.` | ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
72-
| `simplenick.nick.format.reset` | Use the `<reset>` formatting tags |
73-
| `simplenick.nick.format.underline` | Use the `<u>`,`</u>` formatting tags |
74-
| `simplenick.nick.format.strikethrough` | Use the `<st>`,`</st>` formatting tags |
75-
| `simplenick.nick.format.bold` | Use the `<b>`,`</b>` formatting tags |
76-
| `simplenick.nick.format.obsfucated` | Use the `<obf>`,`</obf>` formatting tags |
101+
### Bypass Permissions
77102

103+
| Permission | Description | Default |
104+
|-------------------------------------|------------------------------------------------------|---------|
105+
| `simplenick.bypass.username` | Use another player’s username as a nickname. | `false` |
106+
| `simplenick.bypass.length` | Set nicknames longer than the configured max length. | `false` |
107+
| `simplenick.bypass.regex` | Set nicknames that don’t match the configured regex. | `false` |
108+
| `simplenick.bypass.nick-protection` | Bypass nickname protection (online/offline/expires). | `false` |
78109

79110
## PlaceholderAPI
80111

81-
- Download the `player` ecloud expansion for Placeholder API
82-
- Use `%player_displayname%`
112+
All placeholders now start with **`simplenick`** for consistency.
113+
114+
| Placeholder | Description |
115+
|----------------------------------|--------------------------------------------------------|
116+
| `%simplenick_nickname%` | Player’s parsed nickname. |
117+
| `%simplenick_mininick%` | Player’s raw MiniMessage nickname (`<red>Name</red>`). |
118+
| `%simplenick_prefixed-nickname%` | Nickname with configured prefix applied. |
119+
| `%simplenick_prefixed-mininick%` | Raw MiniMessage nickname with prefix. |
120+
121+
---
122+
123+
## Configuration
124+
125+
### MySQL
126+
If you're using MySQL you know what to put here. Plugin uses SQLite by default, so you will need to enable MySQL if you are going to use it
127+
128+
### Nickname Length
129+
This is the max length that someone's nickname can be *after* the colors and formats have been figured out. So, if you're doing a nickname like `<gradient:red:green:white:yellow>ThisIs</gradient><gradient:blue:white:green>AConvoluted</gradient><rainbow>Exam</color><b>ple</b>` the text that will be checked will be `ThisIsAConvolutedExample`. It's not recommended to set the value below 3, as there may be unintended side effects.
130+
131+
### Nickname Regex
132+
This is the allowed characters in a nickname. The default allows only alphanumeric characters and underscores `[A-Za-z0-9_]+` - you can add additional characters into this, use a resource like https://regexr.com/ to make sure your regex properly parses
133+
134+
### Require Permission
135+
136+
These set whether or not specific functionalities require a permission. If you don't know what a permissions plugin is, and you just want the plugin to work, you can set the functions you want to 'false'. If you do know what permissions are and how to use them, you probably don't need this section.
137+
138+
**Nick**
139+
Gives functionality for:
140+
- `/nick set`
141+
- `/nick reset`
142+
- `/nick save`
143+
Allows a player to change the name they appear as.
144+
145+
**Color**
146+
Gives functionality for color tags, like `<red>`, `<#aabbcc>`, `<rainbow>`, `<gradient:color1:color2>`, and `<reset>`
147+
Allows a player to change the name they appear as, and the color of their name.
148+
149+
**Format**
150+
Gives functionality for formatting tags, like `<u>` (underline), `<i>` (*italic*), `<b>` (**bold**), `<st>` (~~strikethrough~~), and `<obf>` (ō̵̬b̵̧̛f̷̩̋u̵̳͂ş̸̓c̷̥̈́a̵͇͂t̸̯͋e̸͎̚d̷̟͝)
151+
152+
**Who**
153+
Gives access to `/nick who <name>` which shows which username is associated with a specific nickname.
154+
155+
### Nickname Protection
156+
157+
Allows protecting nicknames that are already in use. This does not protect saved nicknames or protect nicknames from being saved.
158+
159+
**Online Protection**
160+
Only prevents a player from taking the nickname of someone who is currently online. Allows people to use nicknames of people who are offline.
161+
162+
**Offline Protection**
163+
Prevents players from using nicknames that someone else is actively using, regardless of if they're online or offline, provided the nickname expiry has not been reached.
164+
165+
**Offline Protection Expires**
166+
Time in days someone needs to be away before their nickname protection expires, set to `-1` if you do not want nickname protection to ever expire, but I wouldn't recommend that.
167+
168+
**Username Protection**
169+
Prevents players from nicknaming themselves someone's username. Only checks against players who have actually logged into the server.
170+
171+
**Username Protection Expires**
172+
This value controls the number of days someone needs to be offline before their username is considered allowed to be used as a nickname. Use `-1` if you do not want the protection ever to expire
173+
174+
### Max Saves
175+
Controls how many nicknames players can save, there is not currently an override permission for this, it is applied for all players with save permissions
176+
177+
### Tablist Nick
178+
Alters the tab list to use the current nicknames of players. If you have any plugin that already can handle this, I would suggest you use that, or use my other plugin [Simple Custom Tab List](https://modrinth.com/plugin/simple-custom-tablist) because this option is very limited and prone to issues with other plugins. If you have a very simple server setup and you just want nicknames to show on tab list this will work, but if you have geyser, or other plugins that might alter scoreboard and other random stuff, you're gonna want a separate plugin to handle the tablist
179+
180+
### Nickname Prefix
181+
Sets what the prefix of nicknames should be, used in placeholder `%simplenick_prefixed-nickname%` and `%simplenick_prefixed-mininick%`, as well as the display name of the player.
182+
### `config.yml`
183+
184+
```yaml
185+
mysql:
186+
enabled: false
187+
ip: "localhost:3306"
188+
name: simplenicks
189+
username: username1
190+
password: badpassword!
191+
192+
# The max amount of characters a nickname should be, not including formatting
193+
# (so a name like <red>Billy<yellow>Bob would only count 'BillyBob' - and would be 8 characters)
194+
# Setting this number to any number below "3" could cause unintended side effects
195+
max-nickname-length: 30
196+
197+
# The regex of valid final nickname characters.
198+
# Be warned that putting non-alphanumeric characters may result in issues with other plugins and other unintended side effects
199+
nickname-regex: "[A-Za-z0-9_]+"
200+
201+
# What should require permission set by a permission plugin?
202+
require-permission:
203+
nick: true
204+
color: true
205+
format: true
206+
who: false
207+
208+
# Blocks certain names from being used as nicknames
209+
# Expiration times are in days, setting to -1 will make it so it never expires
210+
nickname-protection:
211+
username:
212+
enabled: true
213+
expires: 30
214+
online:
215+
enabled: false
216+
offline:
217+
enabled: false
218+
expires: 30
219+
220+
# How many nicknames can be saved?
221+
max-saves: 5
222+
223+
# Should names be changed in tablist?
224+
# (Keep this false if you use any other tablist plugin, there are placeholder API placeholders to use on those)
225+
tablist-nick: false
226+
227+
# What prefix should be given for players who have a nickname? put "" if you want no prefix
228+
nickname-prefix: ""
229+
230+
# Development option, this will flood your logs, discouraged from enabling unless asked
231+
debug-mode: false
232+
```
233+
234+
---
235+
236+
## Migration from Older Versions
237+
238+
If you are upgrading from a version of SimpleNicks **before SQL support**:
239+
240+
- **Data Storage:**
241+
- Old versions stored nicknames in YML or using the PersistentDataContainer (PDC).
242+
- New versions use **MySQL or SQLite**. Existing data will be migrated automatically.
243+
- **Commands:**
244+
- Admin commands now live under `/nick admin` instead of sharing player command structure.
245+
- `/nick save` can now accept arguments (`/nick save <nickname>`).
246+
- **Permissions:**
247+
- Color and format permissions were moved into their own nodes (`simplenick.color.*` and `simplenick.format.*`).
248+
- Color and format can now be allowed without permissions, check new config options
249+
- `simplenick.admin.restrictive`, `simplenick.admin.basic` and `simplenick.admin.full` were **removed.** The permission is now `simplenick.admin.set`
250+
- Admin nickname setting always uses **admin’s own permissions** now. (Previously 'admin basic' functionality)
251+
- `simplenick.admin.save` was **removed** - since this is now using brigadier, you can use
252+
- **PlaceholderAPI:**
253+
- Placeholders were renamed for consistency.
254+
- `%simplenicks_mininick%` → `%simplenick_mininick%`
255+
- `%simplenicks_nickname%` → `%simplenick_nickname%`
256+
- New prefixed variants: `%simplenick_prefixed-nickname%`, `%simplenick_prefixed-mininick%`.
257+
- Previously the placeholder always included the prefix if you had one set, now only the prefixed variants will. This is useful if you don't want the prefix in some areas but want it in others.
83258

84-
- If you have a specific setup that needs the minimessage formatting before it has been parsed, i.e. the
85-
`"<red>Nickname</red>"` version, you can use `%simplenicks_mininick%`
86-
- This won't be necessary for most users though, the previous one will work best.
87259

88260
## TODO
89261

90-
- Create a `/nick whois` or similar command to determine "who is the player(s) with this nickname".
262+
[ ] - Add a nickname blacklist

0 commit comments

Comments
 (0)