RpEssentials

RpEssentials is a comprehensive server-side utility mod built for immersive Roleplay servers running Minecraft 1.21.1 on NeoForge. It provides a complete suite of RP tools: proximity-based name obfuscation, a profession and license system, a warn system, connection tracking, private messaging, schedule automation, staff moderation tools, advanced chat formatting, world border warnings, named zones, Death RP, and deep LuckPerms integration. All configurable in real-time without restarts.

Current version: 4.1.9: See CHANGELOG for the full history.

Requirements

ImmersiveMessages and TxniLib are only required on the client if you use zoneMessageMode = IMMERSIVE. The server runs fine without them.

Installation

1. Download the latest rpessentials-X.X.X.jar from the releases page.
2. Place the JAR in your server's mods/ folder.
3. (Optional) Install LuckPerms for prefix/suffix and group-based staff permissions.
4. Start the server: all config files are generated automatically under config/rpessentials/.
5. Edit the relevant config files (see 'Configuration' below).
6. Reload in-game with /rpessentials config reload or restart the server.

Features

Proximity Obfuscation

Prevents metagaming by hiding player identities based on distance:

• Player names in the TabList and above heads are replaced with ????? beyond a configurable range (default: 8 blocks).
• Tab list player head hidden for obfuscated players: The skin icon next to an obfuscated player's name in the tab list is hidden, preventing skin-based identification. Non-obfuscated players, staff, whitelisted players, and always-visible players are unaffected.
• Sneak Stealth Mode: Crouching players are only detectable at 2 blocks (configurable).
• Nametag Hiding: Optionally hide all player nametags above heads server-wide.
• Whitelist: Players who always see all names clearly.
• Blacklist: Players who are always hidden regardless of distance (stealth staff, NPCs).
• Always Visible List: Players who are never obfuscated to anyone.
• Spectator Blur: Players in spectator mode are automatically hidden from the TabList.
• LuckPerms rank prefixes are always hidden during obfuscation to prevent rank-based metagaming.
• Staff with opsSeeAll see both nickname and real name simultaneously: Nickname (RealName).

Nickname System

Persistent RP nicknames fully integrated across all mod systems:

• Set custom nicknames with full § and & color code support.
• Nicknames appear in the TabList, above heads, in chat, and in private messages.
• Stored persistently in world/data/rpessentials/nicknames.json.
• /whois allows staff to reverse-lookup any nickname to its real MC username and UUID.

Nametag System

Realistic nametag behavior integrated with the nickname system:

• Block occlusion: Nametags are hidden when a block is between the viewer and the target. Implemented by switching Font.DisplayMode from SEE_THROUGH to NORMAL, activating the GPU depth test, same technique as the Realistic Nametag mod. No raycast, no performance overhead.
• Server nickname on nametag: The nametag displays the nickname set on the server (via /rpessentials nick), with the LuckPerms prefix and full color code support. Never uses a locally cached nickname.
• Global hide toggle: All nametags can be hidden server-wide via hideNametags = true in rpessentials-core.toml or /rpessentials config set hideNametags true/false.

Profession & License System

A complete job restriction system for RP servers:

• Define unlimited professions with custom names and color codes.
• Physical license items are given to players, carrying profession metadata and issuance date.
• RP Licenses: Decorative-only licenses for events, with a printed expiration date and no actual permissions.
• Restriction types: crafting, block breaking, item usage, equipment (armor/weapons), and attacks.
• Global restrictions apply to all players by default, with per-profession overrides for licensed players.
• Wildcard pattern support: minecraft:*_pickaxe blocks an entire item category.
• Restriction messages shown via action bar with anti-spam cooldown.
• Tooltips display required professions on restricted items (client-side packet sync).
• License Audit Log: Every GIVE, REVOKE, and GIVE_RP action is permanently logged to world/data/rpessentials/license-audit.json.
• Temp License Registry: RP licenses are tracked in world/data/rpessentials/licenses-temp.json.
• Revoked license items are automatically removed from the player's inventory.
• Whitelisted players are exempt from all profession restrictions (configurable).
• Granting or revoking a license automatically adds or removes the corresponding vanilla scoreboard tag (tag name = profession ID).

Warn System

Full staff warning system for moderation:

• Issue permanent or temporary warns to any online player.
• The warned player receives an immediate in-chat notification with the reason and duration.
• On every login, players are notified of their active warn count and invited to run /mywarn.
• /mywarn lets any player view their own active warns with reason, issuer, date, and remaining time.
• Configurable staff broadcast on every warn add and warn remove.
• Automatic purge of expired temp-warns on player login (configurable).
• Warn IDs are auto-incremental integers, recalculated after every deletion to avoid gaps.
• Data stored in world/data/rpessentials/warns.json.

Last Connection Tracking

Automatic recording of player connection history:

• Records last login and last logout for every player.
• Data stored in world/data/rpessentials/lastconnection.json: human-readable UUID (McUsername) key format.
• Staff can look up any player's last connection time, even for offline players.
• List view shows the N most recent connections sorted by date.

Private Messaging

Custom /msg system fully replacing vanilla messaging:

• /msg <player> <message>, /tell, /w, /whisper: send private messages with Rp Essentials formatting.
• /r <message>: reply to the last person who messaged you.
• Messages formatted with nicknames, LuckPerms prefixes/suffixes, and color codes.
• Clickable "Click to reply" button in received messages.
• Console-to-player messaging supported.

Advanced Chat

Full chat formatting system:

• Customizable player name format with LuckPerms prefix/suffix support ($prefix $name $suffix).
• Full message template with timestamp and color support ($time | $name: $msg).
• Global chat message color configuration (16 Minecraft colors available).
• Timestamp system with customizable Java SimpleDateFormat.
• Real-time Markdown support:
  • **text** → Bold
  • *text* → Italic
  • <span style="text-decoration: underline;">text</span> → Underline
  • ~~text~~ → Strikethrough
• /colors displays all available colors and formatting codes with a visual preview.
• Full integration with the nickname system, nicknames appear in chat automatically.

Join / Leave Messages

• Fully customizable join and leave messages with {player} and {nickname} placeholders.
• Full color code support.
• Can be disabled entirely.

Welcome Message

• Configurable multi-line welcome message sent to players on login.
• Optional sound effect with configurable volume and pitch.
• {player} and {nickname} variable support.
• Integrates with the schedule system to display server status.

Server Schedule

Automated server opening and closing management with per-day support:

• Each day of the week (MONDAY through SUNDAY) has its own enabled, open, and close fields.
• Disabled days are treated as fully closed.
• Automated warnings at 45, 30, 10, and 1 minute before closing.
• Smart kick system that only affects non-staff players.
• Staff receives notifications when the server opens or closes.
• The kick message displays the next open day and its hours (placeholders: {day}, {open}, {close}).
• /rpessentials schedule and /schedule display the full week at a glance with the current day highlighted.
• Aliases: /schedule and /horaires.

Death Hours

An optional schedule layer that activates Death RP during configured time slots, independently of the global Death RP toggle. Supports cross-midnight ranges. Disabled by default.

HRP Hours

An optional schedule layer for out-of-roleplay (HRP) period management:

• Two tiers: tolerated (noted but not punished) and allowed (fully free).
• Broadcast message sent once per slot start to all connected players.
• Configurable display mode: CHAT, ACTION_BAR, TITLE, IMMERSIVE.
• Disabled by default, entirely ignored when enableHrpHours = false.

Death RP

Permanent death system for RP servers:

• Global toggle enabling or disabling the system in real-time.
• Per-player overrides to enable, disable, or reset to the global state.
• On RP death: a broadcast is sent to all connected players with the deceased's nickname and real name.
• A configurable sound is played to all players on RP death.
• Optional automatic whitelist removal on RP death (whitelistRemove).
• All messages and sounds are fully configurable for both global and per-player toggles.

World Border & Named Zones

• Distance-based warning triggered by proximity to spawn (independent of the vanilla world border).
• Configurable message with {distance} and {player} placeholders.
• Named Zones: Define circular zones with center coordinates, radius, and custom entry/exit messages.
• Configurable display mode for zone messages: IMMERSIVE, CHAT, ACTION_BAR.

Staff Moderation Tools

Silent staff commands with full logging:

• Silent gamemode, teleport, and effect commands: invisible to other players.
• All actions logged to console and broadcast to other online staff (configurable).
• Target notification disabled by default (stealth mode).

Teleportation Platforms

• Define named platforms across dimensions with custom coordinates.
• Staff can teleport themselves or other players to any platform.
• /setplatform command to create or update a platform without editing the config file.

Roles

• Assign predefined roles to players via /rpessentials setrole.
• Automatically removes all existing role tags, adds the new tag, and sets the corresponding LuckPerms group.
• Roles configurable in rpessentials-core.toml under [Roles]. Format: roleId;lpGroup.
• Full tab-completion of available roles.
• Requires OP level 3.

Auto-Unwhitelist

Automatic removal of inactive players from the whitelist:

• Configurable inactivity threshold (days).
• Runs once per day at midnight.
• Requires enableLastConnection = true.
• Staff members online at the time receive a clickable cancel button to immediately re-whitelist the player.
• Optional extra commands executed per removed player. Placeholders: {player}, {uuid}.
• Disabled by default.

Staff Permission System

Multi-layered staff detection for maximum reliability:

• Scoreboard tags (admin, modo, staff, builder: configurable).
• Minimum OP level bypass (configurable from 0 to 4).
• LuckPerms group integration (configurable).
• Results cached for better performance (30-second cache).
• Automatic cache invalidation on logout.

Fully Configurable Messages

Every player-facing string in the mod is exposed as a configurable value via oneria-messages.toml:

• Full English translation of all messages out of the box.
• § and & color code support in all values.
• Reloadable at runtime with /rpessentials config reload (no restart required).
• Organized into clear sections: [System], [Private Messaging], [Warn System], [Last Connection], [Death RP], [Whois], [Player List], [Help], [Profession Restrictions].

Commands

Permissions: OP 2 = OP level ≥ 2; Staff = staff role detected by the mod's permission system; Everyone = all players.

Configuration

Nicknames

Licenses

Warns

Last Connection

Death RP

Roles

Staff

Whitelist / Blacklist

Messaging

Public

Configuration

The mod uses 6 config files under config/rpessentials/, generated automatically on first launch. All files are fully documented with inline comments.

rpessentials-core.toml

[Obfuscation Settings]

[Permissions System]

[World Border Warning]

[DeathRP]

[Roles]

rpessentials-chat.toml

[Chat Settings]

[Join / Leave Messages]

rpessentials-schedule.toml

[Schedule System | Per Day]

Each day of the week (MONDAY through SUNDAY) has its own fields:

[Messages]

[Welcome Message]

[Death Hours]

[HRP Hours]

[Auto-Unwhitelist]

rpessentials-moderation.toml

[Silent Commands]

[Teleportation Platforms]

[Last Connection]

[Warn System]

rpessentials-professions.toml

rpessentials-messages.toml

All player-facing strings are configurable in this file. It is generated automatically on first start and organized into sections:

Data Storage

All persistent data is stored in the world folder. Files are human-readable JSON and can be edited manually. Keys use the UUID (McUsername) format for readability.

All saves are asynchronous. All loads are synchronous at server startup.

LuckPerms Integration

LuckPerms is optional. The mod works fully without it, with graceful fallback:

• Without LuckPerms: staff detection falls back to scoreboard tags and OP levels. Prefix/suffix display is disabled.
• With LuckPerms: full integration with prefixes, suffixes, groups, and permission nodes.
• All LuckPerms-dependent features are silently skipped when the mod is absent.

Performance

• Permission checks: 30-second cache (~90% overhead reduction).
• Profession restriction checks: ~0.1ms per check (cached) (most of the verification is now event-based so almost no impact).
• License database queries: ~0.5ms (with caching).
• Network sync: ~1KB packet per player on login.
• Cache cleanup runs every 20 seconds to prevent memory leaks.
• Nametag block occlusion: zero raycast overhead, handled entirely by GPU depth test.
• Estimated total overhead: <1% CPU usage on active servers.

Technical Information