Lux

Lux is a Paper plugin that lets players in Survival mode craft, place, adjust, and remove invisible light blocks (Minecraft's light block) in a controlled way.

Features

• Lux item: a real Material.LIGHT item (not a reskin) with its own

display name and lore ("Light level: X"), so it's clearly distinguishable in the inventory from an admin-spawned vanilla light block. Craftable via a configurable shaped or shapeless recipe (recipe.type). Places an invisible block with level 0–15; breaking it (left-click with the item/a tool) returns the item.

• Light level adjustment: right-clicking a placed block opens an

inventory GUI (16 levels), based on the Levelled block data of the LIGHT block. Alternatively: shift + scroll on the held item - the current level is shown live right on the item icon (real BlockData via BlockDataMeta/Levelled, the same vanilla rendering of that number overlay a normal light block item shows), not just in the lore, which isn't displayed anyway while simply holding the item in the hotbar. The extra chat message on scroll can be turned off via scroll.chat-message, and the actionbar message via scroll.actionbar-message.

• Particles: /lux particles shows the executing player all Lux

light blocks within the configured radius via particles (visible only to them). With no argument: toggles with the configured default duration (particles.default-duration-seconds). With an argument: /lux particles <seconds> explicitly (re-)activates for exactly that long, then auto-disables. /lux particles unlimited (equivalent: 0 or -1) activates with no time limit, additionally requires lux.particles.unlimited. Same toggle (default duration) is also reachable in-world: shift + right-click while holding the Lux item with no block in reach.

• Protection integration: optional, soft dependency on WorldGuard and

GriefPrevention - Lux works fine without either plugin installed.

• Rate limiting & performance: bulk operations (chunk restore, purge) run

through a ticked, batch-processed queue instead of blocking the server tick; per-player/per-chunk limits are configurable.

• Persistence: SQLite (default) or MySQL, data is restored per chunk on

load.

• Multi-language: messages/de.yml and messages/en.yml (MiniMessage

format), additional languages can easily be added. If a key is missing from an already-existing file in the data folder after an update, it gets backfilled from the bundled default on startup//lux reload (your own customizations to existing keys are left untouched).

• Self-updating config: the same auto-backfill applies to config.yml -

a new option added by a plugin update appears in your existing file (including its explanatory comment) on next startup//lux reload instead of silently only using the Java-side default forever.

## Example configuration (excerpt from config.yml)

storage:
  type: sqlite
  sqlite:
    file: lux.db

recipe:
  enabled: true
  type: shaped   # shaped | shapeless
  shape:
    - " G "
    - "GLG"
    - " G "
  ingredients:
    G: GLOWSTONE
    L: GLASS
  # Only used when type: shapeless.
  shapeless-ingredients:
    - GLOWSTONE:4
    - GLASS:4

light:
  default-level: 15
  min-level: 0
  max-level: 15

scroll:
  chat-message: true       # false suppresses the scroll chat message (the level stays visible live on the item regardless)
  actionbar-message: true  # false suppresses the actionbar message shown on scroll

limits:
  max-per-player: 200   # -1 (or any negative value) = unlimited, 0 = none allowed
  max-per-chunk: 8       # -1 (or any negative value) = unlimited, 0 = none allowed
  queue-batch-size: 50
  queue-interval-ticks: 1

particles:
  radius: 10
  interval-ticks: 10
  default-duration-seconds: 30
  type: END_ROD   # or DUST, plus dust-color/dust-size

Commands

| Command | Permission | Description | |---|---|---| | /lux particles | lux.particles | Toggle with default duration (particles.default-duration-seconds) | | /lux particles <seconds> | lux.particles | (Re-)activates for the given duration | | /lux particles unlimited | lux.particles.unlimited | Activates with no time limit | | /lux version | – | Shows the plugin version | | /lux reload | lux.admin | Reloads config/language files | | /lux list [player] | lux.admin | Lists placed light blocks | | /lux purge <player\|world> | lux.admin | Removes light blocks | | /lux give <player> <amount> | lux.admin | Gives items |

Permissions

| Node | Default | Description | |---|---|---| | lux.use | true | Place, break, adjust the level | | lux.craft | true | Craft the Lux item | | lux.particles | true | Use /lux particles with the default or a self-chosen duration | | lux.particles.unlimited | op | Use /lux particles unlimited (continuous particle load, hence more restrictive) | | lux.admin | op | reload, list, purge, give |