feat: NickCore v1.0.0 - enterprise nickname plugin for Paper/Folia/Velocity

2026-05-30 21:05:02 -05:00
parent 8a42740875
commit f0b35e89ac
54 changed files with 5393 additions and 0 deletions
--- a/README.MD
+++ b/README.MD
@@ -0,0 +1,149 @@
+# NickCore
+
+**Enterprise Minecraft Nickname Plugin** for Paper 1.21.11, Folia 1.21.11, and Velocity 3.5.0.
+
+![Java 25](https://img.shields.io/badge/Java-25-blue)
+![Paper 1.21.11](https://img.shields.io/badge/Paper-1.21.11-green)
+![Velocity 3.5.0](https://img.shields.io/badge/Velocity-3.5.0-orange)
+
+---
+
+## 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.