Bukkit Types

Location and ItemStack aren’t plain data, so Jackson can’t (de)serialize them on its own. cw-commons ships Jackson (de)serializers for both in the bukkit.serialization package, bundled as BukkitModule. Both subsystems register it for you, so a Location or ItemStack field “just works” wherever it appears:

• Config — new BukkitConfigManagerBuilder().build() (see Config Loading).
• Data store — new BukkitDataStoreBuilder(...).build() (see Bukkit Integration).

Serialized format

Location

A YAML object. world is the world name (or null if the location has no world); x/y/z are doubles and yaw/pitch are floats. world, x, y, and z are required; yaw and pitch are optional and default to 0. On a config field you can require them with @RequireOrientation.

world: world
x: 128.5
y: 64.0
z: -256.5
yaw: 90.0     # optional, defaults to 0
pitch: 0.0    # optional, defaults to 0

ItemStack

Bukkit’s ConfigurationSerializable map. Simple items are readable and hand-editable — just a type (the Material name) and an amount:

type: STICK
amount: 64

Item metadata (display name, lore, enchantments, …) nests under a meta map carrying Bukkit’s == type marker — the same structure Bukkit writes to YAML. It’s verbose to hand-write, so meta’d items are usually generated by saving an existing item:

type: DIAMOND_SWORD
meta:
  ==: ItemMeta
  display-name: Excalibur

A top-level == is optional, so a hand-written item needs only type (plus optional amount/meta).

In a config

Declare Location and ItemStack fields like any other and load with new BukkitConfigManagerBuilder().build():

import com.crimsonwarpedcraft.cwcommons.config.Config;
import com.crimsonwarpedcraft.cwcommons.config.bukkit.BukkitConfigManagerBuilder;
import org.bukkit.Location;
import org.bukkit.inventory.ItemStack;

public record GuiConfig(Location anchor, ItemStack icon) implements Config {}

GuiConfig config = new BukkitConfigManagerBuilder().build().load(configFile, GuiConfig.class);

anchor:
  world: world
  x: 0.5
  y: 64.0
  z: 0.5
  # yaw and pitch are optional — omitted here, so they default to 0.0
icon:
  type: STICK
  amount: 64

Both fields are hand-editable. If the anchor world isn’t loaded at read time its Location comes back with a null world, so guard for that before using it.

In the data store

The same types work as repository values. The store persists the same field structure shown above, but as a JSON string in its SQLite database — same shape, different on-disk syntax. See Bukkit Integration → Storing Bukkit types.

Bringing your own mapper

new BukkitConfigManagerBuilder().build() and new BukkitDataStoreBuilder(...) register BukkitModule for you. If you build a Jackson ObjectMapper yourself, register it directly:

import com.crimsonwarpedcraft.cwcommons.bukkit.serialization.BukkitModule;
import com.fasterxml.jackson.databind.ObjectMapper;

ObjectMapper mapper = new ObjectMapper().registerModule(new BukkitModule());

Or annotate individual fields with @JsonSerialize/@JsonDeserialize using the per-type (de)serializers in bukkit.serialization — see Per-field instead of store-wide.