Dynamic Item Lighting

**Carry light with you.**

Keep a torch in your offhand while exploring, leave a glowing lantern where it lands, or fit your helmet with a rechargeable headlamp to free both hands. Dynamic Item Lighting makes portable light sources illuminate nearby blocks and creatures, with colors that suit the item you carry.

**For Minecraft: Java Edition 1.21.1 · NeoForge 21.1.200 or newer on the 1.21.1 line · Java 21.** Built and tested with NeoForge 21.1.252. No additional mod dependencies are required.

**The lighting is visual only.** It does not place light blocks or change world light levels, mob spawning, crop growth, mob AI, or the light values shown on the F3 screen. A cave that looks bright can still spawn hostile mobs.

## Light that travels with you

- **Held items:** Luminous items in either hand light your surroundings. The system also tracks held lights on nearby players and mobs.
- **Dropped items:** Supported items continue illuminating the area after being thrown or dropped, until picked up, merged, or despawned.
- **83 bundled vanilla item rules:** Torches, lanterns, froglights, candles, glowstone, lava buckets, and more have individual brightness and color settings.
- **Water-aware sources:** Ordinary torches and other flame-based sources stop shining underwater. Lanterns and headlamps keep working, while sea pickles shine only in water. Redstone torches also keep glowing underwater.
- **No stacking brightness:** A stack of torches is as bright as one torch. Overlapping lights use the strongest brightness rather than adding together.

## Color for dark places

Torchlight has a warm amber tint, soul lights shine blue, redstone torches glow red, and candles follow their dye colors. Dynamic light tints terrain and living creatures where it is brighter than the existing lighting; it does not recolor daylight or placed lights.

Color is applied as a rendering tint. Held items, particles, and block entities such as chests receive additional brightness without the color tint. Shader packs may change or hide the result.

## Rechargeable headlamps

Attach a lamp to a helmet and explore with both hands available. The helmet keeps its armor, durability, enchantments, trim, and custom name. Lamp charge is separate from helmet durability.

Craft one at a crafting table using this pattern:

```text
Glass block | Glass pane   | Glass block
Glass block | Power source | Glass block
Glass block | Helmet       | Glass block
```

All six glass blocks must be the same item. Choose clear glass, tinted glass, or one of the 16 stained glass colors. Clear glass uses the power source's color; stained glass overrides it, while tinted glass gives a smoky violet tint. The top glass pane does not determine the light color.

| Power source | Default brightness | Full charge | Recharge item |
| --- | --- | --- | --- |
| Torch | 14 | 20 minutes | Torch or soul torch |
| Soul torch | 10 | 20 minutes | Soul torch or torch |
| Redstone lamp | 14 | 40 minutes | Redstone lamp only |
| Redstone torch | 7 | 60 minutes | Redstone torch only |

- **Switch the worn lamp on or off:** Press **H** (rebindable), or crouch and right-click with an empty main hand. While wearing a headlamp, that crouch-click gesture is reserved for the lamp.
- **Recharge in a crafting grid:** Place the matching recharge item directly above the headlamp, with nothing else in the grid. The 2×2 inventory grid works. The item is consumed and the lamp returns fully charged and switched on, keeping its glass color and helmet durability.
- **Switch torch type:** Recharging a torch-powered lamp with a soul torch changes it to the soul version, and vice versa. Redstone dust does not recharge either redstone variant.
- **Change glass or power source:** Use the full crafting-table recipe again with the existing headlamp as the helmet.
- **Track charge:** The lamp has a charge bar and tooltip. Charge normally drains only while the lamp is worn and switched on; see the edge cases below.

Server settings can change charge times and brightness for newly crafted or recharged headlamps.

## Glow berries: Luminous

Eating glow berries gives players the **Luminous** effect for **30 seconds**, producing a warm yellow light at level 10. Eating more restarts the timer, and milk removes the effect. Holding glow berries provides a weaker level-5 light without eating them.

## Singleplayer and multiplayer

Install the mod JAR in the `mods` folder of your NeoForge 1.21.1 installation. For multiplayer, install the mod on **the server and every player's client**. It registers recipes, headlamp data, and the Luminous effect, so clients without the mod cannot join a server that has it. Client-only use on a server without the mod is unverified and may be refused by NeoForge.

Lighting is drawn on each client. The server handles shared item rules, headlamp charge, and Luminous synchronization. In singleplayer, local rules are used by default; on a modded server, shared server rules normally take precedence. Each player can choose their own rendering quality and turn the visual effect off.

Dedicated development-server joining and rule synchronization have recorded tests. Two-player checks of headlamps, toggling, and Luminous visibility remain outstanding.

## Settings and custom item rules

- **Client configuration:** `config/dynamicitemlights-client.toml` controls the effect toggle, held and dropped sources, discovery distance, automatic quality scaling, diagnostics, and renderer mode.
- **Quality presets:** Low, Balanced, and High cap active lights at 16, 48, and 96 respectively. Balanced is the default. Automatic scaling can lower quality when the mod's work exceeds its budget.
- **Server configuration:** `config/dynamicitemlights-server.toml` controls shared policy, held and dropped sources, invisibility exclusion, and headlamp brightness and charge times.
- **JSON item rules:** Customize brightness, color, underwater behavior, and eligibility using local files or resource packs; server owners can distribute rules through data packs. Local loose rules go in `config/dynamicitemlights/items/<namespace>/<name>.json`.
- **Modded items:** Items that place light-emitting blocks can be discovered automatically from their default block state. Other items, or context-dependent emitters, may need explicit rules.

Useful commands:

- `/dilclient toggle` — enable or disable your dynamic lighting.
- `/dilclient quality low|balanced|high` — choose your maximum quality preset.
- `/dilclient status` — inspect active lights, renderer status, and diagnostics.
- `/dilclient export_catalog` — export installed-item lighting information for rule editing.
- `/dilpolicy reload` and `/dilpolicy status` — reload or inspect server rules; operator permission is required.

Reload local rules with **F3 + T**. Source caps and scheduled terrain updates help manage rendering work, but performance depends on your hardware, world, and installed mods.

## Compatibility and known limitations

- **Vanilla renderer:** Implemented and tested. This is the verified rendering setup.
- **Embeddium, Sodium, and Rubidium:** Unverified. In the default `AUTO` mode, detection disables this mod's lighting. `FORCE_ENABLE` is an untested override, not a guarantee of compatibility.
- **Other dynamic-light mods:** Detection of known competing mod IDs also disables this mod's renderer in `AUTO`. Choose one lighting system; this mod does not disable other mods for you.
- **Iris, Oculus, and shader packs:** Unverified. A notice is shown, but this mod keeps rendering. Shader packs may show white light, hide the effect, or supply their own handheld lighting.
- **Modded helmets and glass:** Recipes use standard helmet and glass tags. Support is implemented, but specific third-party combinations have not been tested.
- **Light passes through walls:** There is no shadow or wall-occlusion calculation. Fast movement can also leave a brief lighting trail while terrain redraws catch up.
- **Tint refresh:** A stationary light's terrain tint may retain its previous appearance until that area redraws, including around dusk.
- **Headlamp charge edge cases:** Dropping a lamp directly from the cursor immediately after removing it can leave its charge draining until pickup. Lamps on mobs can drain while their chunks are unloaded.

## Development status

Version **1.3.1** includes the corrected headlamp recharge rules. The features described above are implemented, with unit tests and in-game development checks recorded for the core systems. Third-party renderer and shader support, specific modded equipment, two-player feature visibility, production-server validation, and large-server or real-hardware performance checks remain unverified.