AW-DynamicLight 💡

Light sources that follow players — without touching your world.

AW-DynamicLight is a lightweight server-side dynamic lighting plugin for Paper. Hold a torch, lantern or another configured light source and the light follows you in-game without placing real blocks in the world.

No client mod required. No ProtocolLib. No world modification.

✨ Features

• 🔦 Dynamic light from held items
• 🤲 Main-hand and off-hand support
• 💡 Configurable light levels
• 🌊 Water-aware fake light blocks
• 🚫 Never places real LIGHT blocks
• 🌍 Does not modify world data or chunk lighting
• ⚡ Designed with server performance in mind
• 🔄 Automatic cleanup on teleport, respawn and world change
• 🌎 Per-world blacklist
• 🛠️ Hot configuration reload
• 📊 Built-in performance statistics

⚡ Performance

AW-DynamicLight is designed to avoid the expensive part of traditional dynamic-light implementations.

The plugin does not create or remove real blocks.

Instead, it sends a temporary fake minecraft:light block directly to the client using Paper's block-change API.

This means:

• no permanent block changes
• no world saves caused by dynamic lights
• no artificial LIGHT blocks left in chunks
• no block physics from the lighting system
• no continuous chunk relighting from placing/removing real blocks

The default update interval is 4 ticks, and the plugin skips packet updates when the player has not changed their light position or brightness.

🔥 Default light sources

Every light source can be changed in config.yml.

🎮 Commands

/dynamiclight stats
/dynamiclight reload
/dynamiclight on
/dynamiclight off

Permission:

dynamiclight.admin

⚙️ Configuration

update-interval-ticks: 4
affect-offhand: true
search-nearby-blocks: true

ignored-worlds: []

items:
  TORCH: 14
  LANTERN: 15
  SOUL_TORCH: 10
  SOUL_LANTERN: 10
  GLOWSTONE: 15

Update interval

Lower values make the light follow movement more closely.

1 tick  = maximum responsiveness
2 ticks = very responsive
4 ticks = recommended
5+ ticks = performance oriented

🧩 Compatibility

Current release

Paper 26.2

Java 25+

Planned / compatible builds

Separate builds may be provided for older modern Paper releases where the same API implementation is available.

The project intentionally avoids NMS and packet libraries where possible, making compatibility maintenance much easier.

🚫 Client mod required?

No.

Players do not need Fabric, Forge, NeoForge, OptiFine or any other client-side dynamic-light mod.

🧠 How it works

AW-DynamicLight uses the vanilla invisible minecraft:light block as a client-side fake block.

The server sends the fake block to the player without actually changing the world.

When the player moves, the previous fake block is restored and a new one is sent at the new position.

The world itself remains untouched.

⚠️ Current limitations

The current release is intentionally focused on performance and simplicity.

The light is currently calculated for the player carrying the source.

A future shared-light mode may allow nearby players to see each other's handheld lights without introducing an expensive global player × player scan.

📌 Why another dynamic-light plugin?

AW-DynamicLight is focused specifically on keeping the server-side implementation small and predictable.

The goal is simple:

Dynamic lighting without turning your server's lighting engine into the bottleneck.