Dynamic Lights Mod Guide: Portable Light Sources for Minecraft
Dynamic Lights makes light-emitting items actually illuminate their surroundings when held, worn, or dropped on the ground. Instead of fumbling through dark caves with a Torch that only lights up when placed, you can simply hold one and see where you're going. The mod is fully configurable, letting you add any item as a light source.
Overview
Dynamic Lights is a client-side lighting mod that makes any "shining" item illuminate the world around it in real time. In vanilla Minecraft, a Torch only produces light after you place it on a wall or floor. With this mod installed, simply holding a Torch in your hand lights up the area as you walk. This works for both the main hand and the off hand, as well as armor slots, so you can wear light-emitting gear and glow as you explore.
The mod also tracks dropped items on the ground. If you toss a Torch on the floor, it will emit light right where it lands. Entities that are on fire also glow at full brightness (light level 15), which means burning Zombies and flaming Arrows will illuminate their surroundings. You can browse the full item and recipe listings using the tabs at the top of this page, though Dynamic Lights itself doesn't add any new craftable items. It simply enhances how existing light-emitting items behave.
Getting Started
- 1
Install and Launch
Drop the Dynamic Lights JAR file into your mods folder. The mod must be installed on both the client and the server if you're playing multiplayer. On first launch, it will generate three configuration files in your .minecraft/config directory.
- 2
Hold a Torch and Walk Into Darkness
Grab a Torch and hold it in either hand. Walk into a dark cave or wait for nightfall. You'll see the light move with you in real time, illuminating blocks as you pass. The Torch emits light level 15 (full brightness), the same as a placed Torch.
- 3
Try Your Off Hand
Place a Torch in your off hand so you can hold a Pickaxe in your main hand and still have portable light. The mod checks both hands and uses whichever has the higher light value. This is the most practical way to use Dynamic Lights while mining.
- 4
Learn the Toggle Key
Press the L key (default binding, found under Gameplay in Controls) to toggle all dynamic lights on or off. A chat message will confirm whether lights are globally enabled or disabled. This is useful when you need to boost FPS in areas with many light sources, or when you want to see the "true" darkness level of a cave to check for mob spawning.
- 5
Customize Your Light Sources
Open the config files in your .minecraft/config folder to add custom items as light sources. You can make any item in the game emit dynamic light, including modded items. See the Configuration section below for details on each config file.
Dynamic Lights requires installation on both the client and the server for multiplayer. It works by placing and rapidly removing invisible light-emitting blocks as light sources move, which requires server-side cooperation.
How Dynamic Lights Works
The mod operates through two independent modules that handle different scenarios: one for the player character and one for dropped item entities.
Player Self Light
The PlayerSelfLightSource module checks what the player is holding and wearing every tick. It examines the main hand, off hand, and all four armor slots. If any equipped item matches the configured light source list, the player character becomes a moving light emitter at light level 15. When both hands hold light items, the mod uses whichever produces the higher light value. Armor items are also checked, so you could configure a modded helmet or chestplate to glow while worn.
Dropped Items Light
The DroppedItemsLightSource module scans all item entities in the loaded world at a configurable interval (default: 1000 milliseconds). Any dropped item that matches the light source list will emit light level 15 from where it lies on the ground. This means you can toss Torches ahead of you into a dark room to light it up before entering, a practical scouting technique.
Burning Entities
Any entity that is on fire automatically emits light level 15, regardless of item configuration. This includes mobs that catch fire at dawn, players hit by Fire Aspect weapons, and any entity standing in Lava. Burning Zombies stumbling through the night will actually illuminate the terrain around them.
Water and Light Interactions
Not all light sources work underwater. The mod distinguishes between waterproof and non-waterproof items through a separate configuration list. By default, Torches are listed as non-waterproof. If you swim underwater while holding a Torch, it will stop emitting dynamic light. However, you can add items like Glowstone or Sea Lanterns to the light source list without adding them to the non-waterproof list, making them function as underwater light sources.
An important limitation: the mod only works with full Water source blocks, not flowing Water or partial Water blocks. If you're standing in a waterfall or shallow river that uses flowing Water blocks, the waterproofing check may not trigger correctly. Similarly, dynamic lights will not function if the light source entity is inside a non-air block like Foliage, Cobwebs, or Tall Grass.
Dynamic lights are FPS-intensive. Each moving light source forces the game to recalculate lighting for surrounding blocks every time it moves. Having many light sources active at once (for example, a large number of dropped Torches or many burning mobs) can cause noticeable frame rate drops. Use the L key to toggle lights off if you experience performance issues.
Configuration
Dynamic Lights creates three configuration files in your .minecraft/config directory, all in JSON format. Understanding these files lets you fully customize which items emit light and how the mod behaves.
dynamiclights.cfg
The main configuration file. Contains a "bannedDimensions" list that disables dynamic lights in specific dimension IDs. By default, dimensions 77 and 88 are banned (these are commonly used by mods like Mystcraft or RFTools Dimensions). Add any dimension ID to this list if you want to disable dynamic lighting there for performance or compatibility reasons.
dynamiclights_selflight.cfg
Controls which items emit light when the player holds or wears them. Contains two lists: "itemsList" defines which items produce light, and "notWaterProofList" defines which of those items stop working underwater. By default, Torches are included in both lists. To add a custom item, use the NBT format with a "nameId" field matching the item's registry name (e.g., {"nameId":"minecraft:glowstone"}).
dynamiclights_droppeditems.cfg
Controls which items emit light when dropped on the ground as entities. Uses the same format as the self-light config. Additionally includes an "updateInterval" setting (default: 1000 milliseconds) that controls how frequently the mod scans for dropped items. Lowering this value makes dropped items light up faster but increases CPU usage. Raising it reduces overhead but introduces a delay before dropped items start glowing.
Configuration Defaults
| Toggle Key | L (Gameplay category) |
| Default Light Items | Torch |
| Light Level Emitted | 15 (maximum) |
| Dropped Item Scan Interval | 1000ms |
| Banned Dimensions | 77, 88 |
| Non-Waterproof Items | Torch |
Mod Compatibility
Dynamic Lights works with any mod that adds items, since you can manually add modded items to the config files. The mod provides an API (the IDynamicLightSource interface) that other mod developers can use to register their own entities as dynamic light sources programmatically, without requiring config file edits.
The banned dimensions feature is particularly useful for compatibility with dimension-adding mods. If you experience issues or performance problems in a specific modded dimension, simply add its ID to the bannedDimensions list in dynamiclights.cfg. The mod uses Mixin to intercept the game's light calculation system, so it generally works alongside other rendering and lighting mods, though conflicts with other mods that heavily modify the lighting engine are possible.
To find an item's registry name for the config, press F3+H in-game to enable advanced tooltips. Hover over the item to see its full ID (e.g., "minecraft:torch" or "thermalexpansion:frame"). Use this ID as the "nameId" value when adding it to the items list.
Frequently Asked Questions
Do dynamic lights prevent mob spawning?
No. Dynamic lights are purely visual. The mod intercepts the rendering light calculation but does not change the block light levels that the game uses for mob spawning logic. You must place actual light source blocks (Torches, Glowstone, etc.) to prevent spawns.
Why does my Torch stop glowing underwater?
Torches are listed in the notWaterProofList by default. When you submerge in a full Water source block while holding a Torch, the mod disables its light emission. To have underwater lighting, add a waterproof item (like Glowstone or a Sea Lantern) to the itemsList without adding it to the notWaterProofList.
Can I change the keybind for toggling dynamic lights?
Yes. The toggle is registered under the Gameplay category in Options > Controls. Look for "Dynamic Lights toggle" and rebind it to any key you prefer. The default is L.
Why are dynamic lights not working in a specific dimension?
Check the bannedDimensions list in dynamiclights.cfg. Dimensions 77 and 88 are banned by default. If your modded dimension uses one of these IDs, remove it from the list. Also verify that the global toggle hasn't been turned off (press L).
Does Dynamic Lights work with modded items?
Yes, but you need to add them manually. Open the config files (dynamiclights_selflight.cfg for held/worn items, dynamiclights_droppeditems.cfg for ground items) and add the item's registry name to the itemsList. Use F3+H in-game to see an item's registry name in its tooltip.
Is Dynamic Lights client-side only?
No. As of this version, the mod must be installed on both the client and the server. It works by rapidly placing and removing invisible light-emitting blocks as sources move, which requires server-side support.