================================================================================
UUID & IP LOCKER - COMMANDS & PERMISSIONS
================================================================================
This document lists all commands and permissions provided by UUID & IP Locker,
what they do, and when they are typically used.
--------------------------------------------------------------------------------
1. USER COMMANDS
--------------------------------------------------------------------------------
These are intended for normal players.
1.1 /login
----------
Syntax:
/login <password>
Who can use:
- Any player, when Password Authentication is enabled.
Purpose:
- Authenticates a player with their previously registered password.
- Grants them "logged in" status for this session.
- When on a NEW IP/verification state, a successful login will also:
- Complete IP verification for that pending IP.
- Add the IP to the player's allowed IP list.
When required:
- If the player has a password and:
- Their password mode is ON (required every login), or
- They are on a new/unverified IP, or
- They are required to use a password via permission.
Notes:
- If the player is already logged in, the plugin sends an "already logged in"
message and does nothing.
- Failed attempts are tracked; exceeding the configured limit will kick them.
1.2 /register
-------------
Syntax:
/register <password> <confirm>
Who can use:
- Normal players, when self-registration is allowed in config.
Purpose:
- Creates a password for the player's account and logs them in immediately.
Behavior:
- Validates that:
- The two password arguments match.
- The password does not contain the player's username.
- The password is not present in the configured blacklist.
- On success:
- Saves the hashed password.
- Marks the player as logged in for this session.
Notes:
- If the player already has a password, registration is blocked.
- Self-registration can be disabled; in that case, the player is told to
contact an administrator.
1.3 /password
-------------
Syntax:
/password <on|off|status>
Who can use:
- Any player who already has a password, while Password Auth is enabled.
Purpose:
- Lets each player choose how strictly their password is enforced.
Subcommands:
- /password on
Sets password mode to ON for this player.
- They must login with /login on every join, even from known IPs.
- /password off
Sets password mode to OFF for this player.
- They are not forced to login every join on known IPs.
- They still must use their password when their info changes
(e.g., new IP or verification).
- /password status
Shows current mode:
- ON = required every login.
- OFF = only required on changes / new IPs.
Notes:
- If the player has no password, the command tells them to register first.
--------------------------------------------------------------------------------
2. MAIN PLUGIN COMMAND (/uuidiplocker, /uil)
--------------------------------------------------------------------------------
Base command:
/uuidiplocker
Alias:
/uil
Who can use:
- All players can run it, but subcommands and features depend on permissions.
2.1 No arguments: Help / Panel
------------------------------
Syntax:
/uuidiplocker
Behavior:
- If sender has admin permission and is a player:
- Opens the main Admin GUI panel.
- Otherwise:
- Prints a help list of commands the sender is allowed to use:
- Admin subcommands (if admin).
- /uuidiplocker verify (if verify permission).
- User commands (/login, /register, /password).
2.2 /uuidiplocker panel
-----------------------
Syntax:
/uuidiplocker panel
Who can use:
- Players with admin permission (uuidiplocker.admin).
Purpose:
- Opens the main Admin GUI:
- Player management
- IP lock/UUID lock overview
- Inventory editor and backups
- Feature toggles and configuration shortcuts.
2.3 /uuidiplocker reset
-----------------------
Syntax:
/uuidiplocker reset <player>
Who can use:
- Players/console with admin permission (uuidiplocker.admin).
Purpose:
- Clears the specified player's IP locks.
- Used when an account needs its IP access list reset.
2.4 /uuidiplocker resetpassword
-------------------------------
Syntax:
/uuidiplocker resetpassword <player>
Who can use:
- Players/console with admin permission (uuidiplocker.admin).
Purpose:
- Removes the target player's password.
- Forces them to re-register a new password on next join (if needed).
Behavior:
- If the target is online:
- Notifies them their password was reset.
- Logs them out server-side so they must re-register/login.
2.5 /uuidiplocker adminverify
-----------------------------
Syntax:
/uuidiplocker adminverify <player> [code]
Who can use:
- Players/console with admin permission (uuidiplocker.admin).
Purpose:
- Manually handles verification for:
- Shared IP limits (second account on same IP).
- Players stuck in verification mode.
Behavior:
- If the target is currently in verification mode:
- If a code is provided:
- Checks it; if wrong, rejects.
- Completes verification:
- Adds the pending IP to the allowed list.
- Logs the player in (bypassing password for that event).
- If the target is online but not in verification mode:
- Authorizes their current IP and logs them in.
2.6 /uuidiplocker blacklist
---------------------------
Syntax:
/uuidiplocker blacklist <add|remove|list> [password]
Who can use:
- Players/console with admin permission (uuidiplocker.admin).
Purpose:
- Manages the password blacklist in config.
Subcommands:
- add <password>
Adds the specified password string to the blacklist.
- remove <password>
Removes the specified password string, if present.
- list
Shows the current blacklist.
Notes:
- The plugin never suggests passwords in tab-complete to avoid leaks.
2.7 /uuidiplocker verify
------------------------
Syntax:
/uuidiplocker verify <code>
Who can use:
- Players with uuidiplocker.verify permission, or
- Players allowed by the plugin when they are in verification mode.
Purpose:
- Lets players verify a new IP with a code that was sent (usually via
Discord webhook or DM).
Behavior:
- If the code matches the pending verification, the plugin:
- Adds the new IP to their allowed IP list.
- Ends verification mode.
2.8 /uuidiplocker resetlink
---------------------------
Syntax:
/uuidiplocker resetlink <player>
Who can use:
- Players/console with admin permission (uuidiplocker.admin).
Purpose:
- Forcefully unlinks a player's Minecraft account from their Discord account.
--------------------------------------------------------------------------------
3. ACCOUNT LINKING COMMANDS
--------------------------------------------------------------------------------
3.1 /link
---------
Syntax:
/link <request|verify|status> [args]
Who can use:
- Any player with a registered password.
Subcommands:
- /link request <discord_id>
Starts the linking process. Sends a verification code to the Link Codes webhook.
- /link verify <code>
Completes the linking process using the code provided by an admin.
- /link status
Shows if the account is linked and the linked Discord ID.
3.2 /unlink
-----------
Syntax:
/unlink
/unlink confirm <code>
Who can use:
- Linked players who are logged in.
Purpose:
- Safely unlinks the account.
- Requires two-step verification via Discord DM.
Behavior:
- /unlink: Generates a code and sends it to the player's linked Discord DM.
- /unlink confirm <code>: Completes the unlinking process.
--------------------------------------------------------------------------------
4. ADMIN-ONLY AUXILIARY COMMANDS
--------------------------------------------------------------------------------
4.1 /adminverify
----------------
Syntax:
/adminverify <player> <code>
Who can use:
- Players/console with admin permission (uuidiplocker.admin).
Purpose:
- Shortcut command to run verification without going through /uuidiplocker.
- Manually verifies a player blocked by shared IP or verification checks.
Behavior:
- Calls the same internal logic as /uuidiplocker adminverify.
4.2 /invopen
------------
Syntax:
/invopen <player>
Who can use:
- Players with admin permission (uuidiplocker.admin).
Purpose:
- Opens an inventory editor GUI for the target player.
- Supports both online and offline targets using stored backups.
Behavior:
- Displays the target's inventory (and some armor/offhand data).
- Allows editing and saving changes back to the target player.
4.3 /resetpassword
------------------
Syntax:
/resetpassword <player>
Who can use:
- Players/console with admin permission (uuidiplocker.admin).
Purpose:
- Resets the player's password, forcing them to re-register.
Behavior:
- Removes the stored password (and password mode).
- If the target is online:
- Logs them out server-side.
- Notifies them their password was reset.
--------------------------------------------------------------------------------
5. PERMISSIONS
--------------------------------------------------------------------------------
5.1 uuidiplocker.admin
----------------------
Default:
- Not granted by default (should be assigned to trusted staff only).
Grants access to:
- /uuidiplocker panel
- /uuidiplocker reset
- /uuidiplocker resetpassword
- /uuidiplocker resetlink
- /uuidiplocker adminverify
- /uuidiplocker blacklist
- /adminverify
- /invopen
- /resetpassword
- Admin portions of the GUI.
Typical usage:
- Give to server owners and high-level staff who manage security and data.
5.2 uuidiplocker.bypass
-----------------------
Default:
- false
Effect:
- Player bypasses:
- IP lock checks on join.
- Shared IP limit checks.
- They are treated as trusted and are not blocked by verification logic.
Typical usage:
- For console accounts, test accounts, or trusted staff that should never
be blocked by IP or verification checks.
5.3 uuidiplocker.require_password
---------------------------------
Default:
- false
Effect:
- If set on a player:
- They must use a password even if IP locks would otherwise allow them.
- If they do not have a password set, they are restricted until they
register one.
Interaction with password mode:
- If the player has no password:
- They are forced to register.
- If they later set a password:
- Password mode (on/off) controls how often they must login, but
this permission still means they are expected to use password auth.
Typical usage:
- For higher-risk accounts that should always be password-protected.
5.4 uuidiplocker.verify
-----------------------
Default:
- Not explicitly defined in plugin.yml (treat as false by default;
assign manually in permissions plugin).
Effect:
- Allows running:
- /uuidiplocker verify <code>
- Also controls whether the verify line appears in the help output.
Typical usage:
- Give to trusted players or groups who are allowed to self-verify new IPs
using codes sent via webhook.
--------------------------------------------------------------------------------
6. OTHER BEHAVIORAL NOTES
--------------------------------------------------------------------------------
- Password Authentication Feature:
- Controlled by config option: features.password-auth (and GUI toggle).
- When disabled:
- /login, /register, /resetpassword, /password are not registered.
- Password checks are effectively skipped; IP/UUID locks still function.
- Self Registration:
- Controlled by config option: allow-self-register.
- When false:
- Players without passwords are directed to contact an admin instead of
being allowed to register themselves.
- Login Attempts and Timeout:
- max-login-attempts:
- Maximum failed /login attempts before the player is kicked.
- login-timeout:
- Time window after join for required login; expired sessions result in
a kick if login was required.
================================================================================
End of Commands & Permissions Reference
================================================================================
===============================================================================
===============================================================================