# Incognito Incognito is a Minecraft plugin for Paper and Folia that lets players hide their identity behind a random alias. It masks names and skins in data sent to clients and shifts visible world coordinates. Administrators can manage players' incognito settings and receive notifications about identity changes. ## Features - A random alias on each incognito login, used in the profile, player list and nametag. - Name masking in chat, scoreboards, boss bars, holograms and supported text sent by other plugins. - Hidden skins or a shared replacement skin for other viewers. Players still see their own skin. - Player head masking in inventories, equipment, dropped items and placed blocks. Original item profiles remain stored on the server. - Books signed with the player's alias while incognito is active. - X/Z offsets in the world view, F3, minimaps and supported text. Coordinates entered in supported commands are translated back to server coordinates. - Player preferences or server rules for showing join and quit messages. - Administrative notifications containing real names and aliases. - Optional PlaceholderAPI and MiniPlaceholders integrations, with SQLite, MySQL or PostgreSQL storage. ## Requirements and installation The project builds against Paper API `1.21.8` by default and targets Java 21. Folia support is declared in the plugin metadata. Packet filtering uses internal server classes, so compatibility with other Minecraft versions should be verified before deployment. 1. Build the project or obtain a packaged `Incognito-v.jar`. 2. Place the JAR in the server's `plugins` directory and restart the server. 3. Edit `plugins/Incognito/config.yml` and grant players `incognito.use`. 4. Restart the server after configuration changes. Missing configuration keys are added at startup. PlaceholderAPI and MiniPlaceholders are optional. Database libraries are loaded through the server's library mechanism. The plugin also uses bStats metrics, controlled by the server's bStats settings. ## Using incognito `/incognito` saves the requested state. Enabling and disabling protection takes effect after the player disconnects and rejoins, including when coordinate masking is disabled. The player receives a pending-change message; the plugin does not automatically disconnect them to apply it. `/incognito status` shows the active alias, disabled state or pending change. Toggling again before disconnecting cancels a pending change. Aliases are generated during login. ## Commands and permissions Command alias: `/incog`. | Command | Action | | --- | --- | | `/incognito` | Toggles the requested incognito state. | | `/incognito on` / `/incognito off` | Requests enabling or disabling incognito. | | `/incognito status` | Shows the current protection state. | | `/incognito messages` | Toggles visibility of the player's own join and quit messages while incognito is active. | | `/incognito messages on` / `/incognito messages off` | Sets those messages to shown or hidden. | | `/incognito messages status` | Shows the effective setting and whether changes are locked. | | `/incognito player [on\|off]` | Changes an online player's state; toggles it when `on`/`off` is omitted. | | Permission | Default | Purpose | | --- | --- | --- | | `incognito.use` | OP | Access to the command and personal incognito settings. | | `incognito.admin` | OP | Manage other players and receive incognito state and alias notifications. The administrative command also requires `incognito.use`. | | `incognito.reveal` | OP | View real names through the `incognito_realname` placeholder. Ordinary name masking remains active. | Personal settings require a player sender. The console can use the `player` subcommand. With `names.hide_realname: true`, target incognito players by their aliases. ## Join and quit messages ```yaml join-quit: mode: player default-show: true allow-toggle: true ``` | Setting | Behavior | | --- | --- | | `mode: player` | Uses each player's saved preference, or `default-show` until they choose one. | | `mode: show` | Forces messages to be shown and blocks player changes. | | `mode: hide` | Forces messages to be hidden and blocks player changes. | | `default-show` | Initial setting in `player` mode: `true` shows messages, `false` hides them. | | `allow-toggle: false` | Locks changes in `player` mode while preserving saved preferences and the default for players without a preference. | A preference controls both join and quit announcements about that player, as seen by everyone in chat. It is saved in the database and can be set before enabling incognito. It applies to subsequent join and quit events while protection is active. Messages for players without incognito remain under the server's control. When showing messages, the plugin preserves the event message and masks the player's name if `names.enabled` and `names.mask-system-messages` are enabled. In `show` mode, if the message was previously cleared, it supplies `messages.join-message` or `messages.quit-message`. In `player` mode, suppression by another plugin is preserved. These rules control standard join and quit events; separate broadcasts sent directly by other plugins are outside their scope. Another listener modifying the event later can change the result. ## Administrative notifications Online players with `incognito.admin` receive notifications when a pending change is saved and when it takes effect at login. They do not need `incognito.reveal`. Real names in these notifications are shown only to authorized recipients. Example messages after a change takes effect: ```text Incognito >> Player Notch enabled incognito, new nickname: incognito123 Incognito >> Player incognito123 disabled incognito, new nickname: Notch ``` Before reconnection, the notification describes the pending change. Rejoining with incognito still active sends a new-alias notification. Canceling a pending change has a separate notification; requesting an already saved state does not send another notification. Templates are in the `messages` section under `notify-enabled`, `notify-disabled`, `notify-alias-changed`, `notify-pending-enabled`, `notify-pending-disabled` and `notify-cancelled`. Set an individual template to `''` to disable that notification. `` is the real name and `` is the alias. All templates in `messages` support MiniMessage. ## Protection settings See [config.yml](src/main/resources/config.yml) for the full configuration, defaults and comments. | Key | Purpose | | --- | --- | | `names.enabled` | Enables name masking and replacement of real UUIDs in supported text with session UUIDs. Dashed and compact UUIDs are supported. | | `names.mask-player-messages` | Default `false`: preserves player-written chat content. Set `true` to mask incognito names and UUIDs inside player messages. Names without an incognito session are unchanged. Structured sender names remain masked independently of this option. | | `names.mask-system-messages` | Default `true`: masks incognito names and UUIDs in server chat messages, including join, quit and death announcements, and on the death screen. Set `false` to preserve those messages, which may expose real identities. Does not control player chat or other UI text such as titles and action bars. | | `names.format` | Alias pattern, default `Anon_{random}`. Requires `{random}`; other characters must be ASCII letters, digits or `_`. Aliases are limited to 16 characters. | | `names.tabcomplete` | Uses aliases in command suggestions and chat name completion. Disabling it leaves real names in suggestions. | | `names.hide_realname` | Replaces the real name with the alias in the server's online-player name map. Offline lookups retain the real name; custom lookup mechanisms in other plugins may bypass this map. | | `skin.enabled` | Masks skins for other viewers. | | `skin.value`, `skin.signature` | Optional shared skin as signed Minecraft profile texture properties. Set both together; these are not a username or image URL. | | `heads` | Masks player heads in packets. | | `books` | Uses the alias as the author when signing a book while name masking is active. | | `coordinates.enabled` | Shifts the visible world along X/Z. Y is unchanged. | | `coordinates.tabcomplete` | Translates coordinates in command suggestions. | | `coordinates.patterns` | Regular expressions for coordinates in text, using named `x` and `z` capture groups. | | `placeholders.enabled` | Filters results from PlaceholderAPI expansions. | | `debug` | Logs detailed packet transformations for troubleshooting. | Masking applies to supported data sent to clients. It does not remove real names from databases, logs or data retained by other plugins. Incognito is not vanish: the player remains visible in the world. Both message options require `names.enabled`. With `names.mask-system-messages` enabled, join, quit and death message fields are masked at `LOWEST` and `HIGHEST` event priorities. Death-screen overrides and the separate death-screen packet are covered as well. The `AsyncChatEvent` renderer receives a masked sender display name regardless of the message options. These event transformations do not shift coordinates; the outgoing packet filter applies the recipient's coordinate offset. The server's `Player` object retains its real UUID and account name so permissions, inventories and other player data keep their original identity. Installed plugins still have access to that object and can reconstruct real names or UUIDs. Custom plugin channels and renderers that ignore the supplied display name require integration; event masking does not isolate plugins from each other. With `names.mask-player-messages: false`, unstructured player chat content is preserved, including content generated by a custom renderer. Messages sent by plugins as unstructured system chat follow `names.mask-system-messages`. Ordinary item metadata and previously written books are not covered by this text filtering. ## Placeholders The following placeholders are available when the corresponding integration is installed: | PlaceholderAPI | MiniPlaceholders | Result | | --- | --- | --- | | `%incognito_enabled%` | `` | `true` or `false` for the active session. | | `%incognito_name%` | `` | Active alias or ordinary player name. | | `%incognito_realname%` | `` | Real name of an online incognito player, revealed to recipients with `incognito.reveal`; otherwise empty. | | `%incognito_x%` | `` | Visible block X coordinate. | | `%incognito_y%` | `` | Block Y coordinate. | | `%incognito_z%` | `` | Visible block Z coordinate. | | `%incognito_world%` | `` | World name. | MiniPlaceholders tags require a player audience. Incognito's own placeholders are registered independently of `placeholders.enabled`; that option controls wrapping results from other PlaceholderAPI expansions. ## Storage The default backend is SQLite at `plugins/Incognito/data.db`. Records contain the UUID, real name, requested incognito state, message preference and last alias needed for the disable notification. The stored alias is used for notifications; a new alias is generated at login. Coordinate offsets are stored separately in `coordinate-sessions.yml`. For MySQL, create a database and configure: ```yaml storage: type: mysql host: localhost port: 3306 database: incognito username: incognito password: '' table-prefix: incognito_ pool-size: 4 ``` For PostgreSQL, use `type: postgresql` (or `postgres`) and the appropriate port, usually `5432`. The database account must be able to create and alter tables. Switching backends does not automatically transfer records between databases. Writes are asynchronous, and pending changes are flushed during a normal plugin shutdown.

Incognito

Compatibility

Minecraft: Java Edition

Platforms

Links

Tags

Creators

Details