LightAPI 5.2.0

Tested Minecraft Versions:

• 1.13
• 1.14
• 1.15
• 1.16
• 1.17
• 1.18

Source Code:

https://github.com/BeYkeRYkt/LightAPI

Contributors:

Qveshn

​

Description
Bukkit library for edit light levels

Features
- Edit light levels in minecraft world

Current supported platforms
- CraftBukkit/Spigot (1.14.1 - 1.18)

Current supported light engines
- Vanilla engine (1.14.1 - 1.18)
- Starlight engine (1.17.1 - 1.18)

How to use
Very simple.
If you want to edit light level (with deferred policy):

Code (Text):

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

After calling this function, your request is added to the queue and will be executed after a while with automatic sending to all clients (by default, after 1 tick).

If you want more control, you can use:

Code (Text):

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);

Using the following parameters, you can:
- lightFlags: choose which lighting layer to make changes on, as well as combine them;
- editPolicy: choose a edit policy (apply changes right now, apply immediately taking into account the state of the server, or apply deferred (by default 1 tick)).
- sendPolicy: choose a policy for sending lighting data to clients (send separate packets for each change or combine the same chunks within an interval (by default 2 tick)).
- callback: get execution result codes about completed stages.

If this is not enough for you, then you can use IBukkitExtension to get a Handler class.

Code (Text):

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

With this class, you get "raw" access to library elements.

Commands
- /lightapi - main command

Known issues
- (ALL) Custom lighting levels have no protection from in-game minecraft mechanics. Therefore, the light may disappear if a regular block is placed/broken nearby (within a radius of one block) or will it just happen.
- (STARLIGHT) After unloading chunks, some custom lighting levels disappear from unloaded chunk.
- (STARLIGHT) There may be problems with the IMMEDIATE edit policy set.
- (STARLIGHT) At a random moment in time, the server may crash for unknown reasons.
- GitHub

Configuration
Default configuration:

Code (Text):

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 - enables debug messages.
enable-metrics - enables bStats metrics.
enable-compatibility-mode - enables compatibility mode, where instead of editing lighting data, the plugin places blocks of light. Does not support Skylight editing. Works only with 1.17+.
force-enable-legacy - enables support for legacy plugins (from ru.beykerykt.lightapi namespace).
specific-handler-path - the path for forced loading of the handler.
handlers.* - a list of platforms and their paths to the HandlerFactory.
BukkitBackgroundService:
corePoolSize - The number of threads allocated for internal tasks.
BukkitScheduledChunkObserver:
tick-period - The delay in server ticks before queue processing.
BukkitScheduledLightEngine:
relight-strategy - A strategy for recalculating lighting. The values can be as follows: DEFERRED - recalculation is performed after ALL changes are applied. FORWARD - recalculation is performed after EACH change.
tick-period - The delay in server ticks before queue processing.
max-time-ms-in-per-tick - The maximum time (in milliseconds) allocated for processing requests for each tick.
max-iterations-in-per-tick - The maximum number of processed requests per tick.

Example usage

Code (Java):

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:
    // The request was executed.
    break;
  case ResultCode.MOVED_TO_DEFERRED:
    // The request has been moved to the queue and will be executed after a
    // while.
    break;
  default:
    broadcastMessage("Something is wrong. Result code:" + resultCode);
    break;
}

- BeYkeRYkt's bukkit-example plugin
- ???

Maven
https://jitpack.io/#BeYkeRYkt/LightAPI
subproject: lightapi-bukkit-common

Code (Text):

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

Special thanks
- Qveshn (@bottomdumber) - for continuous support for Legacy version
- and other contributors who create a pull requests and report errors found.

Source code
https://github.com/BeYkeRYkt/LightAPI
License is MIT

Metrics
Plugin uses the bStats metrics.
Privacy policy
bStats license