init

2026-05-26 23:16:33 -04:00
commit 3b023d3c6b
32 changed files with 2931 additions and 0 deletions
@@ -0,0 +1,37 @@
+# Ranks
+
+Ranks, groups, grants, and chat prefixes for KweebecNet. Replaces Hytale's default file-backed permission provider with a MySQL-backed one.
+
+## What it does
+
+- **Ranks (= Hytale groups)**: create, delete, edit, set parents (inheritance), add/remove permission nodes.
+- **Grants**: give a rank to a player permanently or for a fixed duration. Multiple ranks per player allowed; one is "primary" for display.
+- **Permission provider**: implements `com.hypixel.hytale.server.core.permissions.provider.PermissionProvider`. After we register, **every** `PermissionsModule.get().hasPermission(...)` call (yours, Staff's, Hytale's own /op) routes through our MySQL.
+- **Chat prefixes**: rewrites `PlayerChatEvent`'s formatter to inject the player's primary rank prefix.
+- **Cross-server propagation**: every write invalidates per-user / per-rank caches network-wide via NetworkCore's MessageBus, so a `/grant` on one server takes effect everywhere within milliseconds.
+
+## Requires
+
+- **NetworkCore** with `mysql.enabled: true` and a healthy MySQL connection.
+- Working `network.auth_token` (so invalidations propagate cleanly).
+- Hytale permission nodes assigned for management commands - see [docs/03_Commands.md](docs/03_Commands.md#permissions).
+
+## Why this is critical
+
+This plugin owns *all* permissions on the network. If it boots in a broken state:
+
+- Players may have wrong perms (too many → security issue; too few → game broken).
+- Hytale's own commands (`/op`, `/perm group`, etc.) silently route through us; if our writes drop, those actions vanish.
+- The chat prefix listener fires on every chat message; a bug there spams logs.
+
+Treat changes to [RanksPermissionProvider](src/main/java/net/kewwbec/ranks/provider/RanksPermissionProvider.java) and [SchemaBootstrap](src/main/java/net/kewwbec/ranks/db/SchemaBootstrap.java) like changes to NetworkCore: read the docs first, ask a higher-up before merging.
+
+## Read before changing
+
+- [docs/01_Overview.md](docs/01_Overview.md) - architecture, how the pieces fit
+- [docs/02_Configuration.md](docs/02_Configuration.md) - config.json reference
+- [docs/03_Commands.md](docs/03_Commands.md) - every command + permission nodes
+- [docs/04_Schema.md](docs/04_Schema.md) - MySQL tables, built-in group seeding
+- [docs/05_Provider_Integration.md](docs/05_Provider_Integration.md) - what "replacing Hytale's provider" actually means at runtime
+- [docs/06_Cross_Server_Caching.md](docs/06_Cross_Server_Caching.md) - cache + invalidation flow
+- [docs/07_Operations.md](docs/07_Operations.md) - ops scenarios, debugging