NameBound

NameBound is a server-only Fabric mod for Minecraft 1.21.1 that gives each authenticated Minecraft account one character identity for one life.

A player whose account name is Maxello1 can create John Smith. In the default surname mode, ordinary players see John S. above the player, in the player list, and as the sender name in signed chat. Death publishes the anonymous message Someone died., deletes that character, and requires a new character after respawn.

The mod uses only vanilla screens and packets. Players can join with an unmodified Minecraft 1.21.1 client.

Important limits

This masks the interface; it does not anonymize the protocol

NameBound never changes a player's authenticated GameProfile, Minecraft username, UUID, skin properties, chat session, public key, or authentication data. Those values remain authoritative for login, bans, whitelists, permissions, selectors, and server administration.

Vanilla networking necessarily sends the real profile name and UUID in player-info data, and the private nametag-hiding scoreboard team contains the real profile name. NameBound replaces the optional display-name components that an unmodified client normally renders, but a modified client, protocol-aware proxy, or network observer able to inspect the session can recover Minecraft usernames. NameBound provides roleplay-oriented UI masking, not cryptographic anonymity. Do not use it as a security boundary or promise players that account names are absent from packets.

Vanilla scoreboard teams are a hard compatibility boundary

A player can belong to only one vanilla scoreboard team. NameBound needs one private team per account to hide the original player nametag before it sends viewer-specific virtual labels.

existingTeamBehaviour controls a conflict with a non-NameBound team:

• WARN_AND_OVERRIDE (default) logs a warning and moves the account into its NameBound team. The previous team membership and any mechanics attached to it are lost.
• WARN_AND_SKIP logs a warning and leaves the existing team untouched. NameBound then cannot hide the vanilla nametag. The client may show both the virtual character label and the original username, producing a double label and a visible username leak.

Choose deliberately. Servers that depend on scoreboard teams for factions, colors, collision, friendly fire, minigames, or permissions need to test this interaction before deployment.

Features

• Exactly one active character per authenticated UUID; there is no player rename or character-switch command.
• Persistent global character state shared across dimensions, including character generation history, active-name ownership, surname mode, optional dead-name reservations, and staff preferences.
• Forced vanilla GUI flow: first-name anvil, last-name anvil, then a confirmation chest.
• Creation lock that blocks normal chat, unrelated commands, block breaking, attacks, and block/entity/item use. It can also provide temporary invulnerability and reopen a closed creation screen.
• Unicode-code-point-aware full-name limit: first name + one space + last name is at most 16 code points.
• Case-insensitive active-name uniqueness, configurable blacklist, title-case normalization, and optional Unicode/apostrophe/hyphen support.
• Global SHORTENED (John S.) and FULL (John Smith) surname display modes, persisted in the world save.
• Viewer-specific names in overhead packet-only text displays, the player list, and signed-chat decoration.
• Authorized staff can privately choose character names or real usernames without changing any other viewer's display.
• Narrow death-message replacement that leaves vanilla death processing intact, followed by character deletion and private server logging.
• Administrative inspection, reset, set, reload, label cleanup, and identity lookup commands.

Requirements and installation

NameBound is built for these exact project versions:

Component	Requirement
Minecraft Java Edition server	1.21.1
Java	21 or newer
Fabric Loader	0.16.14 or newer
Fabric API	0.116.12+1.21.1 or newer for Minecraft 1.21.1
Multiplayer client mod	None when joining a dedicated server

To install on a dedicated server:

1. Install Fabric Loader for a dedicated Minecraft 1.21.1 server.
2. Put Fabric API 0.116.12+1.21.1 or newer and namebound-1.0.2.jar in the server's mods directory.
3. Start the server with Java 21. NameBound creates config/namebound.json on its first run.
4. Stop the server, review the generated configuration—especially existingTeamBehaviour—then restart it.
5. Back up the world before first use on an existing server. Character state is stored in the overworld's persistent world data.

Clients joining a dedicated NameBound server do not need the mod. To use or test NameBound in singleplayer, however, install both NameBound and Fabric API in that client profile: Minecraft runs singleplayer's integrated server inside the client process, so Fabric must load the jar there. NameBound still contains no client-side feature code, and all user interaction uses vanilla client capabilities.

One-life workflow

1. A player joins. NameBound looks up the authenticated account UUID in global world state.
2. If no active character exists, the player enters the creation lock. The player list shows Creating Character…, and the first vanilla anvil screen opens after a short delay.
3. The player enters a first name, then a last name. Each step validates its input.
4. A confirmation chest shows the full and public names, plus warnings that the identity cannot be changed and death deletes it. The player may confirm or start again.
5. Confirmation revalidates the entire name and creates the record atomically on the server thread. Duplicate clicks cannot create a second active record.
6. Normal gameplay resumes. Viewer-specific character names are sent to chat, the player list, and nearby virtual nametags.
7. A completed death emits one configured generic message and deletes the active character after vanilla death processing. Totem activations do not count because the player did not complete a death.
8. Respawn or the next reconnect starts creation again. The account's character generation increments. A dimension transfer does not delete the character.

Incomplete creation sessions are memory-only. Disconnecting during creation causes the flow to start over on the next join.

Name rules

The defaults enforce all of the following:

• First and last names are each at least 2 code points.
• The complete normalized name, including its separating space, is no more than 16 Unicode code points.
• ASCII letters are accepted; Unicode letters are disabled unless configured.
• Apostrophes and hyphens are allowed only internally when enabled.
• Spaces inside either name part, leading or trailing punctuation, §, control/format characters, newlines, tabs, zero-width characters, and text-component formatting are rejected.
• Names are normalized and title-cased (o'connor becomes O'Connor; smith-jones becomes Smith-Jones).
• Active full names are unique under normalized, case-insensitive comparison.
• Blacklist entries are normalized full names.

/character create <firstName> <lastName> is the fallback when the vanilla GUI is unusable. It only succeeds for a player without an active character.

Commands and permissions

Permission values are vanilla command permission levels from 0 through 4. NameBound does not define separate permission-node strings.

Command	Default level	Purpose
/character info	Player	Show your active full/public name and generation.
/character create <firstName> <lastName>	Player	GUI fallback; only works with no active character.
/characteradmin info <account>	3	Show an authenticated account's UUID and character details.
/characteradmin reset <account>	3	Delete the character; start creation now if online and alive, after respawn if dead, or on next join if offline.
/characteradmin set <account> <firstName> <lastName>	3	Create or replace an account's character using normal validation.
/characteradmin reload	3	Reload config/namebound.json and refresh affected displays.
/characteradmin cleanup-labels	3	Remove and rebuild packet-only labels.
/namebound surname shortened	3	Globally display John S..
/namebound surname full	3	Globally display John Smith.
/namebound surname toggle	3	Toggle the persistent global surname mode.
/namebound surname status	3	Show the current global surname mode.
/namebound view character	2	Use character names in this staff viewer's UI.
/namebound view username	2	Use real usernames in this staff viewer's UI.
/namebound view toggle	2	Toggle this staff viewer's personal mode.
/namebound view status	2	Show this staff viewer's effective mode.
/namebound identify	2	Privately identify the online player under the crosshair within 8 blocks.
/namebound identify <player>	2	Privately show both identities for an online real username.
/namebound whois <full name>	2	Find the account UUID and known username owning an active full character name.

adminPermissionLevel, surnameAdminPermissionLevel, and staffViewPermissionLevel configure the three protected groups independently. The view commands require a player executor. Identity lookup results are private to the executor. Account arguments use authenticated Minecraft profiles, not character names; administrative profile arguments can resolve known offline accounts.

Saved staff preferences never grant access. NameBound checks the viewer's permission live and immediately falls back to CHARACTER_NAME if authorization is lost. Staff must explicitly opt into REAL_USERNAME.

Configuration

The first server start generates config/namebound.json with:

{
  "maximumFullNameLength": 16,
  "minimumFirstNameLength": 2,
  "minimumLastNameLength": 2,
  "surnameDisplayMode": "SHORTENED",
  "normalPlayersCanViewRealUsernames": false,
  "staffViewPermissionLevel": 2,
  "surnameAdminPermissionLevel": 3,
  "defaultStaffViewMode": "CHARACTER_NAME",
  "persistStaffViewPreferences": true,
  "unnamedPlayerDisplay": "Creating Character…",
  "requireUniqueActiveNames": true,
  "allowDeadNameReuse": true,
  "allowUnicodeLetters": false,
  "allowApostrophes": true,
  "allowHyphens": true,
  "nameBlacklist": [],
  "deathMessage": "Someone died.",
  "creationInvulnerability": true,
  "forceCreationScreenReopen": true,
  "nameplateViewRange": 1.0,
  "nameplateVerticalOffset": 0.35,
  "logCharacterDeaths": true,
  "adminPermissionLevel": 3,
  "existingTeamBehaviour": "WARN_AND_OVERRIDE"
}

Field	Default	Meaning
maximumFullNameLength	16	Maximum code points in first + space + last; accepted range is 5–16.
minimumFirstNameLength	2	Minimum first-name code points.
minimumLastNameLength	2	Minimum last-name code points.
surnameDisplayMode	SHORTENED	Initial world mode: SHORTENED or FULL. Once world state exists, commands change the persistent value.
normalPlayersCanViewRealUsernames	false	Safety-locked to false; setting it to true has no effect.
staffViewPermissionLevel	2	Level required for personal username view and identity lookup; valid range 1–4.
surnameAdminPermissionLevel	3	Level required to change/query global surname mode; valid range 0–4.
defaultStaffViewMode	CHARACTER_NAME	Safety-locked to CHARACTER_NAME; staff must opt into usernames.
persistStaffViewPreferences	true	Persist viewer preferences by authenticated UUID.
unnamedPlayerDisplay	Creating Character…	Neutral display while no character is complete.
requireUniqueActiveNames	true	Safety-locked to true; duplicate active full names are never allowed.
allowDeadNameReuse	true	If false, normalized names remain reserved after deletion, including death or administrative reset.
allowUnicodeLetters	false	Permit Unicode letter categories instead of ASCII letters only.
allowApostrophes	true	Permit internal apostrophes.
allowHyphens	true	Permit internal hyphens.
nameBlacklist	[]	Normalized full names that cannot be created. Legacy aliases blacklist and blockedNames are also read and merged.
deathMessage	Someone died.	Anonymous public text used for completed player deaths.
creationInvulnerability	true	Reject damage while a player is creation-locked.
forceCreationScreenReopen	true	Reopen the current creation screen after it is closed.
nameplateViewRange	1.0	Text-display view-range multiplier; valid range 0.01–64.0.
nameplateVerticalOffset	0.35	Extra label height above the current player pose; valid range -4.0–4.0 blocks.
logCharacterDeaths	true	Log the deleted character, real account name, and UUID privately to the server log.
adminPermissionLevel	3	Level required for /characteradmin; valid range 0–4.
existingTeamBehaviour	WARN_AND_OVERRIDE	Scoreboard conflict policy; either WARN_AND_OVERRIDE or WARN_AND_SKIP.

Invalid or unsafe values fall back to safe defaults. A malformed existing JSON file is not destroyed; NameBound logs a warning and runs with defaults. Display text rejects formatting and control characters. Run /characteradmin reload after editing most fields. The persistent global surname mode is intentionally not reset by a config reload.

Turning allowDeadNameReuse from false to true permits future reuse checks to ignore the reservation set; it does not reconstruct deleted character records. Always back up the world before changing identity policy.

Building from source

The Gradle wrapper and dependency versions are committed. A Java 21 JDK is required.

./gradlew.bat clean build

The distributable jar is written to build/libs/namebound-1.0.2.jar. The adjacent -sources.jar is for development and is not the server mod artifact.

Useful tasks:

./gradlew.bat test
./gradlew.bat compileJava
./gradlew.bat runServer

runServer creates a development server under run/. Read Mojang's EULA and set eula=true yourself only if you accept it; do not redistribute a pre-accepted EULA file.

Verification status

The Java 21 build compiles cleanly, and all 36 automated JUnit tests pass. Compatibility builds and the full test suite also pass against Fabric API 0.116.12+1.21.1, 0.116.13+1.21.1, and 0.116.14+1.21.1. A development launch loaded Minecraft 1.21.1, Fabric Loader 0.16.14, Fabric API 0.116.12+1.21.1, NameBound 1.0.2, and its mixins without bootstrap errors. It then stopped normally at eula=false. A full local world startup and live multiplayer session were not performed because the EULA was not accepted on the user's behalf; use the checklist below before production deployment.

Manual multiplayer test checklist

Use a disposable backed-up world, at least two normal accounts, and one operator/staff account. For per-viewer behavior, keep clients visible side by side.

First join and creation lock

• Join with a new UUID and verify the tab entry is Creating Character…, not a rendered username.
• Confirm the first-name anvil opens after the short join delay, followed by the last-name anvil and confirmation chest.
• Close each screen and verify the correct stage reopens when forceCreationScreenReopen is enabled.
• While locked, try normal chat, an unrelated command, block breaking, attacks, block/entity/item use, dropping, offhand swapping, inventory clicks, crafting, and creative inventory actions; each should be blocked.
• Take damage while creationInvulnerability is enabled and confirm it is rejected.
• Disconnect halfway through, reconnect, and verify creation starts again without retaining partial names.
• Use “Start Again” from confirmation and verify the flow returns to the first name.

Validation and atomicity

• Accept a normal name such as John Smith and verify normalization such as o'connor → O'Connor.
• Accept a full name exactly 16 code points long; reject one with 17. Confirm the separating space, apostrophes, and hyphens count.
• Reject one-character parts, internal spaces, leading/trailing punctuation, §, controls, zero-width characters, and blacklisted names.
• With Unicode disabled, reject non-ASCII letters. With it enabled, test a surrogate-pair code point and verify it counts once.
• Have two accounts race for the same normalized full name and verify only one succeeds.
• Double-click confirmation and run /character create after success; verify no second active character is created.

Normal identity surfaces

• From a normal viewer, verify the target shows John S. in the tab list, overhead label, and new signed-chat decoration.
• Verify there is only one overhead label, it follows standing/sneaking/swimming/crawling/sleeping/flight poses, and it disappears outside tracking range.
• Confirm chat arrives once, its body is unchanged, and the vanilla client does not flag a valid signed message merely because its decoration changed.
• Change dimensions and return; verify the character survives, no old label leaks across worlds, and one correct label is recreated.
• Disconnect/reconnect with an active character and verify no creation flow or duplicate label appears.

Global and per-viewer modes

• Put one authorized staff viewer in CHARACTER_NAME and another in REAL_USERNAME; verify they simultaneously see different labels and tab names for the same target.
• Verify staff username mode affects only that viewer's overhead labels, tab list, and new chat decoration.
• Verify a normal viewer continues to see character names and receives no username in NameBound-controlled display components.
• Toggle /namebound surname full and shortened; verify all public tab entries, labels, and subsequent chat refresh, while staff in username mode remains unchanged.
• Restart the server and verify global surname mode and configured staff preferences persist.
• Remove a staff viewer's permission live and verify their effective view immediately returns to CHARACTER_NAME and username-view commands disappear.
• Test /namebound identify, /namebound identify <player>, and /namebound whois <full name>; verify details are sent only to the authorized executor.

Death and replacement

• Kill a named player through PvP, a mob, fall/environment damage, the void, and /kill in separate runs; verify exactly one Someone died. message with no names, cause, killer, or item hover.
• Verify normal drops, statistics, advancements, scoreboard processing, killer attribution, and death/respawn behavior still occur.
• Activate a Totem of Undying and verify the character is not deleted.
• With doImmediateRespawn=false, die and disconnect while the death screen is visible.
• Reconnect and verify the vanilla death screen remains visible and no NameBound anvil or confirmation screen opens.
• Wait longer than INITIAL_OPEN_DELAY_TICKS and verify the death screen is still not replaced.
• Press Respawn and verify the first-name anvil opens after the normal creation delay.
• With doImmediateRespawn=true, die and verify normal respawn still occurs, creation opens once after respawn, and no creation screen repeatedly reopens.
• Respawn and create a replacement; verify its generation increased and the previous identity cannot be selected or switched back to.
• Test both allowDeadNameReuse values. With false, confirm the dead full name remains reserved.
• Verify the private server log records account details only when logCharacterDeaths is enabled.

Scoreboard conflicts and protocol expectations

• Put a test account on a non-NameBound team, select WARN_AND_OVERRIDE, join, and verify the warning plus removal from the original team.
• Repeat with WARN_AND_SKIP; verify the original team remains and document the expected double-label/real-nametag leak for your server setup.
• Inspect an authenticated session with a test client/proxy and verify the real GameProfile name and UUID remain present as documented; confirm operators, bans, whitelist entries, and selectors still use the real account.
• Run /characteradmin cleanup-labels after forced disconnects/dimension changes and verify there are no duplicate or orphaned virtual labels.

Operational notes

• Back up the world, not just config/namebound.json; active characters and identity preferences live in persistent overworld data.
• Use real Minecraft account names for administrative targeting. Character names are display identities, not authentication principals.
• Review server logs for scoreboard-conflict warnings after installs, config reloads, and player joins.
• Test with the same proxy, chat-reporting, scoreboard, permissions, and tab-list plugins/mods used in production because they may rewrite the same packets or team membership.