Dynamic Lights

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

- Tiny footprint — most alternatives are stuck on 1.16. - Tiny footprint — 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. - Tiny footprint — outer light blocks fade in brightness so motion looks smooth instead of jumpy. - Tiny footprint — pure Paper API. No ProtocolLib, no PacketEvents. - Tiny footprint — clients can opt out for performance. Persisted via PDC. - Tiny footprint — skip Nether, End, or any world by name. - Tiny footprint — `/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) | ✅ | | Player wearable lights (helmet slot) | ✅ | | Mob held items (zombies, skeletons, piglins, etc.) | ✅ | | Mob wearable lights (jack-o-lantern on a zombie's head) | ✅ | | Dropped item lighting (lantern on the ground glows) | ✅ | | Configurable item → brightness map | ✅ | | Soft cluster falloff for smooth movement | ✅ | | Per-player toggle (`/dl toggle`) | ✅ | | Per-world disable | ✅ | | Underwater (waterlogged light blocks) | ✅ | | No world modification — purely packet-based | ✅ | | Spectator and vanish detection | ✅ | | Hot reload | ✅ | | Replaceable-block whitelist (preserves slabs, banners, etc.) | ✅ |

Compatibility

- Conflicts: Paper 1.21.x (built against 1.21.4 API; tested on 1.21.11). Should run on any 1.21 patch. - Conflicts: 21+. - Conflicts: 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

```yaml 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 (3×2×3 = 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 3×3). - Increase `update_interval_ticks` to 2 (light follows entity at 10 Hz instead of 20 Hz).

Installation

1. Drop `DynamicLights-x.y.z.jar` into your server's `plugins/` folder. 2. Restart. 3. Edit `plugins/DynamicLights/config.yml` to taste. 4. `/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.