From b7d77e61a0a9b36f3db4d58746a4395e22d9f810 Mon Sep 17 00:00:00 2001
From: hermes_bot <hermes@mrxzx.info>
Date: Wed, 3 Jun 2026 02:00:06 +0800
Subject: [PATCH] docs: add comprehensive README for minecraft-libraries

- cross-platform module overview (common, paper, velocity)
- requirements matrix with JDK 21
- build instructions via Gradle shadowJar
- configuration examples for both Paper and Velocity
- feature list: player bind, economy sync, placeholders
- project structure tree
---
 README.md | 120 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 119 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 48e9280..7b9af1a 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,120 @@
-# mineroo-bind-velocity
+# 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)
-- 
2.49.1