# Mineroo Minecraft Libraries

Cross-platform Minecraft server integration libraries for Mineroo — connecting Paper/Spigot servers and Velocity proxies to the Mineroo platform.

## Modules

### `common`
Shared components used by both Paper and Velocity modules:
- **HTTP client** — authenticated API communication with Mineroo backend
- **User info cache** — in-memory caching of player profiles
- **Message manager** — localized message resolution
- **Network abstraction** — unified interface for direct HTTP and proxy-mode communication

### `paper`
PaperMC plugin (`MinerooCore-Paper.jar`):
- Player-to-MineRoo account binding
- **Vault economy integration** — server currencies synced to Mineroo platform
- **PlaceholderAPI expansion** — `%mineroo_*` placeholders
- Online player reporting (optional, privacy-aware)
- Player join/leave bind validation
- Proxy network support (Velocity forwarding)

### `velocity`
Velocity proxy plugin (`mineroo-velocity.jar`):
- Cross-server player bind state management
- Plugin-message channel registration (`mineroo:main`)
- MOTD token handling for server-server communication
- Centralized bind listener for proxy-level flows

## Requirements

| Module | Runtime | JDK |
|---|---|---|
| `paper` | Paper 1.21.10+ | 21 |
| `velocity` | Velocity 3.x | 21 |

**Optional soft dependencies:**
- [Vault](https://github.com/MilkBowl/VaultAPI) — economy features
- [PlaceholderAPI](https://github.com/PlaceholderAPI/PlaceholderAPI) — placeholders

## Build

```bash
./gradlew shadowJar
```

Artifacts:
- `paper/build/libs/MinerooCore-Paper.jar`
- `velocity/build/libs/velocity-*.jar` (via submodule build)

## Configuration

### Paper
Place `MinerooCore-Paper.jar` in `plugins/` and edit `plugins/MinerooCore/config.yml`:

```yaml
server:
  bind:
    bind-token: "your-server-token-from-mineroo-panel"
test:
  api-hostname: "https://api.mineroo.online"
proxy:
  use-velocity: false
currencies:
  enable: true
privacy:
  show-online-players: true
```

### Velocity
Place `mineroo-velocity.jar` in `plugins/` and edit `plugins/mineroo-velocity/config.yaml`.

## Features

### Player Bind
Players link their Minecraft UUID to a Mineroo account via `/mineroo bind`.

### Economy Sync
When Vault is present and `currencies.enable: true`:
- Server currencies are read from Vault
- Changes are queued to Mineroo backend
- Players earn/spend platform-wide currency

### Placeholders
Available when PlaceholderAPI is installed:
- `%mineroo_username%`
- `%mineroo_currency_<slug>%`
- More via `MinerooExpansion`

## Project Structure

```
minecraft-libraries/
├── common/
│   └── src/main/java/online/mineroo/common/
│       ├── cache/          # Caching utilities
│       ├── request/        # HTTP client & DTOs
│       ├── HttpNetworkService.java
│       ├── MessageManager.java
│       └── NetworkServiceInterface.java
├── paper/
│   └── src/main/java/online/mineroo/paper/
│       ├── commands/       # /mineroo command tree
│       ├── economy/        # Vault economy bridge
│       ├── expansions/     # PlaceholderAPI expansion
│       ├── listeners/      # Bukkit event handlers
│       ├── tasks/          # Scheduled tasks
│       ├── MinerooCore.java
│       └── Config.java
├── velocity/
│   └── src/main/java/online/mineroo/velocity/
│       ├── listeners/
│       ├── MinerooVelocity.java
│       └── Config.java
└── build.gradle.kts / settings.gradle.kts
```

## License

[Apache-2.0](LICENSE)