LightAPI

💡 LightAPI

LightAPI is a next-generation dynamic lighting framework and spatial registry created for modern Minecraft (1.21.11+). Built to bridge the gap following Mojang's extensive GPU and vertex consumer pipeline overhaul (OrderedRenderCommandQueue, ModelCommandRenderer), LightAPI provides a resilient, clean, and thread-safe abstraction for registering, updating, and querying dynamic light sources in the world.

🚀 Key Features

• 🌐 3D Spatial Partitioning:
  • Chunk-based spatial hashing (CellHasher, SpatialIndex) for \(O(1)\) spatial queries near players and cameras.
• 🛡️ Thread-Safe Double Buffering (LightBaker):
  • Staged write-buffers and atomic snapshot swapping (LightSnapshot) ensure asynchronous light queries never cause concurrency locks or frame drops on the render thread.
• 📐 Geometric Shapes & Volumetric Lighting:
  • Supports multiple volumetric emitters: SPHERE, VOLUME_BOX, CAPSULE, EDGE_CURVE, PLANE, ELLIPSE, and CONE.
  • Physics-based attenuation curves: LINEAR, QUADRATIC, and SMOOTH falloff.
• 👥 Multi-Light Grouping (LightGroupManager):
  • Contiguous light fixtures (such as modular neon strips or linked light bars) automatically merge into unified volumetric groups, dramatically reducing GPU overhead.
• 🔄 Decoupled Chromatic Math:
  • Modular Dual-Mode Architecture:
  • Standalone Mode: Zero external color dependencies. Operates as a pure vanilla lighting engine with 0–15 photometric scalar falloff.
  • Chromatic Mode: Dynamically detects ColorAPI via Fabric Loader / SPI (IColorEngineBridge) to unlock full multi-channel RGB/HSV spectral propagation without static bytecode coupling.

💻 Developer Quick Start

Add LightAPI to your build.gradle:

repositories {
    mavenCentral()
    mavenLocal()
}

dependencies {
    modImplementation "mb.bartra:colorapi:1.0"
    modImplementation "mb.bartra:lightapi:1.0"
}

Registering a Dynamic Light Source:

import mb.bartra.lightapi.LightAPI;
import mb.bartra.lightapi.core.LightRegistration;
import mb.bartra.lightapi.core.LightHandle;
import mb.bartra.lightapi.core.CompositeLightShape;
import mb.bartra.lightapi.engine.TickMode;
import net.minecraft.util.math.BlockPos;

// 1. Quick Registration
LightHandle handle = LightAPI.registerLight(pos, 15.0f, 0xFF5500);

// 2. Advanced Volumetric Registration
LightRegistration reg = new LightRegistration(pos, 15.0f, 0x00FF88)
    .compositeShape(CompositeLightShape.VOLUME_BOX)
    .tickMode(TickMode.REAL_TIME);

LightHandle advancedHandle = LightAPI.registerLight(reg);

// 3. Remove when done
LightAPI.removeLight(handle);

🧩 Dependencies

• Fabric API (Required)
• ColorAPI (Optional / Soft Dependency — enables multi-channel RGB chromatic lighting; operates in standalone monochrome mode if absent)

📄 License

MIT License. Free to use in any CurseForge or Modrinth modpack.