150 lines
5.3 KiB
Markdown
150 lines
5.3 KiB
Markdown
# NickCore
|
|
|
|
**Enterprise Minecraft Nickname Plugin** for Paper 1.21.11, Folia 1.21.11, and Velocity 3.5.0.
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Nickname System** — Approved names, random names, custom names (permission-gated)
|
|
- **Rank System** — Configurable visual ranks with MiniMessage prefixes/suffixes
|
|
- **Skin System** — Multi-tier cache (memory → DB → Mojang API), rate-limited
|
|
- **GUI System** — Paginated inventory menus with click cooldowns
|
|
- **PlaceholderAPI** — 14 placeholders served from in-memory cache
|
|
- **Velocity Sync** — Cross-server nickname/rank/skin synchronization
|
|
- **Folia Support** — Region/Entity/Global scheduler compliance
|
|
- **Security** — Homoglyph detection, impersonation prevention, input sanitization
|
|
- **Database** — SQLite/MySQL/MariaDB with HikariCP pooling and schema migration
|
|
- **Audit Logging** — Full history of all nickname changes
|
|
|
|
## Architecture
|
|
|
|
```
|
|
nickcore/
|
|
├── nickcore-common/ # Shared models, DTOs, validation
|
|
├── nickcore-paper/ # Paper + Folia plugin (single JAR)
|
|
└── nickcore-velocity/ # Velocity proxy plugin
|
|
```
|
|
|
|
## Building
|
|
|
|
```bash
|
|
./gradlew build
|
|
```
|
|
|
|
Artifacts:
|
|
- `nickcore-paper/build/libs/NickCore-Paper-1.0.0.jar`
|
|
- `nickcore-velocity/build/libs/NickCore-Velocity-1.0.0.jar`
|
|
|
|
## Requirements
|
|
|
|
- Java 25+
|
|
- Paper 1.21.11 or Folia 1.21.11
|
|
- Velocity 3.5.0 (optional, for multi-server)
|
|
|
|
## Installation
|
|
|
|
1. Place `NickCore-Paper-1.0.0.jar` in your server's `plugins/` folder
|
|
2. (Optional) Place `NickCore-Velocity-1.0.0.jar` in your Velocity proxy's `plugins/` folder
|
|
3. Start the server to generate configuration files
|
|
4. Edit configuration files in `plugins/NickCore/`
|
|
5. Run `/nick reload` to apply changes
|
|
|
|
## Commands
|
|
|
|
| Command | Permission | Description |
|
|
|---------|-----------|-------------|
|
|
| `/nick` | `nickcore.use` | Open the main GUI |
|
|
| `/nick <name>` | `nickcore.name.custom` | Set custom nickname |
|
|
| `/nick random` | `nickcore.name.random` | Generate random nickname |
|
|
| `/nick reset` | `nickcore.reset` | Reset to real identity |
|
|
| `/nick rank [id]` | `nickcore.rank.select` | Select visual rank |
|
|
| `/nick skin [name]` | `nickcore.skin.select` | Change skin |
|
|
| `/nick gui` | `nickcore.use` | Open GUI explicitly |
|
|
| `/nick reload` | `nickcore.reload` | Reload configuration |
|
|
| `/nick info <player>` | `nickcore.info` | View player nick info |
|
|
| `/nick force <player> <nick>` | `nickcore.force` | Force nickname on player |
|
|
| `/nick clear <player>` | `nickcore.clear` | Clear player's nickname |
|
|
|
|
## Permissions
|
|
|
|
| Permission | Default | Description |
|
|
|-----------|---------|-------------|
|
|
| `nickcore.use` | `true` | Access `/nick` |
|
|
| `nickcore.name.custom` | `op` | Enter custom nicknames |
|
|
| `nickcore.name.select` | `true` | Select from approved list |
|
|
| `nickcore.name.random` | `true` | Generate random nicknames |
|
|
| `nickcore.rank.select` | `false` | Access rank selection |
|
|
| `nickcore.rank.<id>` | `false` | Per-rank permissions |
|
|
| `nickcore.skin.select` | `false` | Access skin selection |
|
|
| `nickcore.skin.keep` | `true` | Keep current skin option |
|
|
| `nickcore.reset` | `true` | Reset identity |
|
|
| `nickcore.admin` | `op` | Admin features |
|
|
| `nickcore.reload` | `op` | Reload configuration |
|
|
| `nickcore.bypass` | `op` | Bypass restrictions |
|
|
| `nickcore.force` | `op` | Force nicknames |
|
|
| `nickcore.info` | `op` | View player info |
|
|
| `nickcore.clear` | `op` | Clear nicknames |
|
|
|
|
## PlaceholderAPI
|
|
|
|
| Placeholder | Description |
|
|
|------------|-------------|
|
|
| `%nickcore_nick%` | Current nickname |
|
|
| `%nickcore_real_name%` | Real player name |
|
|
| `%nickcore_rank%` | Visual rank name |
|
|
| `%nickcore_rank_prefix%` | Rank prefix |
|
|
| `%nickcore_rank_suffix%` | Rank suffix |
|
|
| `%nickcore_skin%` | Applied skin name |
|
|
| `%nickcore_is_nicked%` | Whether player is nicked |
|
|
| `%nickcore_display_name%` | Effective display name |
|
|
| `%nickcore_original_name%` | Original player name |
|
|
|
|
## Configuration Files
|
|
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `config.yml` | General settings, chat format, security |
|
|
| `database.yml` | Database connection and pooling |
|
|
| `messages.yml` | Player-facing messages (MiniMessage) |
|
|
| `ranks.yml` | Rank definitions |
|
|
| `skins.yml` | Pre-configured skins |
|
|
| `names.yml` | Approved nickname pool |
|
|
|
|
## Integrations
|
|
|
|
- **PlaceholderAPI** — Soft dependency, 14 placeholders
|
|
- **LuckPerms** — Permission-based rank filtering
|
|
- **TAB** — Tablist prefix/suffix updates
|
|
- **Velocity** — Cross-server synchronization
|
|
- **EssentialsX** — Compatible display names
|
|
- **HuskChat** — Compatible via PlaceholderAPI
|
|
|
|
## Security
|
|
|
|
- Unicode homoglyph detection
|
|
- Invisible/zero-width character blocking
|
|
- Levenshtein-based impersonation prevention
|
|
- MiniMessage injection sanitization
|
|
- SQL injection prevention (prepared statements)
|
|
- Velocity packet validation with protocol versioning
|
|
|
|
## Performance
|
|
|
|
- ConcurrentHashMap-based caches (lock-free reads)
|
|
- Pre-computed placeholder values (zero DB hits during resolution)
|
|
- Deduplicating skin fetcher (one request per skin)
|
|
- Rate-limited Mojang API access
|
|
- HikariCP connection pooling
|
|
- Virtual threads for database operations
|
|
- ViewerUnaware chat renderer (single render per message)
|
|
- Scoreboard team caching (no redundant updates)
|
|
|
|
## License
|
|
|
|
All rights reserved.
|