DynamicLights
Held items emit dynamic light that follows players and mobs in real time. Built for modern Paper 1.21+. No client mod, no ProtocolLib, no world modification.
A torch in your hand lights up the cave around you. A jack-o-lantern on a zombie's head lights up the zombie. Drop a lantern on the floor and it lights up the room. Walk away and the world goes dark again - your save file never changes.
Why this plugin
- Built for Paper 1.21+ - most alternatives are stuck on 1.16.
- Mobs emit light - give a zombie a torch in its hand or a jack-o-lantern on its head and it walks around lit up. Configurable per mob type.
- Soft falloff clusters - outer light blocks fade in brightness so motion looks smooth instead of jumpy.
- Zero dependencies - pure Paper API. No ProtocolLib, no PacketEvents.
- Per-player toggle - clients can opt out for performance. Persisted via PDC.
- Per-world disable - skip Nether, End, or any world by name.
- Reload without restart -
/dl reload reverts all phantom blocks, reloads config, resumes.
- Tiny footprint - ~40 KB jar, no shaded dependencies except bStats.
Features
| Feature |
Status |
| Player held items (main hand, off hand) |
Yes |
| Player wearable lights (helmet slot) |
Yes |
| Mob held items (zombies, skeletons, piglins, etc.) |
Yes |
| Mob wearable lights (jack-o-lantern on a zombie's head) |
Yes |
| Dropped item lighting (lantern on the ground glows) |
Yes |
| Configurable item to brightness map |
Yes |
| Soft cluster falloff for smooth movement |
Yes |
Per-player toggle (/dl toggle) |
Yes |
| Per-world disable |
Yes |
| Underwater (waterlogged light blocks) |
Yes |
| No world modification - purely packet-based |
Yes |
| Spectator and vanish detection |
Yes |
| Hot reload |
Yes |
| Replaceable-block whitelist (preserves slabs, banners, etc.) |
Yes |
Compatibility
- Server: Paper 1.21.x (built against 1.21.4 API; tested on 1.21.11). Should run on any 1.21 patch.
- Java: 21+.
- Folia / Spigot: untested. PRs welcome.
- Conflicts: none known. Does not modify world data, so safe to remove at any time.
Default item brightness
TORCH 14 LANTERN 15 GLOWSTONE 15 JACK_O_LANTERN 15
SOUL_TORCH 10 SOUL_LANTERN 10 REDSTONE_TORCH 7
SEA_LANTERN 15 SHROOMLIGHT 15 END_ROD 14
CAMPFIRE 14 SOUL_CAMPFIRE 10 GLOW_BERRIES 6 BLAZE_ROD 10
Add or override any material via config.yml.
Commands
| Command |
Permission |
Description |
/dynamiclights toggle |
dynamiclights.toggle |
Toggle dynamic lights for yourself. |
/dynamiclights reload |
dynamiclights.reload |
Reload config + resume. |
/dynamiclights status |
- |
Diagnostics: tracked emitters, config summary. |
Aliases: /dl, /dynlights.
Configuration
enabled: true
view_radius: 32
update_interval_ticks: 1
mob_scan_interval_ticks: 4
track_mobs: true
track_items: true # dropped items on the ground emit light
suppress_vanished_emitters: true
suppress_spectator_emitters: true
cluster_radius: 1 # 0 = single column, 1 = 3x3, 2 = 5x5 (capped at 2)
cluster_height: 2 # 1 = head only, 2 = head + body (capped at 3)
cluster_falloff_per_block: 2 # subtract per block of distance from center
disabled_worlds: [] # e.g. [world_nether, world_the_end]
mob_whitelist:
- ZOMBIE
- SKELETON
- PIGLIN
- DROWNED
equipment_slots:
- MAIN_HAND
- OFF_HAND
- HEAD
item_brightness:
TORCH: 14
LANTERN: 15
GLOWSTONE: 15
JACK_O_LANTERN: 15
replaceable_blocks: # only these blocks may be replaced with phantom light
- AIR
- CAVE_AIR
- WATER
- SHORT_GRASS
- TALL_GRASS
How it works
When an entity holds a configured light item, the plugin sends each nearby player a phantom minecraft:light[level=N,waterlogged=B] block-update packet at the entity's eye position (and surrounding cluster). The actual world is never touched - chunk lighting isn't recomputed and no blocks are placed. When the entity moves, the previous block(s) are reverted with a real-block packet and new ones are emitted.
Because the vanilla Minecraft client only knows about block-level lighting, dynamic lights inherently snap to the block grid. The cluster + falloff settings make the visual transitions softer but cannot make the light fully continuous - that requires a client-side mod such as LambDynamicLights or Optifine's Dynamic Lights.
Performance
On a 4-player test server with ~30 mobs holding torches, default cluster size (3x2x3 = 18 blocks per emitter), the per-tick task takes < 1 ms. If your server is CPU-bound:
- Set
track_mobs: false to skip the per-tick mob scan.
- Lower
cluster_radius to 0 (single column instead of 3x3).
- Increase
update_interval_ticks to 2 (light follows entity at 10 Hz instead of 20 Hz).
Installation
- Drop
DynamicLights-x.y.z.jar into your server's plugins/ folder.
- Restart.
- Edit
plugins/DynamicLights/config.yml to taste.
/dl reload.
License
Proprietary - All Rights Reserved. You may install and run unmodified copies of the plugin on your own Minecraft servers. Redistribution, modification, and reverse engineering are not permitted without written permission.
