chore: Support Velocity in Debug

4 files changed, 379 insertions, 2 deletions

diff --git a/docker/README.md b/docker/README.md
new file mode 100644
index 0000000..9efe09e
--- /dev/null
+++ b/docker/README.md
@@ -0,0 +1,214 @@
+# LunaticChat Docker Development Environment
+
+This directory contains Docker Compose configuration for testing LunaticChat with Velocity proxy integration.
+
+## Architecture
+
+```
+┌─────────────────┐
+│  Minecraft      │
+│  Client         │
+│  localhost:25577│
+└────────┬────────┘
+         │
+         v
+┌─────────────────┐
+│  Velocity       │
+│  Proxy          │
+│  Port: 25577    │
+│  + LunaticChat  │
+│    (Velocity)   │
+└────────┬────────┘
+         │
+         v
+┌─────────────────┐
+│  Paper Server   │
+│  minecraft:25565│
+│  + LunaticChat  │
+│    (Paper)      │
+└─────────────────┘
+```
+
+## Requirements
+
+- Docker
+- Docker Compose
+- Gradle (for building plugins)
+
+## Quick Start
+
+```bash
+# Build plugins and start containers
+./x start
+
+# View Minecraft server logs
+./x logs
+
+# View Velocity proxy logs
+./x vlogs
+
+# Restart containers
+./x restart
+
+# Stop containers
+./x stop
+
+# Clean up (remove volumes)
+./x clean
+
+# Access RCON
+./x rcon
+```
+
+## Configuration
+
+### LunaticChat Paper Plugin
+
+Configuration file: `docker/plugins/LunaticChat/config.yml`
+
+Key settings:
+- `features.velocityIntegration.enabled: true` - Enables Velocity integration
+- `debug: true` - Enables debug logging
+
+### Velocity Proxy
+
+Configuration file: `docker/velocity.toml`
+
+Key settings:
+- `online-mode = false` - Offline mode for testing
+- `player-info-forwarding-mode = "NONE"` - No player info forwarding
+- `servers.minecraft = "minecraft:25565"` - Backend server connection
+
+## Testing Velocity Integration
+
+### 1. Start the environment
+
+```bash
+./x start
+```
+
+Wait for both containers to start. You should see:
+- Paper server: "Done! For help, type 'help'"
+- Velocity: "Done (X.XXs)!"
+
+### 2. Connect with Minecraft client
+
+1. Open Minecraft Java Edition
+2. Add a server with address: `localhost:25577`
+3. Connect to the server
+
+### 3. Verify handshake
+
+When you join the server, LunaticChat will perform a handshake between Paper and Velocity.
+
+**Expected behavior:**
+- Paper plugin sends handshake message to Velocity
+- Velocity plugin validates plugin version and protocol version
+- If compatible: connection succeeds, handshake logs appear in both containers
+- If incompatible: Paper plugin disables itself with error message
+
+**Check logs:**
+
+Paper server:
+```bash
+./x logs | grep -i handshake
+```
+
+Expected output:
+```
+[INFO]: [LunaticChat] Sending handshake to Velocity (Plugin: 0.8.0, Protocol: 1.0.0)
+[INFO]: [LunaticChat] Velocity handshake successful with version 0.7.0
+```
+
+Velocity proxy:
+```bash
+./x vlogs | grep -i handshake
+```
+
+Expected output:
+```
+[INFO] [lunaticchat]: Received handshake from minecraft: Plugin=0.8.0, Protocol=1.0.0
+[INFO] [lunaticchat]: Handshake successful with minecraft
+```
+
+### 4. Test /lcv status command
+
+In-game or via RCON:
+```
+/lcv status
+```
+
+Expected output:
+- Paper Plugin Version
+- Velocity Plugin Version
+- Protocol Version
+- Connection State: Connected
+- Live status check results
+
+## Version Compatibility
+
+### Plugin Version Check
+- **Rule:** Paper and Velocity plugin versions must match exactly
+- **Example:** Paper 0.8.0 + Velocity 0.8.0 = ✓ PASS
+- **Example:** Paper 0.8.0 + Velocity 0.7.0 = ✗ FAIL
+
+### Protocol Version Check
+- **Rule:** MAJOR.MINOR must match (PATCH differences are OK)
+- **Example:** Paper 1.0.0 + Velocity 1.0.1 = ✓ PASS
+- **Example:** Paper 1.0.0 + Velocity 1.1.0 = ✗ FAIL
+- **Example:** Paper 1.0.0 + Velocity 2.0.0 = ✗ FAIL
+
+## Troubleshooting
+
+### Paper plugin disabled on startup
+
+**Cause:** Handshake failed or timed out
+
+**Solutions:**
+1. Check Velocity is running: `docker ps | grep velocity`
+2. Check plugin versions match in both containers
+3. Review error messages in Paper logs: `./x logs | grep ERROR`
+
+### "Handshake timeout" error
+
+**Cause:** Paper plugin couldn't reach Velocity proxy
+
+**Solutions:**
+1. Verify network connectivity: `docker network inspect docker_minecraft-network`
+2. Check Velocity logs for errors: `./x vlogs`
+3. Restart containers: `./x restart`
+
+### Version mismatch errors
+
+**Cause:** Plugin versions don't match or protocol incompatible
+
+**Solutions:**
+1. Rebuild both plugins: `./gradlew clean :platform-paper:shadowJar :platform-velocity:shadowJar`
+2. Restart containers: `./x restart`
+3. Verify versions in logs match
+
+## Network Details
+
+- **Velocity Public Port:** 25577 (connect here with Minecraft client)
+- **Paper RCON Port:** 25575 (for remote commands)
+- **Internal Network:** `minecraft-network` (bridge driver)
+- **Paper Internal Address:** `minecraft:25565` (accessible from Velocity)
+
+## Useful Commands
+
+```bash
+# Follow logs in real-time
+docker compose -f docker/compose.yaml logs -f
+
+# Execute command in Minecraft server
+docker compose -f docker/compose.yaml exec minecraft rcon-cli
+> /list
+> /lcv status
+
+# Shell access to containers
+docker compose -f docker/compose.yaml exec minecraft bash
+docker compose -f docker/compose.yaml exec velocity bash
+
+# View Velocity configuration
+docker compose -f docker/compose.yaml exec velocity cat /server/velocity.toml
+```
diff --git a/docker/compose.yaml b/docker/compose.yaml
index c3814d1..7ab8e19 100644
--- a/docker/compose.yaml
+++ b/docker/compose.yaml
@@ -1,10 +1,35 @@
 services:
+  velocity:
+    image: itzg/mc-proxy:java21
+    container_name: debug-velocity
+    ports:
+      - "25577:25577"
+    volumes:
+      - lunatic-debug-velocity-data:/server
+      - ../platform-velocity/build/libs:/plugins:ro
+      - ./velocity.toml:/server/velocity.toml
+    environment:
+      TYPE: "VELOCITY"
+      MEMORY: "512M"
+      ONLINE_MODE: "false"
+    depends_on:
+      minecraft:
+        condition: service_healthy
+    healthcheck:
+      test: mc-health
+      start_period: 60s
+      interval: 10s
+      timeout: 5s
+      retries: 3
+    networks:
+      - minecraft-network
+
   minecraft:
     image: itzg/minecraft-server:java21
     container_name: debug-server
-    user: "0:0"
+    expose:
+      - "25565"
     ports:
-      - "25565:25565"
       - "25575:25575"
     volumes:
       - lunatic-debug-minecraft-data:/data
@@ -36,8 +61,15 @@ services:
       MAX_PLAYERS: "3"
       ONLINE_MODE: "false"
       SYNC_SKIP_NEWER_IN_DESTINATION: "false"
+    networks:
+      - minecraft-network
     tty: true
     stdin_open: true
 
+networks:
+  minecraft-network:
+    driver: bridge
+
 volumes:
   lunatic-debug-minecraft-data:
+  lunatic-debug-velocity-data:
diff --git a/docker/paper-global.yml b/docker/paper-global.yml
new file mode 100644
index 0000000..4c01c4e
--- /dev/null
+++ b/docker/paper-global.yml
@@ -0,0 +1,8 @@
+# Paper Global Configuration
+# https://docs.papermc.io/paper/reference/global-configuration
+
+proxies:
+  velocity:
+    enabled: true
+    online-mode: false
+    secret: ""
diff --git a/docker/velocity.toml b/docker/velocity.toml
new file mode 100644
index 0000000..4d2cd19
--- /dev/null
+++ b/docker/velocity.toml
@@ -0,0 +1,123 @@
+# Config version. Do not change this
+config-version = "2.7"
+
+# What port should the proxy be bound to? By default, we'll bind to all addresses on port 25577.
+bind = "0.0.0.0:25577"
+
+# What should be the MOTD? This gets displayed when the player adds your server to
+# their server list. Only MiniMessage format is accepted.
+motd = "<#09add3>LunaticChat Debug Server"
+
+# What should we display for the maximum number of players? (Velocity does not support a cap
+# on the number of players online.)
+show-max-players = 3
+
+# Should we authenticate players with Mojang? By default, this is on.
+online-mode = false
+
+# Should the proxy enforce the new public key security standard? By default, this is on.
+force-key-authentication = false
+
+# If client's ISP/AS sent from this proxy is different from the one from Mojang's
+# authentication server, the player is kicked. This disallows some VPN and proxy
+# connections but is a weak form of protection.
+prevent-client-proxy-connections = false
+
+# Should we forward IP addresses and other data to backend servers?
+# Available options:
+# - "none":        No forwarding will be done. All players will appear to be connecting
+#                  from the proxy and will have offline-mode UUIDs.
+# - "legacy":      Forward player IPs and UUIDs in a BungeeCord-compatible format. Use this
+#                  if you run servers using Minecraft 1.12 or lower.
+# - "bungeeguard": Forward player IPs and UUIDs in a format supported by the BungeeGuard
+#                  plugin. Use this if you run servers using Minecraft 1.12 or lower, and are
+#                  unable to implement network level firewalling (on a shared host).
+# - "modern":      Forward player IPs and UUIDs as part of the login process using
+#                  Velocity's native forwarding. Only applicable for Minecraft 1.13 or higher.
+player-info-forwarding-mode = "NONE"
+
+# If you are using modern or BungeeGuard IP forwarding, configure a file that contains a unique secret here.
+# The file is expected to be UTF-8 encoded and not empty.
+forwarding-secret-file = "forwarding.secret"
+
+# Announce whether or not your server supports Forge. If you run a modded server, we
+# suggest turning this on.
+#
+# If your network runs one modpack consistently, consider using ping-passthrough = "mods"
+# instead for a nicer display in the server list.
+announce-forge = false
+
+[query]
+# Should Query be enabled? Query allows clients to request information about the server.
+enabled = false
+
+# This is the map name that is reported to the query services.
+map = "Velocity"
+
+# Whether plugins should be shown in query response by default or not
+show-plugins = false
+
+[servers]
+# Configure your servers here. Each key represents the server's name, and the value
+# represents the IP address of the server to connect to.
+minecraft = "minecraft:25565"
+
+# In what order we should try servers when a player logs in or is kicked from a server.
+try = [
+    "minecraft"
+]
+
+[forced-hosts]
+# Configure your forced hosts here.
+
+[advanced]
+# How large a Minecraft packet has to be before we compress it. Setting this to zero will
+# compress all packets, and setting it to -1 will disable compression entirely.
+compression-threshold = 256
+
+# How much compression should be done (from 0-9). The default is -1, which uses the
+# default level of 6.
+compression-level = -1
+
+# How fast (in milliseconds) are clients allowed to connect after the last connection? By
+# default, this is three seconds. Disable this by setting this to 0.
+login-ratelimit = 3000
+
+# Specify a custom timeout for connection timeouts here. The default is five seconds.
+connection-timeout = 5000
+
+# Specify a read timeout for connections here. The default is 30 seconds.
+read-timeout = 30000
+
+# Enables compatibility with HAProxy's PROXY protocol. If you don't know what this is for, then
+# don't enable it.
+haproxy-protocol = false
+
+# Enables TCP fast open support on the proxy. Requires the proxy to run on Linux.
+tcp-fast-open = false
+
+# Enables BungeeCord plugin messaging channel support on Velocity.
+bungee-plugin-message-channel = true
+
+# Shows ping requests to the proxy from clients.
+show-ping-requests = false
+
+# By default, Velocity will attempt to gracefully handle situations where the user unexpectedly
+# loses connection to the server without an explicit disconnect message by attempting to fall the
+# user back, except in the case of read timeouts. BungeeCord will disconnect the user instead. You
+# can disable this setting to use the BungeeCord behavior.
+failover-on-unexpected-server-disconnect = true
+
+# Declares the proxy commands to 1.13+ clients.
+announce-proxy-commands = true
+
+# Enables the logging of commands
+log-command-executions = false
+
+# Enables logging of player connections when connecting to the proxy, switching servers
+# and disconnecting from the proxy.
+log-player-connections = true
+
+# Allows players transferred from other hosts via the
+# Transfer packet (Minecraft 1.20.5) to be received.
+accepts-transfers = false