Better Light

Better Light brings immersive, portable lighting to Minecraft. Clip a lantern to your belt and keep both hands free, watch it sway naturally as you walk, run, and jump, and grab torches or lanterns straight off the ground with a single right-click instead of breaking and re-placing them.

The mod is built to feel like a natural extension of vanilla survival — no new blocks to craft, no bulky UI, just smarter, more physical lighting layered on top of the items you already use. It's lightweight and fully multiplayer-friendly, with every gameplay effect running on the server and only the visuals handled client-side.

Features

🏮 Dynamic lighting

Any light-emitting item you're holding — or wearing on your belt — casts real light into the world, not just onto your hand. Light fades smoothly in and out rather than snapping on and off, follows you as you move, and automatically respects any vanilla or modded item that emits light. It also dims appropriately when the source is on your belt rather than in your hand, capped by a configurable maximum radius.

👖 Belt slot

Attach a torch or lantern to your belt to light your way hands-free. Equip or unequip it by holding Shift and right-clicking with empty air (with a light source in hand, or already worn), or bind a dedicated hotkey (default: N) from the Controls menu. The equipped item is visibly modeled on your character and swings with its own inertia as you move, turn, and jump — see Physics below.

🖱️ Instant pickup

Right-click a placed torch, soul torch, lantern, or soul lantern and it's collected straight into your inventory — no mining animation, no accidental block breaking, no tool required.

🎨 Visible equipment rendering

The lantern on your belt isn't just a stat effect — it's rendered on your character model (compatible with both default and slim skins), positioned and angled to sit naturally at hip level.

🕯️ Swinging physics

Two independent spring-based physics systems make lanterns feel alive:

• Belt lantern physics — reacts to your own movement and camera turns, with configurable intensity, stiffness, damping, and maximum swing angle.
• Hanging lantern physics — any lantern hung from a chain in the world sways in a simulated wind, factoring in rain, thunderstorms, and nighttime for extra motion, while lanterns tucked away in the Nether or the End stay nearly still. Chains above a swinging lantern move together with it as a single rigid pendulum, up to a configurable chain length.

🌒 Monsters react to light

Optionally, a lit lantern on your belt makes you easier for nearby monsters to notice from farther away — but the light also weakens them, applying a periodic Weakness effect while they linger nearby. Detection range, the follow-range bonus, and the Weakness amplifier are all configurable, and the effect can be turned off entirely.

✨ Decorative colored glow (API)

Other mods can register a custom glow color for their own light-emitting items. Since Minecraft's lighting engine only supports a single brightness value (not full RGB), this is implemented as a subtle particle effect near the item rather than true colored light — but it's a nice finishing touch for modpacks with custom lanterns.

⚙️ Fully configurable

Nearly every number above — brightness, radius, update frequency, belt position and rotation, swing feel, wind strength, monster-effect ranges — is exposed through Forge's config system and tunable per-world (common) or per-client (client-only rendering options). In-game, an in-inventory gear button also opens a quick settings screen for adjusting belt height, side offset, forward offset, and rotation on the fly.

Controls

Action	Default
Toggle belt lantern (equip/unequip)	Shift + Right-click (empty hand)
Toggle belt lantern (hotkey)	N (can be disabled/rebound)
Open belt settings	Gear button in the inventory screen
Pick up a placed torch/lantern	Right-click the block

Configuration

Better Light splits its settings into two config files, generated on first launch under config/:

Common (betterlight-common.toml) — server-authoritative, affects all players:

• dynamicLightEnabled, multiplayerEnabled, updateIntervalTicks
• brightnessMultiplier, maxLightLevel, beltDimming
• itemLightOverrides — add or override light levels for any item, e.g. "minecraft:blaze_rod=8"
• instantTorchPickup
• monsterLightEffectEnabled, monsterLightDetectionRange, monsterLightDetectionBonus, monsterLightWeaknessAmplifier, monsterLightWeaknessDurationTicks

Client (betterlight-client.toml) — local rendering and feel, safe to differ between players:

• Belt positioning: beltHeightOffset, beltSideOffset, beltForwardOffset, beltRotationOffset, useKeybindForBelt
• Belt swing physics: swingEnabled, swingIntensity, swingStiffness, swingDamping, swingMaxAngle
• Hanging lantern physics: hangingLanternPhysicsEnabled, wind strength/speed/stiffness/damping/max angle/max velocity, influence distance, max chain length, and weather/time-of-day multipliers for rain, thunder, and night
• Decorative colored glow: coloredLightEnabled, particle interval, particle scale

Most players will never need to touch these files — the defaults are tuned to feel right out of the box — but they're there for anyone who wants to fine-tune performance or feel, or for pack authors adjusting balance.

For Mod Developers

Better Light exposes a small public API (com.kaistudio.betterlight.api.IBetterLightAPI) for other mods to hook into, retrieved via BetterLightAPI.getInstance(). It lets other mods:

• Register or unregister an item as a custom light source, with its own light level
• Register a custom block as a dynamic-light source
• Read or set a player's belt item, or toggle it programmatically
• Query the current config state (dynamic light enabled, swing settings, monster-effect settings, etc.)
• Register a decorative glow color for a light-emitting item
• Query wind exposure at a given position, to sync custom effects (like a candle flicker) with the same wind simulation Better Light uses for hanging lanterns

IBetterLightAPI api = BetterLightAPI.getInstance();
if (api != null) {
    api.registerLightSource("mymod:glowing_item", 12);
    api.registerColoredLightSource("mymod:glowing_lantern", 0.2f, 0.6f, 1.0f);
    api.togglePlayerBelt(player);
}