LightAPI - 动态光照编辑库

LightAPI 是一个用于编辑 Minecraft 世界光照等级的 Bukkit 库。它提供了简单易用的 API，允许开发者动态修改方块的光照数据，并支持多种光照引擎。

💡功能特性

• 编辑 Minecraft 世界中的光照等级。

💡支持平台与引擎

支持的平台

• CraftBukkit/Spigot (1.14.1 - 1.19)

支持的光照引擎

• Vanilla 引擎 (1.14.1 - 1.19)
• Starlight 引擎 (1.17.1 - 1.19)

🎮使用方法

使用非常简单。如果你想编辑光照等级（使用延迟策略）：

LightAPI.get().setLightLevel(String worldName, int blockX, int blockY, int blockZ, int lightLevel);

调用此函数后，你的请求会被加入队列，并在稍后（默认 1 tick 后）自动执行并发送给所有客户端。

如果需要更多控制，可以使用以下重载方法

LightAPI.get().setLightLevel(String worldName, int blockX, int blockY, int blockZ, int lightLevel, int lightFlags);
LightAPI.get().setLightLevel(String worldName, int blockX, int blockY, int blockZ, int lightLevel, int lightFlags, ICallback callback);
LightAPI.get().setLightLevel(String worldName, int blockX, int blockY, int blockZ, int lightLevel, int lightFlags, EditPolicy editPolicy, SendPolicy sendPolicy, ICallback callback);

通过参数，你可以

• lightFlags：选择在哪个光照层进行更改，并可组合使用。
• editPolicy：选择编辑策略（立即应用、考虑服务器状态立即应用、或延迟应用（默认 1 tick））。
• sendPolicy：选择向客户端发送光照数据的策略（为每个更改发送单独的数据包，或在间隔内合并相同区块（默认 2 tick））。
• callback：获取执行结果代码，了解已完成阶段。

如果这还不够，你可以使用 IBukkitExtension 来获取 Handler 类，以获得对库元素的“原始”访问权限：

IBukkitExtension ext = (IBukkitExtension) LightAPI.get().getExtension();
IHandler rawHandler = ext.getHandler();

🔧命令

• /lightapi - 主命令

❓已知问题

• (所有引擎) 自定义光照等级不受游戏内 Minecraft 机制保护。因此，如果在附近（一格半径内）放置或破坏普通方块，光照可能会消失。
• (Starlight) 区块卸载后，来自已卸载区块的部分自定义光照等级会消失。
• (Starlight) 设置 IMMEDIATE 编辑策略时可能会出现问题。
• (Starlight) 服务器可能因未知原因在随机时刻崩溃。

✨配置

默认配置如下

general:
  debug: false
  enable-metrics: true
  enable-compatibility-mode: false
  force-enable-legacy: false
  specific-handler-path: none
handlers:
  craftbukkit:
    factory-path: ru.beykerykt.minecraft.lightapi.bukkit.internal.handler.craftbukkit.HandlerFactory
BukkitBackgroundService:
  corePoolSize: 1
BukkitScheduledChunkObserver:
  tick-period: 2
BukkitScheduledLightEngine:
  relight-strategy: DEFERRED
  tick-period: 1
  max-time-ms-in-per-tick: 50
  max-iterations-in-per-tick: 256

配置项说明

• general.debug：启用调试信息。
• general.enable-metrics：启用 bStats 统计。
• general.enable-compatibility-mode：启用兼容模式，该模式下插件会放置光源方块而非直接编辑光照数据。不支持天空光编辑，仅适用于 1.17+。
• general.force-enable-legacy：启用对旧版插件（来自 ru.beykerykt.lightapi 命名空间）的支持。
• general.specific-handler-path：用于强制加载处理器的路径。
• handlers.*：平台列表及其对应的 HandlerFactory 路径。
• BukkitBackgroundService.corePoolSize：为内部任务分配的线程数。
• BukkitScheduledChunkObserver.tick-period：队列处理前的服务器 tick 延迟。
• BukkitScheduledLightEngine.relight-strategy：重新计算光照的策略。可选值：DEFERRED（应用所有更改后重新计算）或 FORWARD（每次更改后重新计算）。
• BukkitScheduledLightEngine.tick-period：队列处理前的服务器 tick 延迟。
• BukkitScheduledLightEngine.max-time-ms-in-per-tick：每个 tick 处理请求的最大时间（毫秒）。
• BukkitScheduledLightEngine.max-iterations-in-per-tick：每个 tick 处理请求的最大数量。

⭐使用示例

int blockLight = LightAPI.get().getLightLevel(worldName, blockX, blockY, blockZ, LightFlag.BLOCK_LIGHTING);
broadcastMessage("LightLevel: " + blockLight);

int resultCode = LightAPI.get().setLightLevel(worldName, blockX, blockY, blockZ, lightLevel);
switch (resultCode) {
    case ResultCode.SUCCESS:
        // 请求已执行。
        break;
    case ResultCode.MOVED_TO_DEFERRED:
        // 请求已移至队列，稍后将执行。
        break;
    default:
        broadcastMessage("Something is wrong. Result code:" + resultCode);
        break;
}

• BeYkeRYkt 的 bukkit-example 插件
• ???

✨Maven

项目托管在 JitPack。添加以下依赖（子项目：lightapi-bukkit-common）：

<dependency>
    <groupId>com.github.BeYkeRYkt</groupId>
    <artifactId>lightapi-bukkit-common</artifactId>
    <version>5.1.0</version>
    <scope>provided</scope>
</dependency>

仓库地址：https://jitpack.io/#BeYkeRYkt/LightAPI

🔧特别感谢

• Qveshn (@bottomdumber) - 对 Legacy 版本的持续支持。
• 其他所有提交 Pull Request 和报告错误的贡献者。

🔧源代码与许可

• 源代码：https://github.com/BeYkeRYkt/LightAPI
• 许可证：MIT

🔧统计与隐私

• 本插件使用 bStats 收集匿名统计信息。
• bStats 隐私政策与许可证适用。