Class BlockPalette

java.lang.Object

dev.despical.pixelpainter.image.BlockPalette

public final class BlockPalette
extends Object

Resolves configured material colors and performs perceptual nearest-color matching.

Loading runs on the server thread because it resolves Bukkit materials and creates canonical block-data strings. Unknown materials are skipped for cross-version palettes; unsafe blocks, invalid colors and unavailable explicit inclusions reject the candidate palette.

Matching uses cached Oklab coordinates without world access. The entry list is copied. Treat each entry's coordinate array as read-only when sharing a palette with image workers; subsets reuse those entries.

Supported transparent cubes include stable ice and leaves; glass is never used. Leaves use persistent block data to prevent natural decay. Gravity blocks and block entities are rejected before a candidate can reach the painting service.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	BlockPalette.Entry	Associates a material and canonical block data with its representative color.

Field Summary

Fields

Modifier and Type	Field	Description
static final Map<String, Set<String>>	DECAYING	Maps blocks that change themselves after placement to the blocks they can become.

Constructor Summary

Constructors

Constructor	Description
BlockPalette(List<BlockPalette.Entry> entries)	Copies a non-empty list of prepared palette entries.

Method Summary

Modifier and Type	Method	Description
List<BlockPalette.Entry>	entries()	Returns the unmodifiable candidate list.
static BlockPalette	load(Path file, Set<String> included, Set<String> excluded)	Loads and filters material colors using the current server material registry.
BlockPalette.Entry	nearest(int rgb)	Finds the closest representative color by squared Oklab distance.
BlockPalette	subset(String name)	Selects a named material family within the configured global filters.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DECAYING

public static final Map<String, Set<String>> DECAYING

Maps blocks that change themselves after placement to the blocks they can become. Undo accepts a decayed block as the painted one; new paintings never use them.

Constructor Details

BlockPalette

public BlockPalette(List<BlockPalette.Entry> entries)

Copies a non-empty list of prepared palette entries.

Parameters:

entries - matching candidates

Throws:

IllegalArgumentException - if no candidates are available

Method Details

load

public static BlockPalette load(Path file,
 Set<String> included,
 Set<String> excluded)
                         throws Exception

Loads and filters material colors using the current server material registry.

Parameters:

file - palette YAML file

included - exact allowlist; empty means all available entries

excluded - exact material denylist

Returns:

non-empty validated palette

Throws:

Exception - if loading or palette validation fails

subset

public BlockPalette subset(String name)

Selects a named material family within the configured global filters.

Parameters:

name - all, concrete, wool or terracotta, ignoring case

Returns:

this palette for all, or a new family palette

Throws:

IllegalArgumentException - if the family is unknown or empty

nearest

public BlockPalette.Entry nearest(int rgb)

Finds the closest representative color by squared Oklab distance.

Parameters:

rgb - packed sRGB sample

Returns:

closest entry, with palette order breaking equal-distance ties

entries

public List<BlockPalette.Entry> entries()

Returns the unmodifiable candidate list.

Returns:

entries; cached coordinate arrays must be treated as read-only