Overview

GD656LightCore is a client-side Minecraft mod that adds dynamic lighting to TACZ firearms — providing real-time muzzle flash, bullet trail, bullet impact, and explosion lighting effects with high configurability.

Last updated: July 18, 2026. Some features may not be fully documented or are subject to change.

Compatibility

• TACZ (Timeless and Classics Zero) 1.1.7-hotfix or later is required;
• Soft compatibility with Explosive Enhancement — detects its explosion particles for additional lighting effects;
• Currently supports Minecraft 1.20.1 Forge only.

Server Installation

This mod is split into client-side and server-side functionality. The vast majority of features work with only a client installation.

Features that work without server installation:

Feature	Notes
Own muzzle flash lighting	Listens to client-side GunFireEvent, processed locally
Bullet trail lighting	Iterates over EntityKineticBullet entities in client rendering
Bullet impact lighting	Mixin-injected into client LevelRenderer.addParticle, detects bullet hole particles
Explosion lighting	Mixin-injected into client LevelRenderer.levelEvent / particle events, covers vanilla, TACZ, and Explosive Enhancement explosions
Config & command system	/gd656lightcore client commands, pure client-side configuration

Feature that requires server installation:

Feature	Notes
Other players' muzzle flash lighting	Server broadcasts muzzle position and gun ID via MuzzleFlashSyncPacket to nearby clients

In short: single-player or standalone use is fully unaffected. In multiplayer, only other players' muzzle flash lighting is missing without the server mod — bullet trails, impact lights, and explosion lights all render normally. Server sync data is minimal (only coordinates and gun ID), with negligible server load.

Configuration & Commands

All parameters can be adjusted via the Forge mod config screen, or through in-game client commands:

/gd656lightcore config list              List all config entries with current values
/gd656lightcore config edit <key> <value>  Modify a config entry
/gd656lightcore config reset             Reset all settings to defaults
/gd656lightcore config reset <key>        Reset a specific setting to default

The alias /gdlc works identically. All changes take effect immediately and are saved automatically.

Notes

• All visual effects are client-side rendered and do not affect server stability;
• This mod is in early development (0.x); features may continue to evolve;
• Portions of the code were assisted by AI technology;
• Licensed under the MIT License.

---

Features

Muzzle Flash Lighting

When a player fires, a transient light source is generated at the muzzle position, with brightness randomly chosen between the configured minimum and maximum.

• Per-weapon-type duration scaling: sniper/DMR default 3×, heavy/RPG default 7×;
• Single-shot weapons (semi-auto only) always use maximum brightness (level 15);
• Automatic weapon type detection via gun ID path keywords (e.g., sniper, rpg, heavy);
• Default muzzle flash duration 40ms (adjustable 1–200ms);
• Per-block deduplication prevents stacking from rapid repeated flashes.

Bullet Trail Lighting

Dynamic lights are placed along bullet trajectories during flight, simulating tracer or friction glow effects.

• 7 weapon categories with independent settings: rifle, shotgun, SMG, heavy, MG, pistol, sniper, plus a fallback default — each brightness adjustable 0–15;
• Trail sampling at ~0.4 block intervals, up to 24 samples per bullet, ensuring continuous trail lighting for long-range shots;
• A 2-block exclusion zone around the muzzle avoids overlap with muzzle flash lighting;
• Trail lights default to 80ms duration, decaying naturally.

Bullet Impact Lighting

Bullet hole particles generated on block impact trigger a single flash of light.

• Reads the gun ID from TACZ bullet hole particles to match the appropriate brightness config;
• Single-shot weapons automatically use max brightness 15, sharing the forced-light logic with muzzle flash.

Explosion Lighting

A spherical area of dynamic light is generated around explosion centers, with intensity fading by distance.

• Covers vanilla explosions (TNT, Creepers, etc.), TACZ weapon explosions, and Explosive Enhancement particle effects;
• Explosion radius ~4.5 blocks, intensity fades from level 15 outward, edges below level 2 are trimmed;
• Independent toggle and duration config (default 0.3s, max 60s);
• Frame-split processing: up to 3 pending explosions processed per frame, max 96 queued, preventing lag spikes from mass explosions.

Performance Controls

• Max simultaneous lights: adjustable 64–65536 (default 4096); when exceeded, higher-brightness lights are kept while lower-brightness ones are trimmed;
• Independent toggles for each light type, allowing you to disable unused effects;
• Dimension switch automatically clears light data to prevent cross-dimension lighting artifacts.