Username Changing System

LUA_SCRIPTING.md

@@ -7,6 +7,7 @@ AmbleKit includes a powerful Lua scripting engine (powered by LuaJ) that allows
 - [Commands](#commands)
 - [Lifecycle Callbacks](#lifecycle-callbacks)
 - [Minecraft API Reference](#minecraft-api-reference)
+- [Module System (require)](#module-system-require)
 - [Entity API](#entity-api)
 - [ItemStack API](#itemstack-api)
 - [Example Scripts](#example-scripts)
@@ -142,21 +143,135 @@ The `mc` parameter provides access to Minecraft data. Methods vary by side:
 | `mc:isDedicatedServer()` | True if dedicated server |
 | `mc:runCommandAs(playerName, command)` | Run command as specific player |
 
-### Skin Management (Server-Only)
+### Skin Management (Client & Server)
 
 All skin methods return `true` on success, `false` on failure.
 
+On server: Methods directly modify the skin tracker and sync to clients.
+On client: Methods run the equivalent `/amblekit skin` command (requires op permissions).
+
+**By Player Name (Client & Server):**
 | Method | Description |
 |--------|-------------|
 | `mc:setSkin(playerName, skinUsername)` | Set player's skin to another player's skin |
 | `mc:setSkinUrl(playerName, url, slim)` | Set player's skin from URL (slim: true/false) |
 | `mc:setSkinSlim(playerName, slim)` | Change arm model without changing texture |
 | `mc:clearSkin(playerName)` | Remove custom skin, restore original |
 | `mc:hasSkin(playerName)` | Check if player has a custom skin |
+| `mc:hasSkinByUuid(uuid)` | Check if entity has custom skin by UUID |
+
+**By UUID String (Server-Only):**
+| Method | Description |
+|--------|-------------|
 | `mc:setSkinByUuid(uuid, skinUsername)` | Set skin by UUID string |
 | `mc:setSkinUrlByUuid(uuid, url, slim)` | Set skin from URL by UUID string |
 | `mc:clearSkinByUuid(uuid)` | Clear skin by UUID string |
-| `mc:hasSkinByUuid(uuid)` | Check if entity has custom skin by UUID |
+
+### Username/Nametag Management (Client & Server)
+
+Custom display names (nametags) can be set for any entity. These override the rendered nametag and sync to all clients.
+
+On server: Methods directly modify the username tracker and sync to clients.
+On client: Methods run the equivalent `/amblekit username` command (requires op permissions).
+
+All username methods return `true` on success, `false` on failure (except getters).
+
+**By Player Name (Client & Server):**
+| Method | Description |
+|--------|-------------|
+| `mc:setUsername(playerName, displayName)` | Set player's display name (supports § formatting) |
+| `mc:setUsernameJson(playerName, jsonText)` | Set display name using JSON Text component |
+| `mc:clearUsername(playerName)` | Remove custom display name, restore original |
+| `mc:hasUsername(playerName)` | Check if player has a custom display name |
+| `mc:getUsername(playerName)` | Get current custom display name (or nil) |
+| `mc:hasUsernameByUuid(uuid)` | Check if entity has custom name by UUID |
+| `mc:getUsernameByUuid(uuid)` | Get custom display name by UUID (or nil) |
+
+**By UUID String (Server-Only):**
+| Method | Description |
+|--------|-------------|
+| `mc:setUsernameByUuid(uuid, displayName)` | Set display name by UUID string |
+| `mc:setUsernameJsonByUuid(uuid, jsonText)` | Set JSON display name by UUID string |
+| `mc:clearUsernameByUuid(uuid)` | Clear display name by UUID string |
+
+**Example - Simple colored name:**
+```lua
+mc:setUsername("Steve", "§c§lRed Steve")  -- Bold red name
+```
+
+**Example - JSON Text with hover:**
+```lua
+mc:setUsernameJson("Steve", '{"text":"Admin","color":"gold","bold":true}')
+```
+
+---
+
+## Module System (require)
+
+Scripts can import other scripts as modules using the `require` function. This allows you to share code between scripts.
+
+### Usage
+
+```lua
+local MyModule = require("namespace:module_name")
+```
+
+The module path follows the format `namespace:script_name` (without `.lua` extension or `script/` prefix).
+
+### Creating a Module
+
+Modules should return a table containing their exported functions and values:
+
+```lua
+-- assets/mymod/script/utils.lua
+local Utils = {}
+
+function Utils.greet(name)
+    return "Hello, " .. name .. "!"
+end
+
+function Utils.clamp(value, min, max)
+    return math.max(min, math.min(max, value))
+end
+
+return Utils
+```
+
+### Using a Module
+
+```lua
+-- assets/mymod/script/main.lua
+local Utils = require("mymod:utils")
+
+function onExecute(mc)
+    local message = Utils.greet(mc:username())
+    mc:sendMessage(message, false)
+
+    local clamped = Utils.clamp(150, 0, 100)  -- Returns 100
+end
+```
+
+### Module Caching
+
+Modules are cached after first load - calling `require` multiple times with the same path returns the same cached instance. The cache is cleared when resources are reloaded.
+
+### Nested Requires
+
+Modules can require other modules:
+
+```lua
+-- assets/mymod/script/advanced.lua
+local Utils = require("mymod:utils")
+local Config = require("mymod:config")
+
+local Advanced = {}
+
+function Advanced.doSomething()
+    return Utils.greet(Config.defaultName)
+end
+
+return Advanced
+```
 
 ---
 

SKIN_SYSTEM.md

@@ -9,6 +9,7 @@ AmbleKit provides a dynamic player skin system that allows you to change player
 - [Skin Sources](#skin-sources)
 - [Persistence](#persistence)
 - [Integration](#integration)
+- [Username/Nametag System](#usernamenametag-system)
 
 ---
 
@@ -253,26 +254,29 @@ function onExecute(mc)
 end
 ```
 
-#### Server-Side Skin API Methods
+#### Skin API Methods (Client & Server)
 
 All skin methods return `true` on success, `false` on failure (player not found, invalid UUID, etc.).
 
-**By Player Name:**
+On server: Methods directly modify the skin tracker and sync to clients.
+On client: Methods run the equivalent `/amblekit skin` command (requires op permissions).
+
+**By Player Name (Client & Server):**
 | Method | Description |
 |--------|-------------|
 | `mc:setSkin(playerName, skinUsername)` | Set player's skin to another player's skin |
 | `mc:setSkinUrl(playerName, url, slim)` | Set skin from URL (slim = true for Alex arms) |
 | `mc:setSkinSlim(playerName, slim)` | Change arm model (true = slim/Alex, false = wide/Steve) |
 | `mc:clearSkin(playerName)` | Remove custom skin, restore original |
 | `mc:hasSkin(playerName)` | Check if player has a custom skin |
+| `mc:hasSkinByUuid(uuid)` | Check if entity has custom skin by UUID |
 
-**By UUID String:**
+**By UUID String (Server-Only):**
 | Method | Description |
 |--------|-------------|
 | `mc:setSkinByUuid(uuid, skinUsername)` | Set skin by UUID string |
 | `mc:setSkinUrlByUuid(uuid, url, slim)` | Set skin from URL by UUID string |
 | `mc:clearSkinByUuid(uuid)` | Clear skin by UUID string |
-| `mc:hasSkinByUuid(uuid)` | Check if entity has custom skin by UUID |
 
 #### Complete Example: Disguise System
 
@@ -469,6 +473,110 @@ data = data.withSlim(true);
 
 ---
 
+## Username/Nametag System
+
+AmbleKit includes a dynamic username/nametag system that allows you to change entity display names at runtime. This works similarly to the skin system.
+
+### Overview
+
+The Username System provides:
+- **Runtime Name Changes** - Change entity nametags without relogging
+- **Rich Text Support** - Full Minecraft Text component support (colors, styles, hover events)
+- **Server Synchronization** - Names sync automatically to all connected clients
+- **Persistent Storage** - Custom names persist across server restarts (saved to `amblekit/usernames.json`)
+- **Universal Entity Support** - Works with any entity by UUID
+
+### Commands
+
+All username commands require operator permissions (level 2).
+
+#### Set Display Name
+
+```
+/amblekit username <target> set <name>
+```
+
+The name supports Minecraft formatting codes (§) and JSON Text format.
+
+**Examples:**
+```
+/amblekit username @p set §c§lRed Bold Name
+/amblekit username @p set {"text":"Admin","color":"gold","bold":true}
+```
+
+#### Clear Display Name
+
+```
+/amblekit username <target> clear
+```
+
+### Java API
+
+```java
+import dev.amble.lib.username.UsernameTracker;
+import net.minecraft.text.Text;
+
+// Get the target entity's UUID
+UUID targetUuid = entity.getUuid();
+
+// Set simple display name
+Text displayName = Text.of("§aGreen Name");
+UsernameTracker.getInstance().putSynced(targetUuid, displayName);
+
+// Set rich text display name
+Text richName = Text.literal("Admin")
+    .styled(style -> style.withColor(0xFFAA00).withBold(true));
+UsernameTracker.getInstance().putSynced(targetUuid, richName);
+
+// Clear custom display name
+UsernameTracker.getInstance().removeSynced(targetUuid);
+
+// Check if entity has custom name
+boolean hasCustomName = UsernameTracker.getInstance().containsKey(targetUuid);
+
+// Get custom name (may be null)
+Text customName = UsernameTracker.getInstance().get(targetUuid);
+```
+
+### Lua API (Client & Server)
+
+See [Lua Scripting System](LUA_SCRIPTING.md) for full documentation.
+
+On server: Methods directly modify the username tracker and sync to clients.
+On client: Methods run the equivalent `/amblekit username` command (requires op permissions).
+
+```lua
+-- Set display name with formatting codes (Client & Server)
+mc:setUsername("Steve", "§c§lRed Steve")
+
+-- Set display name with JSON Text (Client & Server)
+mc:setUsernameJson("Steve", '{"text":"Admin","color":"gold"}')
+
+-- Clear custom name (Client & Server)
+mc:clearUsername("Steve")
+
+-- Check if player has custom name (Client & Server)
+if mc:hasUsername("Steve") then
+    local name = mc:getUsername("Steve")
+end
+
+-- By UUID (Server-Only)
+mc:setUsernameByUuid(uuid, "§bCustom Name")
+mc:clearUsernameByUuid(uuid)
+```
+
+### Persistence
+
+Custom display names are saved to `<world>/amblekit/usernames.json` and automatically loaded when the server starts. The format is:
+
+```json
+{
+  "uuid-string": {"text":"Display Name","color":"red"}
+}
+```
+
+---
+
 ## See Also
 
 - [Lua Scripting System](LUA_SCRIPTING.md) - Full skin management API for server scripts

src/main/java/dev/amble/lib/AmbleKit.java

@@ -9,8 +9,10 @@
 import dev.amble.lib.command.PlayAnimationCommand;
 import dev.amble.lib.command.ServerScriptCommand;
 import dev.amble.lib.command.SetSkinCommand;
+import dev.amble.lib.command.SetUsernameCommand;
 import dev.amble.lib.script.ServerScriptManager;
 import dev.amble.lib.skin.SkinTracker;
+import dev.amble.lib.username.UsernameTracker;
 import dev.drtheo.multidim.MultiDimMod;
 import dev.drtheo.scheduler.SchedulerMod;
 import net.fabricmc.api.ModInitializer;
@@ -36,11 +38,13 @@ public void onInitialize() {
         AmbleRegistries.getInstance();
         ServerLifecycleHooks.init();
 		SkinTracker.init();
+		UsernameTracker.init();
 		AnimationTracker.init();
 		ServerScriptManager.getInstance().init();
 
 		CommandRegistrationCallback.EVENT.register((dispatcher, access, env) -> {
 			SetSkinCommand.register(dispatcher);
+			SetUsernameCommand.register(dispatcher);
 			PlayAnimationCommand.register(dispatcher);
 			ServerScriptCommand.register(dispatcher);
 		});