core-ranks/docs/07_Operations.md

Operations

Smoke test after deploy

1. /networkcore status shows "Database: ok" and "Network: connected".
2. Boot log shows Replaced default provider: <something> and Registered Ranks provider (kewwbec-ranks).
3. /rank list returns at least the seven built-in groups (hytale:None, hytale:Adventurer, ..., hytale:Admin).
4. /rank create vip [VIP] 50 then /rank info vip shows it back.
5. /grant <your-alt> vip. From the alt, send a chat message - prefix [VIP] should appear.
6. /primary <your-alt> vip (only needed if the alt has multiple ranks; with just vip it's already primary).
7. /revoke <your-alt> vip - prefix disappears.

Permissions don't seem to apply

1. /ranks <player> - is the rank in the active list? If no, the grant didn't take.
2. /rank info <rank-id> - does the rank actually have the permission you expected?
3. Check inheritance: if vip has no perm but its parent default does, the player should still have it via inheritance.
4. The cache. After a /grant, the player's cache entry is invalidated locally and a bus message is sent. If the server they're on missed the bus message, their cache is stale. Quick fix: have them reconnect, or restart that server.

/op Bob did nothing visible

It writes to MySQL but doesn't tell anyone. Verify:

SELECT * FROM ranks_grants
WHERE user_uuid = '<bob-uuid>' AND rank_id = 'hytale:Admin'
ORDER BY granted_at DESC LIMIT 1;

If you see the row, /op succeeded - Bob needs to reconnect for client-side perm changes to apply (Hytale reads perms on connect for many things).

Chat prefixes aren't showing

1. inject_prefix is true in config?
2. The player has a primary rank? /ranks <name> and check the "Primary:" line.
3. The primary rank has a non-empty prefix? /rank info <rank>.
4. The chat event isn't being cancelled by something else (e.g. mute from Staff). If muted, the formatter rewrite is irrelevant - the message never sends.

A rank's permissions don't apply to existing holders

You added a perm with /rank addperm. Existing holders need their cache invalidated to pick it up. addRankPermission does cache.invalidateRank(id) which clears all caches and broadcasts. If they STILL don't see it:

1. Check the boot log - did our cache subscription succeed?
2. redis-cli -h <host> MONITOR while you re-run /rank addperm. You should see a PUBLISH on ranks.invalidate. If not, the publish failed.
3. Worst case: bounce the server they're on. Cache rebuilds on next call.

Built-in groups missing

If /rank list doesn't show the hytale:* groups, schema bootstrap didn't seed them (or someone deleted them via raw SQL). To re-seed:

INSERT IGNORE INTO ranks (id, parent_id, display_name, prefix, priority, built_in, created_at) VALUES
('hytale:None', NULL, 'None', '', 0, 1, UNIX_TIMESTAMP() * 1000),
('hytale:Adventurer', 'hytale:None', 'Adventurer', '', 10, 1, UNIX_TIMESTAMP() * 1000),
('hytale:Builder', 'hytale:Adventurer', 'Builder', '', 20, 1, UNIX_TIMESTAMP() * 1000),
('hytale:WorldEditor', 'hytale:Builder', 'WorldEditor', '', 30, 1, UNIX_TIMESTAMP() * 1000),
('hytale:ServerEditor', 'hytale:WorldEditor', 'ServerEditor', '', 40, 1, UNIX_TIMESTAMP() * 1000),
('hytale:Admin', 'hytale:ServerEditor', 'Admin', '', 100, 1, UNIX_TIMESTAMP() * 1000);

INSERT IGNORE INTO ranks_perms (rank_id, permission) VALUES ('hytale:Admin', '*');

Then invalidate all caches by restarting any one server (it'll broadcast nothing useful but its own cache rebuilds, and you can run /rank reload if we ever add one).

Auditing

Recent grants by any moderator:

SELECT granted_at, granted_by_name, user_uuid, rank_id, expires_at
FROM ranks_grants
ORDER BY granted_at DESC LIMIT 50;

All grants of a specific rank to anyone, ever:

SELECT * FROM ranks_grants WHERE rank_id = 'vip' ORDER BY granted_at DESC;

Players with active permanent grants of hytale:Admin:

SELECT DISTINCT user_uuid FROM ranks_grants
WHERE rank_id = 'hytale:Admin' AND revoked = 0 AND expires_at IS NULL;

Things this plugin deliberately doesn't do

• No /perm reload-style admin command. Cache invalidation is implicit on every write; a manual reload is rarely needed. If you need one, add a small command that calls cache.invalidateAll().
• No per-world permissions. Hytale's group model is global. If you need per-world, you'd need a separate layer that filters by world before checking - out of scope.
• No GUI for managing ranks. Could be a Staff-style HyUI page. Not in v1.
• No automatic OP backup before replacing default. If you have important OPs in the file provider, document them yourself before installing.