LightAPI

LightAPI

Minecraft Fabric 1.21.11+ 高性能动态光照引擎与空间索引 API。具备体积形状、双缓冲烘焙管线与多光源分组功能。

💡 LightAPI

Fabric Minecraft Java ![Dependency](https://img.shields.io/badge/ColorAPI-Soft Dependency / Optional-blueviolet?style=for-the-badge)

LightAPI 是为现代 Minecraft(1.21.11+)打造的新一代动态光照框架与空间注册系统。为弥合 Mojang 大规模 GPU 与顶点消费者管线重构(OrderedRenderCommandQueue、ModelCommandRenderer)所留下的空白,LightAPI 提供了健壮、简洁且线程安全地注册、更新与查询世界中动态光源的抽象层。


🚀 核心特性

  • 🌐 3D 空间分区:
    • 基于区块的空间哈希(CellHasher、SpatialIndex),实现玩家与摄像机附近 (O(1)) 的空间查询。
  • 🛡️ 线程安全双缓冲(LightBaker):
    • 分阶段写入缓冲与原子快照交换(LightSnapshot)确保异步光照查询不会在渲染线程上引发并发锁或掉帧。
  • 📐 几何形状与体积光照:
    • 支持多种体积发射器:SPHERE、VOLUME_BOX、CAPSULE、EDGE_CURVE、PLANE、ELLIPSE 与 CONE。
    • 基于物理的衰减曲线:LINEAR、QUADRATIC 与 SMOOTH 衰减。
  • 👥 多光源分组(LightGroupManager):
    • 相邻的光源装置(例如模块化霓虹灯带或相连的灯条)会自动合并为统一的体积组,大幅降低 GPU 开销。
  • 🔄 解耦的色彩数学:
    • 模块化双模式架构:
    • 独立模式: 零外部颜色依赖。作为纯原版光照引擎运行,支持 0–15 光度标量衰减。
    • 色彩模式: 通过 Fabric Loader / SPI(IColorEngineBridge)动态检测 ColorAPI,在无需静态字节码耦合的情况下解锁完整的多通道 RGB/HSV 光谱传播。

💻 开发者快速入门

将 LightAPI 添加到你的 build.gradle:

repositories {
    mavenCentral()
    mavenLocal()
}

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

注册动态光源:

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. 快速注册
LightHandle handle = LightAPI.registerLight(pos, 15.0f, 0xFF5500);

// 2. 高级体积注册
LightRegistration reg = new LightRegistration(pos, 15.0f, 0x00FF88)
    .compositeShape(CompositeLightShape.VOLUME_BOX)
    .tickMode(TickMode.REAL_TIME);

LightHandle advancedHandle = LightAPI.registerLight(reg);

// 3. 使用完毕后移除
LightAPI.removeLight(handle);

🧩 依赖

  • Fabric API(必需)
  • ColorAPI(可选 / 软依赖 — 启用多通道 RGB 彩色光照;若缺失则以独立单色模式运行)

📄 许可证

MIT 许可证。可在任意 CurseForge 或 Modrinth 整合包中自由使用。