Flashlight - Dynamic Lighting

Flashlight Plugin
A Minecraft Java Edition plugin that provides dynamic lighting for held items. When players hold light-emitting items in either hand, they will emit light equivalent to their placed block counterpart.

Features

• Dynamic Lighting: Hold torches, lanterns, glowstone, and other light sources to illuminate your surroundings
• Both Hands Support: Works with items in main hand and off-hand
• Configurable Light Levels: Customize which items emit light and their intensity
• Real-time Updates: Light follows you as you move
• Performance Optimized: Efficient light placement and cleanup
• Per-Item Configuration: Set different light levels for different items
• Permission Support: Optional permission-based usage
• Admin Commands: Easy configuration through in-game commands

Installation

1. Download the plugin JAR file
2. Place it in your server's plugins folder
3. Restart your server
4. Configure the plugin using /flashlight commands or edit config.yml

How It Works
The plugin uses invisible light blocks that are placed at the player's location when they hold light-emitting items. These blocks are automatically cleaned up when:

• The player moves to a new location
• The player stops holding the light source
• The player logs out or changes worlds

Commands
Main Command: /flashlight (aliases: /fl, /light)

• /flashlight help - Show all available commands
• /flashlight info - Display plugin information and your current light status
• /flashlight list - List all configured light-emitting items
• /flashlight set <item> <level> - Set light level for an item (0-15)
• /flashlight remove <item> - Remove item from light sources
• /flashlight toggle - Enable/disable the plugin
• /flashlight reload - Reload the plugin configuration
• /flashlight status [player] - Check a player's current light level

Examples
/flashlight set diamond_sword 8 # Make diamond swords emit light level 8
/flashlight set torch 14 # Set torch light level to 14
/flashlight remove redstone # Remove redstone from light sources
/flashlight status Steve # Check Steve's current light level
/flashlight toggle # Disable/enable the plugin

Configuration
The plugin creates a config.yml file with the following structure:

# General settings
enabled: true
update-interval: 5 # Update frequency in ticks
max-light-distance: 50 # Maximum light distance
require-permission: false # Require flashlight.use permission

# Light levels for items (0-15)
light-levels:
torch: 14
lantern: 15
glowstone: 15
# ... many more items
Default Light Sources
The plugin comes pre-configured with realistic light levels for:

• Torches & Lanterns: torch (14), soul_torch (10), lantern (15), soul_lantern (10)
• Glowstone Items: glowstone (15), glowstone_dust (8), glow_ink_sac (6)
• Sea Items: sea_lantern (15), prismarine_crystals (8)
• Redstone Items: redstone_torch (7), redstone (3), redstone_block (5)
• Fire Items: fire_charge (10), lava_bucket (15), magma_cream (6)
• Candles: All candle colors (3)
• Special Items: jack_o_lantern (15), beacon (15), shroomlight (15)
• Ores: diamond (4), emerald (3)
• Nether Items: blaze_rod (12), blaze_powder (8)

Permissions

• flashlight.use - Use flashlight functionality (default: true)
• flashlight.admin - Access to all admin commands (default: op)
• flashlight.info - View plugin information (default: true)
• flashlight.list - View list of light sources (default: true)
• flashlight.status - Check player light status (default: true)

Technical Details

• Light Method: Uses invisible LIGHT blocks for dynamic lighting
• Update Frequency: Configurable (default: every 5 ticks)
• Compatibility: Minecraft 1.20 and 1.21
• Performance: Optimized for minimal server impact
• Cleanup: Automatic cleanup of light blocks when players move or disconnect

Building from Source

1. Clone this repository
2. Ensure you have Java 17+ and Maven installed
3. Run mvn clean package
4. The compiled JAR will be in the target folder

Compatibility

• Minecraft Version: 1.20 and 1.21
• Server Software: Bukkit, Spigot, Paper
• Java Version: 17+

Performance Notes

• Light blocks are only placed when necessary
• Automatic cleanup prevents memory leaks
• Configurable update intervals for performance tuning
• Efficient tracking of player positions and light states

Support
For issues, feature requests, or questions, please create an issue on the GitHub repository.

License
This project is licensed under the MIT License.