Lumen Singleplayer Utilities

A client-side Fabric mod of quality-of-life tools for single-player and your own worlds only. It adds entity highlights (ESP), floating entity info labels, an adjustable reach, and smooth creative-style flight.

⚠️ Single-player only by design. This is not a hack client. Every gameplay-altering feature automatically switches off the moment you join a multiplayer server or someone else's LAN world. There are no anti-cheat bypasses, packet exploits, or server-bypass features here, and none will be added — that behaviour is prohibited on virtually every Minecraft server.

• Minecraft: 1.21.1
• Loader: Fabric Loader (>=0.16)
• Mappings: Yarn 1.21.1+build.3
• Requires: Fabric API
• Optional: Mod Menu (adds a config button)

---

Features

1. Entity Highlight / ESP

• Clean box outline around nearby entities.
• Toggle each category independently: Players, Hostile mobs, Passive mobs, Items, Projectiles.
• Configurable highlight range.
• Does not render through walls by default. A separate X-Ray Highlight toggle exists for those who explicitly want see-through boxes; it is off by default.

2. Entity Info Display

• Floating label above entities, e.g. Zombie | 14.2m | 18/20 HP.
• Independently toggle name, distance, health, items, and whether labels show over hostile / passive mobs.
• Text is billboarded to face you and kept at a small, readable scale.

3. Reach Adjustment (single-player only)

• Configurable reach; when enabled, defaults to the safe survival cap.
• Safe caps: Survival max 6 blocks, Creative max 10 blocks (requests above the cap are clamped down; reach is never shortened below vanilla).
• Completely disabled on multiplayer. The config screen shows the warning: "Reach changes only work in single-player worlds."

4. Flight (single-player only)

• Keybind toggle for smooth, creative-style flight.
• Adjustable flight speed.
• Disabled on multiplayer; when turned off, your normal abilities are restored safely based on your game mode.

5. Config Screen

• Mod Menu-compatible screen (also openable via keybind — no Mod Menu required).
• All settings, saved to config/lumen.json.

---

Installation

1. Install Fabric Loader for Minecraft 1.21.1.
2. Download Fabric API for 1.21.1 and put it in your mods folder.
3. (Optional) Download Mod Menu for 1.21.1.
4. Build this mod (see Building) and copy build/libs/lumen-singleplayer-utilities-1.0.0.jar into your mods folder.
5. Launch the game with the Fabric profile.

---

Keybinds

Set in the vanilla Options → Controls screen under "Lumen Singleplayer Utilities". Defaults:

Action	Default key
Toggle Entity Highlights	H
Toggle Flight	G
Open Lumen Menu	Right Shift
Cycle Highlight Category	N

Cycle Highlight Category advances a focus pointer through the categories and flips that category's highlight on/off, with on-screen feedback.

---

Config

Stored as JSON at .minecraft/config/lumen.json and editable in-game.

Key	Meaning
highlightsEnabled	Master toggle for ESP boxes
highlightRange	Max distance (blocks) for boxes/labels
xrayHighlight	Render boxes/labels through walls (default false)
highlightPlayers / highlightHostiles / highlightPassives / highlightItems / highlightProjectiles	Per-category box toggles
infoEnabled	Master toggle for info labels
showNames / showDistance / showHealth / showItems	Which label parts show
infoOnHostiles / infoOnPassives	Which mob types get labels
infoTextScale	Label text size
reachEnabled	Enable reach adjustment (single-player only)
reachDistance	Requested reach (clamped to 6 survival / 10 creative)
flightEnabled	Enable flight (single-player only)
flightSpeed	Flight speed multiplier (0.25×–5×)
selectedCategory	Category targeted by the cycle keybind
showToggleMessages	Show action-bar feedback on toggles

---

Project layout

src/main/java/com/lumen/singleplayer/
├── LumenClient.java            # client entrypoint, wires everything together
├── config/                     # LumenConfig (pure data), ConfigManager (JSON), EntityCategory
├── util/                       # WorldUtil (single-player gate), EntityClassifier, HudMessenger
├── keybinds/                   # KeyBindings (registration + input handling)
├── render/                     # EntityHighlightRenderer, EntityInfoRenderer, LumenRenderLayers
├── features/                   # ReachFeature, FlightFeature (safety + policy)
├── mixin/                      # PlayerEntityReachMixin (version-specific shim)
└── gui/                        # LumenConfigScreen + gui/modmenu/LumenModMenu

Safety architecture: util/WorldUtil.isOwnedSingleplayer() is the single gate. It returns true only when the local client owns the world (pure single-player, or hosting your own LAN world) by checking that an in-process integrated server exists. Reach and flight both consult it and disable themselves otherwise. See the class Javadoc for why this is preferred over MinecraftClient.isInSingleplayer().

---

Building

Requires JDK 21.

./gradlew build

The mod jar is written to build/libs/. To run a dev client:

./gradlew runClient

---

Updating to newer Minecraft versions

The project is structured to keep the update surface small.

1. Bump the versions in gradle.properties — this is the primary place: minecraft_version, yarn_mappings, loader_version, fabric_version, and modmenu_version. Find matching values at fabricmc.net/develop and the Mod Menu page.
2. Fix any renamed Yarn mappings. Version-sensitive code is deliberately isolated to a few files (grep for the "Updating for a new Minecraft version" notes):
   • mixin/PlayerEntityReachMixin.java — the two reach getter method names.
   • render/LumenRenderLayers.java — the RenderLayer/RenderPhase builder API.
   • render/EntityHighlightRenderer.java / EntityInfoRenderer.java — the WorldRenderContext accessors and WorldRenderer.drawBox signature.
   • util/EntityClassifier.java — the entity class names used for categories. The pure-data (config/LumenConfig), gating (util/WorldUtil) and feature policy (features/*) classes rarely need changes.
3. Recommended branching strategy. Keep one branch per Minecraft version (e.g. mc/1.21.1, mc/1.21.4, …). Develop features on the newest branch and cherry-pick fixes back. Because all version numbers live in gradle.properties and the MC-touching code is isolated, most of a version bump is a properties edit plus a handful of mapping fixes.
   • If you prefer a single multi-version codebase, this layout also adapts cleanly to a preprocessor like Stonecutter; the isolated files above are exactly where the version comments would go.

---

License

MIT — see LICENSE.