Rewrite local configuration api and expand "physics-version"

sakura-api/src/main/java/me/samsuik/sakura/configuration/local/ConfigurableKey.java

@@ -0,0 +1,37 @@
+package me.samsuik.sakura.configuration.local;
+
+import me.samsuik.sakura.explosion.durable.DurableMaterialsContainer.SealedDurableMaterialsContainer;
+import me.samsuik.sakura.mechanics.MinecraftMechanicsTarget;
+import me.samsuik.sakura.redstone.RedstoneConfiguration;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * A key for a configurable value.
+ */
+@NullMarked
+public record ConfigurableKey<T>(Class<T> expectedType) {
+    public static final ConfigurableKey<MinecraftMechanicsTarget> MECHANICS_TARGET = new ConfigurableKey<>(MinecraftMechanicsTarget.class);
+    public static final ConfigurableKey<SealedDurableMaterialsContainer> DURABLE_MATERIALS = new ConfigurableKey<>(SealedDurableMaterialsContainer.class);
+    public static final ConfigurableKey<RedstoneConfiguration> REDSTONE_BEHAVIOUR = new ConfigurableKey<>(RedstoneConfiguration.class);
+    public static final ConfigurableKey<Boolean> CONSISTENT_EXPLOSION_RADIUS = new ConfigurableKey<>(Boolean.class);
+    public static final ConfigurableKey<Integer> LAVA_FLOW_SPEED = new ConfigurableKey<>(Integer.class);
+
+    public T validate(@Nullable final Object value) {
+        final T casted = this.conform(value);
+        if (casted == null) {
+            throw new IllegalArgumentException("Value cannot be null for key " + this);
+        }
+        return casted;
+    }
+
+    public @Nullable T conform(@Nullable final Object value) {
+        if (value == null) {
+            return null;
+        }
+        if (!this.expectedType.isInstance(value)) {
+            throw new IllegalArgumentException("Expected type " + this.expectedType.getName() + " but got " + value.getClass().getName());
+        }
+        return this.expectedType.cast(value);
+    }
+}

sakura-api/src/main/java/me/samsuik/sakura/configuration/local/ConfigurationContainer.java

@@ -0,0 +1,106 @@
+package me.samsuik.sakura.configuration.local;
+
+import com.google.common.base.Preconditions;
+import org.jetbrains.annotations.ApiStatus;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+import java.util.IdentityHashMap;
+import java.util.Map;
+import java.util.Optional;
+
+/**
+ * A container for configuration values.
+ */
+@NullMarked
+public sealed class ConfigurationContainer implements Container<ConfigurableKey<?>, Object> {
+    private final IdentityHashMap<ConfigurableKey<?>, Object> values = new IdentityHashMap<>();
+
+    public static SealedConfigurationContainer sealedContainer(final Object... contents) {
+        if (contents.length % 2 != 0) {
+            throw new IllegalArgumentException("Expected an even number of contents, got " + contents.length);
+        }
+        final IdentityHashMap<ConfigurableKey<?>, Object> values = new IdentityHashMap<>();
+        for (int index = 0; index < contents.length; index += 2) {
+            final Object key = contents[index];
+            final Object value = contents[index + 1];
+            if (!(key instanceof ConfigurableKey<?> configurableKey)) {
+                throw new IllegalArgumentException("Key at index " + index + " must be of type ConfigurableKey");
+            }
+            values.put(configurableKey, configurableKey.validate(value));
+        }
+        return new SealedConfigurationContainer(values);
+    }
+
+    private ConfigurationContainer(final IdentityHashMap<ConfigurableKey<?>, Object> values) {
+        this.values.putAll(values);
+    }
+
+    public ConfigurationContainer() {}
+
+    public <V> @Nullable V set(final ConfigurableKey<V> key, final V value) {
+        Preconditions.checkNotNull(value, "Value cannot be null");
+        return key.conform(this.values.put(key, value));
+    }
+
+    public <V> @Nullable V remove(final ConfigurableKey<V> key) {
+        return key.conform(this.values.remove(key));
+    }
+
+    public final <V> @Nullable V get(final ConfigurableKey<V> key) {
+        return key.conform(this.values.get(key));
+    }
+
+    public final <V> Optional<V> getOptional(final ConfigurableKey<V> key) {
+        return Optional.ofNullable(this.get(key));
+    }
+
+    @ApiStatus.Internal
+    public final void fillAbsentValues(final ConfigurationContainer container) {
+        for (final Map.Entry<ConfigurableKey<?>, Object> entry : container.values.entrySet()) {
+            this.values.putIfAbsent(entry.getKey(), entry.getValue());
+        }
+    }
+
+    public void clear() {
+        this.values.clear();
+    }
+
+    @Override
+    public final Map<ConfigurableKey<?>, Object> contents() {
+        return Map.copyOf(this.values);
+    }
+
+    public final ConfigurationContainer open() {
+        return this instanceof SealedConfigurationContainer
+            ? new ConfigurationContainer(this.values)
+            : this;
+    }
+
+    public final SealedConfigurationContainer seal() {
+        return this instanceof SealedConfigurationContainer sealed
+            ? sealed
+            : new SealedConfigurationContainer(this.values);
+    }
+
+    public static final class SealedConfigurationContainer extends ConfigurationContainer {
+        private SealedConfigurationContainer(final IdentityHashMap<ConfigurableKey<?>, Object> values) {
+            super(values);
+        }
+
+        @Override
+        public <V> V set(final ConfigurableKey<V> key, final V value) {
+            throw new UnsupportedOperationException("Container is sealed");
+        }
+
+        @Override
+        public <V> V remove(final ConfigurableKey<V> key) {
+            throw new UnsupportedOperationException("Container is sealed");
+        }
+
+        @Override
+        public void clear() {
+            throw new UnsupportedOperationException("Container is sealed");
+        }
+    }
+}

sakura-api/src/main/java/me/samsuik/sakura/configuration/local/Container.java

@@ -0,0 +1,14 @@
+package me.samsuik.sakura.configuration.local;
+
+import org.jspecify.annotations.NullMarked;
+
+import java.util.Map;
+
+@NullMarked
+public interface Container<K, V> {
+    Map<K, V> contents();
+
+    Container<K, V> open();
+
+    Container<K, V> seal();
+}

sakura-api/src/main/java/me/samsuik/sakura/configuration/local/LocalConfigurationAccessor.java

@@ -0,0 +1,75 @@
+package me.samsuik.sakura.configuration.local;
+
+import io.papermc.paper.math.Position;
+import me.samsuik.sakura.configuration.local.ConfigurationContainer.SealedConfigurationContainer;
+import org.bukkit.util.BoundingBox;
+import org.bukkit.util.Vector;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+import java.util.List;
+
+/**
+ * An accessor for local configuration containers.
+ */
+@NullMarked
+public interface LocalConfigurationAccessor {
+    default <V> void set(final BoundingBox area, final ConfigurableKey<V> key, final V value) {
+        final ConfigurationContainer container = this.get(area);
+        final ConfigurationContainer newContainer = container != null
+            ? container.open()
+            : new ConfigurationContainer();
+        newContainer.set(key, value);
+        this.set(area, newContainer.seal());
+    }
+
+    default void remove(final BoundingBox area, final ConfigurableKey<?> key) {
+        final ConfigurationContainer container = this.get(area);
+        if (container != null) {
+            final ConfigurationContainer newContainer = container.open();
+            newContainer.remove(key);
+            this.set(area, newContainer.seal());
+        }
+    }
+
+    default <T> @Nullable T get(final BoundingBox area, final ConfigurableKey<T> key) {
+        final ConfigurationContainer container = this.get(area);
+        return container == null ? null : container.get(key);
+    }
+
+    void set(final BoundingBox area, final SealedConfigurationContainer container);
+
+    @Nullable SealedConfigurationContainer remove(final BoundingBox area);
+
+    @Nullable SealedConfigurationContainer get(final BoundingBox area);
+
+    default <T> @Nullable T getValue(final Vector vector, final ConfigurableKey<T> key) {
+        final ConfigurationContainer container = this.getContainer(vector);
+        return container != null ? container.get(key) : null;
+    }
+
+    default <T> @Nullable T getValue(final Position position, final ConfigurableKey<T> key) {
+        final ConfigurationContainer container = this.getContainer(position);
+        return container != null ? container.get(key) : null;
+    }
+
+    default @Nullable ConfigurationContainer getContainer(final Vector vector) {
+        return this.getContainer(vector.getBlockX(), vector.getBlockY(), vector.getBlockZ());
+    }
+
+    default @Nullable ConfigurationContainer getContainer(final Position position) {
+        return this.getContainer(position.blockX(), position.blockY(), position.blockZ());
+    }
+
+    @Nullable ConfigurationContainer getContainer(final int x, final int y, final int z);
+
+    default List<BoundingBox> getAreas(final Vector vector) {
+        return this.getAreas(vector.getBlockX(), vector.getBlockY(), vector.getBlockZ());
+    }
+
+    default List<BoundingBox> getAreas(final Position position) {
+        return this.getAreas(position.blockX(), position.blockY(), position.blockZ());
+    }
+
+    List<BoundingBox> getAreas(final int x, final int y, final int z);
+}

sakura-api/src/main/java/me/samsuik/sakura/explosion/durable/DurableMaterial.java

@@ -0,0 +1,40 @@
+package me.samsuik.sakura.explosion.durable;
+
+import org.jspecify.annotations.NullMarked;
+import org.spongepowered.configurate.objectmapping.ConfigSerializable;
+
+@NullMarked
+@ConfigSerializable
+public record DurableMaterial(int durability, float resistance, boolean onlyDamagedByTnt) {
+    public DurableMaterial(final int durability, final float resistance) {
+        this(durability, resistance, true);
+    }
+
+    public boolean replaceBlastResistance() {
+        return this.resistance >= 0.0f;
+    }
+
+    public boolean applyDurability() {
+        return this.durability >= 0;
+    }
+
+    public static DurableMaterial durability(final int durability) {
+        return new DurableMaterial(durability, 0.0f);
+    }
+
+    public static DurableMaterial resistance(final float resistance) {
+        return new DurableMaterial(1, resistance);
+    }
+
+    public static DurableMaterial likeSand(final int durability) {
+        return new DurableMaterial(durability, 3.0f);
+    }
+
+    public static DurableMaterial likeCobblestone(final int durability) {
+        return new DurableMaterial(durability, 6.0f);
+    }
+
+    public static DurableMaterial likeEndstone(final int durability) {
+        return new DurableMaterial(durability, 9.0f);
+    }
+}

sakura-api/src/main/java/me/samsuik/sakura/explosion/durable/DurableMaterialsContainer.java

@@ -0,0 +1,123 @@
+package me.samsuik.sakura.explosion.durable;
+
+import com.google.common.base.Preconditions;
+import me.samsuik.sakura.configuration.local.Container;
+import org.bukkit.Material;
+import org.bukkit.block.BlockType;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+import java.util.IdentityHashMap;
+import java.util.Map;
+
+/**
+ * A container for durable materials.
+ */
+@NullMarked
+public sealed class DurableMaterialsContainer implements Container<BlockType, DurableMaterial> {
+    private final Map<BlockType, DurableMaterial> materials = new IdentityHashMap<>();
+
+    public static SealedDurableMaterialsContainer sealedContainer(final Object... contents) {
+        if (contents.length % 2 != 0) {
+            throw new IllegalArgumentException("Expected an even number of contents, got " + contents.length);
+        }
+        final Map<BlockType, DurableMaterial> materials = new IdentityHashMap<>();
+        for (int index = 0; index < contents.length; index += 2) {
+            Object key = contents[index];
+            Object value = contents[index + 1];
+            if (key instanceof Material bukkitMaterial) {
+                key = blockTypeFromBukkitMaterial(bukkitMaterial);
+            }
+            if (!(key instanceof BlockType blockType)) {
+                throw new IllegalArgumentException("Key at index " + index + " must be of type BlockType or Material");
+            }
+            if (!(value instanceof DurableMaterial material)) {
+                throw new IllegalArgumentException("Value at index " + (index + 1) + " must be of type DurableMaterial");
+            }
+            materials.put(blockType, material);
+        }
+        return new SealedDurableMaterialsContainer(materials);
+    }
+
+    private DurableMaterialsContainer(final Map<BlockType, DurableMaterial> materials) {
+        this.materials.putAll(materials);
+    }
+
+    public DurableMaterialsContainer() {}
+
+    private static BlockType blockTypeFromBukkitMaterial(final Material bukkitMaterial) {
+        final BlockType blockType = bukkitMaterial.asBlockType();
+        Preconditions.checkNotNull(blockType, "Material " + bukkitMaterial + " is not a block");
+        return blockType;
+    }
+
+    @Deprecated
+    public final @Nullable DurableMaterial set(final Material bukkitMaterial, final DurableMaterial material) {
+        return this.set(blockTypeFromBukkitMaterial(bukkitMaterial), material);
+    }
+
+    @Deprecated
+    public final @Nullable DurableMaterial remove(final Material bukkitMaterial) {
+        return this.remove(blockTypeFromBukkitMaterial(bukkitMaterial));
+    }
+
+    @Deprecated
+    public final @Nullable DurableMaterial get(final Material bukkitMaterial) {
+        return this.get(blockTypeFromBukkitMaterial(bukkitMaterial));
+    }
+
+    public @Nullable DurableMaterial set(final BlockType blockType, final DurableMaterial material) {
+        Preconditions.checkNotNull(material, "Material cannot be null");
+        return this.materials.put(blockType, material);
+    }
+
+    public @Nullable DurableMaterial remove(final BlockType blockType) {
+        return this.materials.remove(blockType);
+    }
+
+    public final @Nullable DurableMaterial get(final BlockType blockType) {
+        return this.materials.get(blockType);
+    }
+
+    public void clear() {
+        this.materials.clear();
+    }
+
+    @Override
+    public final Map<BlockType, DurableMaterial> contents() {
+        return Map.copyOf(this.materials);
+    }
+
+    public final DurableMaterialsContainer open() {
+        return this instanceof SealedDurableMaterialsContainer
+            ? new DurableMaterialsContainer(this.materials)
+            : this;
+    }
+
+    public final SealedDurableMaterialsContainer seal() {
+        return this instanceof SealedDurableMaterialsContainer sealed
+            ? sealed
+            : new SealedDurableMaterialsContainer(this.materials);
+    }
+
+    public static final class SealedDurableMaterialsContainer extends DurableMaterialsContainer {
+        private SealedDurableMaterialsContainer(final Map<BlockType, DurableMaterial> materials) {
+            super(materials);
+        }
+
+        @Override
+        public DurableMaterial set(final BlockType key, final DurableMaterial value) {
+            throw new UnsupportedOperationException("Container is sealed");
+        }
+
+        @Override
+        public DurableMaterial remove(final BlockType key) {
+            throw new UnsupportedOperationException("Container is sealed");
+        }
+
+        @Override
+        public void clear() {
+            throw new UnsupportedOperationException("Container is sealed");
+        }
+    }
+}

sakura-api/src/main/java/me/samsuik/sakura/local/LocalRegion.java

@@ -1,47 +0,0 @@
-package me.samsuik.sakura.local;
-
-import io.papermc.paper.math.Position;
-import org.bukkit.util.BoundingBox;
-import org.bukkit.util.Vector;
-import org.jspecify.annotations.NullMarked;
-
-@NullMarked
-@Deprecated(forRemoval = true)
-public record LocalRegion(int minX, int minZ, int maxX, int maxZ) {
-    public static LocalRegion from(BoundingBox boundingBox) {
-        return of(boundingBox.getMin(), boundingBox.getMax());
-    }
-
-    public static LocalRegion of(Vector min, Vector max) {
-        return of(min.getBlockX(), min.getBlockZ(), max.getBlockX(), max.getBlockZ());
-    }
-
-    public static LocalRegion of(Position min, Position max) {
-        return of(min.blockX(), min.blockZ(), max.blockX(), max.blockZ());
-    }
-
-    public static LocalRegion of(int minX, int minZ, int maxX, int maxZ) {
-        return new LocalRegion(
-            Math.min(minX, maxX), Math.min(minZ, maxZ),
-            Math.max(minX, maxX), Math.max(minZ, maxZ)
-        );
-    }
-
-    public static LocalRegion at(int x, int z, int radius) {
-        return new LocalRegion(x-radius, z-radius, x+radius, z+radius);
-    }
-
-    public boolean intersects(LocalRegion region) {
-        return (this.minX <= region.minX() && this.maxX >= region.minX() || this.maxX >= region.maxX() && this.minX < region.maxX())
-            && (this.minZ <= region.minZ() && this.maxZ >= region.minZ() || this.maxZ >= region.maxZ() && this.minZ < region.maxZ());
-    }
-
-    public boolean contains(LocalRegion region) {
-        return this.minX < region.minX() && this.maxX > region.maxX()
-            && this.maxZ < region.minZ() && this.maxZ > region.maxZ();
-    }
-
-    public boolean contains(int x, int z) {
-        return this.minX <= x && this.maxX >= x && this.minZ <= z && this.maxZ >= z;
-    }
-}

sakura-api/src/main/java/me/samsuik/sakura/local/LocalValueKey.java

@@ -1,24 +0,0 @@
-package me.samsuik.sakura.local;
-
-import org.bukkit.NamespacedKey;
-import org.jspecify.annotations.NullMarked;
-
-import java.util.function.Supplier;
-
-@NullMarked
-@Deprecated(forRemoval = true)
-public record LocalValueKey<T>(NamespacedKey key, Supplier<T> defaultSupplier) {
-    @Override
-    public boolean equals(Object o) {
-        if (this == o) return true;
-        if (o == null || this.getClass() != o.getClass()) return false;
-
-        LocalValueKey<?> that = (LocalValueKey<?>) o;
-        return this.key.equals(that.key);
-    }
-
-    @Override
-    public int hashCode() {
-        return this.key.hashCode();
-    }
-}

sakura-api/src/main/java/me/samsuik/sakura/local/LocalValueKeys.java

@@ -1,26 +0,0 @@
-package me.samsuik.sakura.local;
-
-import me.samsuik.sakura.physics.PhysicsVersion;
-import me.samsuik.sakura.redstone.RedstoneImplementation;
-import org.bukkit.Material;
-import org.bukkit.NamespacedKey;
-
-import java.util.HashMap;
-import java.util.Map;
-import java.util.function.Supplier;
-
-@Deprecated(forRemoval = true)
-public final class LocalValueKeys {
-    private static final String NAMESPACE = "sakura";
-
-    public static final LocalValueKey<PhysicsVersion> PHYSICS_VERSION = create("physics-version", () -> PhysicsVersion.LATEST);
-    public static final LocalValueKey<Map<Material, Map.Entry<Integer, Float>>> DURABLE_MATERIALS = create("durable-materials", HashMap::new);
-    public static final LocalValueKey<RedstoneImplementation> REDSTONE_IMPLEMENTATION = create("redstone-implementation", () -> RedstoneImplementation.VANILLA);
-    public static final LocalValueKey<Boolean> CONSISTENT_EXPLOSION_RADIUS = create("consistent-radius", () -> false);
-    public static final LocalValueKey<Boolean> REDSTONE_CACHE = create("redstone-cache", () -> false);
-    public static final LocalValueKey<Integer> LAVA_FLOW_SPEED = create("lava-flow-speed", () -> -1);
-
-    private static <T> LocalValueKey<T> create(String key, Supplier<T> supplier) {
-        return new LocalValueKey<>(new NamespacedKey(NAMESPACE, key), supplier);
-    }
-}

sakura-api/src/main/java/me/samsuik/sakura/local/storage/LocalStorageHandler.java

@@ -1,28 +0,0 @@
-package me.samsuik.sakura.local.storage;
-
-import me.samsuik.sakura.local.LocalRegion;
-import org.bukkit.Location;
-import org.jspecify.annotations.NonNull;
-import org.jspecify.annotations.Nullable;
-
-import java.util.List;
-import java.util.Optional;
-
-@Deprecated(forRemoval = true)
-public interface LocalStorageHandler {
-    default @NonNull Optional<LocalRegion> locate(@NonNull Location location) {
-        return this.locate(location.blockX(), location.blockZ());
-    }
-
-    @NonNull Optional<LocalRegion> locate(int x, int z);
-
-    @Nullable LocalValueStorage get(@NonNull LocalRegion region);
-
-    boolean has(@NonNull LocalRegion region);
-
-    void put(@NonNull LocalRegion region, @NonNull LocalValueStorage storage);
-
-    void remove(@NonNull LocalRegion region);
-
-    @NonNull List<LocalRegion> regions();
-}

sakura-api/src/main/java/me/samsuik/sakura/local/storage/LocalValueStorage.java

@@ -1,51 +0,0 @@
-package me.samsuik.sakura.local.storage;
-
-import it.unimi.dsi.fastutil.objects.Object2ObjectOpenHashMap;
-import me.samsuik.sakura.local.LocalValueKey;
-import org.jspecify.annotations.NullMarked;
-import org.jspecify.annotations.Nullable;
-
-import java.util.Map;
-import java.util.Optional;
-
-@NullMarked
-@Deprecated(forRemoval = true)
-@SuppressWarnings("unchecked")
-public final class LocalValueStorage {
-    private final Map<LocalValueKey<?>, Object> map = new Object2ObjectOpenHashMap<>();
-
-    public <T> void set(LocalValueKey<T> key, T insert) {
-        this.map.put(key, insert);
-    }
-
-    public void remove(LocalValueKey<?> key) {
-        this.map.remove(key);
-    }
-
-    public <T> Optional<T> get(LocalValueKey<T> key) {
-        T value = (T) this.map.get(key);
-        return Optional.ofNullable(value);
-    }
-
-    public <T> T getOrDefault(LocalValueKey<T> key, T def) {
-        return (T) this.map.getOrDefault(key, def);
-    }
-
-    public boolean exists(LocalValueKey<?> key) {
-        return this.map.containsKey(key);
-    }
-
-    @Nullable
-    public <T> T value(LocalValueKey<T> key) {
-        return (T) this.map.get(key);
-    }
-
-    public <T> T value(LocalValueKey<T> key, boolean returnDefault) {
-        T val = (T) this.map.get(key);
-        if (!returnDefault || val != null)
-            return val;
-        // update value
-        this.set(key, val = key.defaultSupplier().get());
-        return val;
-    }
-}

sakura-api/src/main/java/me/samsuik/sakura/mechanics/MechanicVersion.java

@@ -0,0 +1,39 @@
+package me.samsuik.sakura.mechanics;
+
+/**
+ * All post-1.8 Minecraft versions with changes to cannon mechanics.
+ * <p>
+ * Versions are encoded as shorts see {@link MinecraftVersionEncoding}.
+ */
+public final class MechanicVersion {
+    public static final short LATEST = Short.MAX_VALUE;
+    public static final short LEGACY = Short.MIN_VALUE;
+    public static final short v1_8_2 = MinecraftVersionEncoding.v1xy(8, 2);
+    public static final short v1_9 = MinecraftVersionEncoding.v1xy(9, 0);
+    public static final short v1_10 = MinecraftVersionEncoding.v1xy(10, 0);
+    public static final short v1_11 = MinecraftVersionEncoding.v1xy(11, 0);
+    public static final short v1_12 = MinecraftVersionEncoding.v1xy(12, 0);
+    public static final short v1_13 = MinecraftVersionEncoding.v1xy(13, 0);
+    public static final short v1_14 = MinecraftVersionEncoding.v1xy(14, 0);
+    public static final short v1_16 = MinecraftVersionEncoding.v1xy(16, 0);
+    public static final short v1_17 = MinecraftVersionEncoding.v1xy(17, 0);
+    public static final short v1_18_2 = MinecraftVersionEncoding.v1xy(18, 2);
+    public static final short v1_19_3 = MinecraftVersionEncoding.v1xy(19, 3);
+    public static final short v1_20 = MinecraftVersionEncoding.v1xy(20, 0);
+    public static final short v1_21_2 = MinecraftVersionEncoding.v1xy(21, 2);
+    public static final short v1_21_5 = MinecraftVersionEncoding.v1xy(21, 5);
+    public static final short v1_21_6 = MinecraftVersionEncoding.v1xy(21, 6);
+
+    public static String name(final short version) {
+        if (version == LATEST) {
+            return "latest";
+        } else if (version == LEGACY) {
+            return "legacy";
+        }
+
+        final int significant = MinecraftVersionEncoding.significant(version);
+        final int major = MinecraftVersionEncoding.major(version);
+        final int minor = MinecraftVersionEncoding.minor(version);
+        return String.format("%d.%d.%d", significant, major, minor);
+    }
+}

sakura-api/src/main/java/me/samsuik/sakura/mechanics/MinecraftMechanicsTarget.java

@@ -0,0 +1,112 @@
+package me.samsuik.sakura.mechanics;
+
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+import java.util.Locale;
+
+/**
+ * The targeted Minecraft version and server type for cannon mechanics.
+ */
+@NullMarked
+public record MinecraftMechanicsTarget(short mechanicVersion, byte serverType) {
+    private static final MinecraftMechanicsTarget LATEST = new MinecraftMechanicsTarget(MechanicVersion.LATEST, ServerType.PAPER);
+    private static final MinecraftMechanicsTarget LEGACY = new MinecraftMechanicsTarget(MechanicVersion.v1_8_2, ServerType.PAPER);
+
+    public boolean isServerType(final byte type) {
+        return this.serverType == type;
+    }
+
+    public boolean is(final short version) {
+        return this.mechanicVersion == version;
+    }
+
+    public boolean before(final short version) {
+        return this.mechanicVersion < version;
+    }
+
+    public boolean after(final short version) {
+        return this.mechanicVersion > version;
+    }
+
+    public boolean atLeast(final short version) {
+        return this.mechanicVersion >= version;
+    }
+
+    public boolean atMost(final short version) {
+        return this.mechanicVersion <= version;
+    }
+
+    public boolean between(final short minVersion, final short maxVersion) {
+        return this.mechanicVersion >= minVersion && this.mechanicVersion < maxVersion;
+    }
+
+    public boolean betweenInclusive(final short minVersion, final short maxVersion) {
+        return this.mechanicVersion >= minVersion && this.mechanicVersion <= maxVersion;
+    }
+
+    public boolean isLegacy() {
+        return this.mechanicVersion == MechanicVersion.LEGACY;
+    }
+
+    public static MinecraftMechanicsTarget latest() {
+        return LATEST;
+    }
+
+    public static MinecraftMechanicsTarget legacy() {
+        return LEGACY;
+    }
+
+    public static MinecraftMechanicsTarget vanilla(final short mechanicVersion) {
+        return new MinecraftMechanicsTarget(mechanicVersion, ServerType.VANILLA);
+    }
+
+    public static MinecraftMechanicsTarget spigot(final short mechanicVersion) {
+        return new MinecraftMechanicsTarget(mechanicVersion, ServerType.SPIGOT);
+    }
+
+    public static MinecraftMechanicsTarget paper(final short mechanicVersion) {
+        return new MinecraftMechanicsTarget(mechanicVersion, ServerType.PAPER);
+    }
+
+    public static @Nullable MinecraftMechanicsTarget fromString(final String target) throws NumberFormatException {
+        // 1.21.8+paper 1.8.8+vanilla 12.2
+        final String[] parts = target.split("\\+");
+        final String serverPart = parts.length == 2 ? parts[1] : "";
+        final byte serverType = switch (serverPart.toLowerCase(Locale.ENGLISH)) {
+            case "vanilla" -> ServerType.VANILLA;
+            case "spigot"  -> ServerType.SPIGOT;
+            default        -> ServerType.PAPER;
+        };
+
+        if (parts.length == 0) {
+            return null;
+        }
+
+        final String[] version = parts[0].split("\\.");
+        if (version.length < 1) {
+            return null;
+        }
+
+        final short mechanicVersion;
+        if (version.length == 1) {
+            mechanicVersion = switch (version[0]) {
+                case "latest" -> MechanicVersion.LATEST;
+                case "legacy" -> MechanicVersion.LEGACY;
+                default -> 0;
+            };
+        } else {
+            // 21.1 -> 1.21.1
+            final int first  = Integer.parseInt(version[0]);
+            final int second = Integer.parseInt(version[1]);
+            if (version.length == 3) {
+                final int third = Integer.parseInt(version[2]);
+                mechanicVersion = MinecraftVersionEncoding.encode(first, second, third);
+            } else {
+                mechanicVersion = MinecraftVersionEncoding.v1xy(first, second);
+            }
+        }
+
+        return new MinecraftMechanicsTarget(mechanicVersion, serverType);
+    }
+}

sakura-api/src/main/java/me/samsuik/sakura/mechanics/MinecraftVersionEncoding.java

@@ -0,0 +1,67 @@
+package me.samsuik.sakura.mechanics;
+
+/**
+ * Encode Minecraft versions into a short.
+ */
+public final class MinecraftVersionEncoding {
+    private static final int SIGNIFICANT_SHIFT = Short.SIZE - 4;
+    private static final int MAJOR_SHIFT = SIGNIFICANT_SHIFT - 6;
+    private static final int MINOR_SHIFT = MAJOR_SHIFT - 6;
+
+    /**
+     * Encodes a 1.x.y Minecraft version into a short.
+     *
+     * @param major the major version (x)
+     * @param minor the minor version (y)
+     * @return the encoded version as a short
+     */
+    public static short v1xy(final int major, final int minor) {
+        return encode(1, major, minor);
+    }
+
+    /**
+     * Encodes a Minecraft version into a short.
+     *
+     * @param significant the significant version
+     * @param major       the major version
+     * @param minor       the minor version
+     * @return the encoded version as a short
+     */
+    public static short encode(final int significant, final int major, final int minor) {
+        short encoded = 0;
+        encoded |= (short) (significant << SIGNIFICANT_SHIFT);
+        encoded |= (short) (major << MAJOR_SHIFT);
+        encoded |= (short) (minor << MINOR_SHIFT);
+        return encoded;
+    }
+
+    /**
+     * Decodes the significant version from an encoded version.
+     *
+     * @param version the encoded version
+     * @return the significant version
+     */
+    public static int significant(final short version) {
+        return (version >>> SIGNIFICANT_SHIFT) & 15;
+    }
+
+    /**
+     * Decodes the major version from an encoded version.
+     *
+     * @param version the encoded version
+     * @return the major version
+     */
+    public static int major(final short version) {
+        return (version >>> MAJOR_SHIFT) & 63;
+    }
+
+    /**
+     * Decodes the minor version from an encoded version.
+     *
+     * @param version the encoded version
+     * @return the minor version
+     */
+    public static int minor(final short version) {
+        return (version >>> MINOR_SHIFT) & 63;
+    }
+}

sakura-api/src/main/java/me/samsuik/sakura/mechanics/ServerType.java

@@ -0,0 +1,22 @@
+package me.samsuik.sakura.mechanics;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Types of server software that have different cannon mechanics.
+ */
+@NullMarked
+public final class ServerType {
+    public static final byte VANILLA = 0;
+    public static final byte SPIGOT = 1;
+    public static final byte PAPER = 2;
+
+    public static String name(final byte serverType) {
+        return switch (serverType) {
+            case 0 -> "vanilla";
+            case 1 -> "spigot";
+            case 2 -> "paper";
+            default -> "unknown";
+        };
+    }
+}

sakura-api/src/main/java/me/samsuik/sakura/physics/PhysicsVersion.java

@@ -1,76 +0,0 @@
-package me.samsuik.sakura.physics;
-
-import org.jspecify.annotations.NullMarked;
-
-@NullMarked
-public enum PhysicsVersion {
-    LEGACY("legacy", 1_0_0),  // replicates patched 1.8.8 paper mechanics
-    v1_8_2("1.8.2", 1_8_2),   // vanilla mechanics
-    v1_9("1.9", 1_9_0),
-    v1_10("1.10", 1_10_0),
-    v1_11("1.11", 1_11_0),
-    v1_12("1.12", 1_12_0),
-    v1_13("1.13", 1_13_0),
-    v1_14("1.14", 1_14_0),
-    v1_16("1.16", 1_16_0),
-    v1_17("1.17", 1_17_0),
-    v1_18_2("1.18.2", 1_18_2),
-    v1_19_3("1.19.3", 1_19_3),
-    v1_20("1.20", 1_20_0),
-    v1_21_2("1.21.2", 1_21_2),
-    v1_21_5("1.21.5", 1_21_5),
-    v1_21_6("1.21.6", 1_21_6),
-    LATEST("latest", 9_99_9); // latest version
-
-    private final String friendlyName;
-    private final int version;
-
-    PhysicsVersion(String friendlyName, int version) {
-        this.friendlyName = friendlyName;
-        this.version = version;
-    }
-
-    public boolean isLegacy() {
-        return this == LEGACY;
-    }
-
-    public boolean afterOrEqual(int version) {
-        return this.version >= version;
-    }
-
-    public boolean before(int version) {
-        return this.version < version;
-    }
-
-    public boolean is(int version) {
-        return this.version == version;
-    }
-
-    public boolean isWithin(int min, int max) {
-        return this.version >= min && this.version <= max;
-    }
-
-    public int getVersion() {
-        return this.version;
-    }
-
-    public String getFriendlyName() {
-        return this.friendlyName;
-    }
-
-    public static PhysicsVersion from(String string) {
-        int parsedVersion = Integer.MIN_VALUE;
-        try {
-            String versionString = string.replace(".", "");
-            parsedVersion = Integer.parseInt(versionString);
-        } catch (NumberFormatException nfe) {
-            // ignored
-        }
-        for (PhysicsVersion ver : values()) {
-            if (ver.name().equalsIgnoreCase(string) || ver.getFriendlyName().equalsIgnoreCase(string) || ver.is(parsedVersion)) {
-                return ver;
-            }
-        }
-        return LATEST;
-    }
-}

sakura-api/src/main/java/me/samsuik/sakura/redstone/RedstoneConfiguration.java

@@ -0,0 +1,16 @@
+package me.samsuik.sakura.redstone;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Configuration for redstone behavior
+ *
+ * @param implementation the redstone implementation to use
+ * @param cache          whether to cache redstone calculations
+ */
+@NullMarked
+public record RedstoneConfiguration(RedstoneImplementation implementation, boolean cache) {
+    public static RedstoneConfiguration withImplementation(final RedstoneImplementation implementation) {
+        return new RedstoneConfiguration(implementation, false);
+    }
+}

sakura-api/src/main/java/me/samsuik/sakura/redstone/RedstoneImplementation.java

@@ -2,6 +2,9 @@ package me.samsuik.sakura.redstone;
 
 import org.jspecify.annotations.NullMarked;
 
+/**
+ * The redstone implementation to use.
+ */
 @NullMarked
 public enum RedstoneImplementation {
     VANILLA("vanilla"),
@@ -10,11 +13,11 @@ public enum RedstoneImplementation {
 
     private final String friendlyName;
 
-    RedstoneImplementation(String friendlyName) {
+    RedstoneImplementation(final String friendlyName) {
         this.friendlyName = friendlyName;
     }
 
-    public String getFriendlyName() {
+    public final String getFriendlyName() {
         return this.friendlyName;
     }
 }