# 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.