Custom item support for extensions (#2822)

Co-authored-by: Camotoy <20743703+Camotoy@users.noreply.github.com>

api/geyser/src/main/java/org/geysermc/geyser/api/GeyserApi.java

@@ -116,7 +116,7 @@ public interface GeyserApi extends GeyserApiBase {
     EventBus eventBus();
 
     /**
-     * Get's the default {@link RemoteServer} configured
+     * Gets the default {@link RemoteServer} configured
      * within the config file that is used by default.
      *
      * @return the default remote server used within Geyser

api/geyser/src/main/java/org/geysermc/geyser/api/event/EventBus.java

@@ -76,7 +76,7 @@ public interface EventBus {
      void unregisterAll(@NonNull Extension extension);
 
     /**
-     * Fires the given {@link Event}.
+     * Fires the given {@link Event} and returns the result.
      *
      * @param event the event to fire
      *

api/geyser/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineCustomItemsEvent.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) 2019-2022 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.event.lifecycle;
+
+import com.google.common.collect.Multimap;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.geyser.api.event.Event;
+import org.geysermc.geyser.api.item.custom.CustomItemData;
+import org.geysermc.geyser.api.item.custom.NonVanillaCustomItemData;
+
+import java.util.*;
+
+/**
+ * Called on Geyser's startup when looking for custom items. Custom items must be registered through this event.
+ *
+ * This event will not be called if the "add non-Bedrock items" setting is disabled in the Geyser config.
+ */
+public abstract class GeyserDefineCustomItemsEvent implements Event {
+    private final Multimap<String, CustomItemData> customItems;
+    private final List<NonVanillaCustomItemData> nonVanillaCustomItems;
+
+    public GeyserDefineCustomItemsEvent(Multimap<String, CustomItemData> customItems, List<NonVanillaCustomItemData> nonVanillaCustomItems) {
+        this.customItems = customItems;
+        this.nonVanillaCustomItems = nonVanillaCustomItems;
+    }
+
+    /**
+     * Gets a multimap of all the already registered custom items indexed by the item's extended java item's identifier.
+     *
+     * @return a multimap of all the already registered custom items
+     */
+    public Map<String, Collection<CustomItemData>> getExistingCustomItems() {
+        return Collections.unmodifiableMap(this.customItems.asMap());
+    }
+
+    /**
+     * Gets the list of the already registered non-vanilla custom items.
+     *
+     * @return the list of the already registered non-vanilla custom items
+     */
+    public List<NonVanillaCustomItemData> getExistingNonVanillaCustomItems() {
+        return Collections.unmodifiableList(this.nonVanillaCustomItems);
+    }
+
+    /**
+     * Registers a custom item with a base Java item. This is used to register items with custom textures and properties
+     * based on NBT data.
+     *
+     * @param identifier the base (java) item
+     * @param customItemData the custom item data to register
+     * @return if the item was registered
+     */
+    public abstract boolean register(@NonNull String identifier, @NonNull CustomItemData customItemData);
+
+    /**
+     * Registers a custom item with no base item. This is used for mods.
+     *
+     * @param customItemData the custom item data to register
+     * @return if the item was registered
+     */
+    public abstract boolean register(@NonNull NonVanillaCustomItemData customItemData);
+}

api/geyser/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserLoadResourcePacksEvent.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2019-2022 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.event.lifecycle;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.geyser.api.event.Event;
+
+import java.nio.file.Path;
+import java.util.List;
+
+/**
+ * Called when resource packs are loaded within Geyser.
+ *
+ * @param resourcePacks a mutable list of the currently listed resource packs
+ */
+public record GeyserLoadResourcePacksEvent(@NonNull List<Path> resourcePacks) implements Event {
+}

api/geyser/src/main/java/org/geysermc/geyser/api/item/custom/CustomItemData.java

@@ -0,0 +1,109 @@
+/*
+ * Copyright (c) 2019-2022 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.item.custom;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.geysermc.geyser.api.GeyserApi;
+
+/**
+ * This is used to store data for a custom item.
+ */
+public interface CustomItemData {
+    /**
+     * Gets the item's name.
+     *
+     * @return the item's name
+     */
+    @NonNull String name();
+
+    /**
+     * Gets the custom item options of the item.
+     *
+     * @return the custom item options of the item.
+     */
+    CustomItemOptions customItemOptions();
+
+    /**
+     * Gets the item's display name. By default, this is the item's name.
+     *
+     * @return the item's display name
+     */
+    @NonNull String displayName();
+
+    /**
+     * Gets the item's icon. By default, this is the item's name.
+     *
+     * @return the item's icon
+     */
+    @NonNull String icon();
+
+    /**
+     * Gets if the item is allowed to be put into the offhand.
+     *
+     * @return true if the item is allowed to be used in the offhand, false otherwise
+     */
+    boolean allowOffhand();
+
+    /**
+     * Gets the item's texture size. This is to resize the item if the texture is not 16x16.
+     *
+     * @return the item's texture size
+     */
+    int textureSize();
+
+    /**
+     * Gets the item's render offsets. If it is null, the item will be rendered normally, with no offsets.
+     *
+     * @return the item's render offsets
+     */
+    @Nullable CustomRenderOffsets renderOffsets();
+
+    static CustomItemData.Builder builder() {
+        return GeyserApi.api().providerManager().builderProvider().provideBuilder(CustomItemData.Builder.class);
+    }
+
+    interface Builder {
+        /**
+         * Will also set the display name and icon to the provided parameter, if it is currently not set.
+         */
+        Builder name(@NonNull String name);
+
+        Builder customItemOptions(@NonNull CustomItemOptions customItemOptions);
+
+        Builder displayName(@NonNull String displayName);
+
+        Builder icon(@NonNull String icon);
+
+        Builder allowOffhand(boolean allowOffhand);
+
+        Builder textureSize(int textureSize);
+
+        Builder renderOffsets(@Nullable CustomRenderOffsets renderOffsets);
+
+        CustomItemData build();
+    }
+}

api/geyser/src/main/java/org/geysermc/geyser/api/item/custom/CustomItemOptions.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2019-2022 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.item.custom;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.geysermc.geyser.api.GeyserApi;
+import org.geysermc.geyser.api.util.TriState;
+
+import java.util.OptionalInt;
+
+/**
+ * This class represents the different ways you can register custom items
+ */
+public interface CustomItemOptions {
+    /**
+     * Gets if the item should be unbreakable.
+     *
+     * @return if the item should be unbreakable
+     */
+    @NonNull TriState unbreakable();
+
+    /**
+     * Gets the item's custom model data predicate.
+     *
+     * @return the item's custom model data
+     */
+    @NonNull OptionalInt customModelData();
+
+    /**
+     * Gets the item's damage predicate.
+     *
+     * @return the item's damage predicate
+     */
+    @NonNull OptionalInt damagePredicate();
+
+    /**
+     * Checks if the item has at least one option set
+     *
+     * @return true if the item at least one options set
+     */
+    default boolean hasCustomItemOptions() {
+        return this.unbreakable() != TriState.NOT_SET ||
+                this.customModelData().isPresent() ||
+                this.damagePredicate().isPresent();
+    }
+
+    static CustomItemOptions.Builder builder() {
+        return GeyserApi.api().providerManager().builderProvider().provideBuilder(CustomItemOptions.Builder.class);
+    }
+
+    interface Builder {
+        Builder unbreakable(boolean unbreakable);
+
+        Builder customModelData(int customModelData);
+
+        Builder damagePredicate(int damagePredicate);
+
+        CustomItemOptions build();
+    }
+}

api/geyser/src/main/java/org/geysermc/geyser/api/item/custom/CustomRenderOffsets.java

@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) 2019-2022 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.item.custom;
+
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+/**
+ * This class is used to store the render offsets of custom items.
+ */
+public record CustomRenderOffsets(@Nullable Hand mainHand, @Nullable Hand offhand) {
+    /**
+     * The hand that is used for the offset.
+     */
+    public record Hand(@Nullable Offset firstPerson, @Nullable Offset thirdPerson) {
+    }
+
+    /**
+     * The offset of the item.
+     */
+    public record Offset(@Nullable OffsetXYZ position, @Nullable OffsetXYZ rotation, @Nullable OffsetXYZ scale) {
+    }
+
+    /**
+     * X, Y and Z positions for the offset.
+     */
+    public record OffsetXYZ(float x, float y, float z) {
+    }
+}

api/geyser/src/main/java/org/geysermc/geyser/api/item/custom/NonVanillaCustomItemData.java

@@ -0,0 +1,188 @@
+/*
+ * Copyright (c) 2019-2022 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.item.custom;
+
+import org.checkerframework.checker.index.qual.NonNegative;
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+import org.geysermc.geyser.api.GeyserApi;
+
+import java.util.OptionalInt;
+import java.util.Set;
+
+/**
+ * Represents a completely custom item that is not based on an existing vanilla Minecraft item.
+ */
+public interface NonVanillaCustomItemData extends CustomItemData {
+    /**
+     * Gets the java identifier for this item.
+     *
+     * @return The java identifier for this item.
+     */
+    @NonNull String identifier();
+
+    /**
+     * Gets the java item id of the item.
+     *
+     * @return the java item id of the item
+     */
+    @NonNegative int javaId();
+
+    /**
+     * Gets the stack size of the item.
+     *
+     * @return the stack size of the item
+     */
+    @NonNegative int stackSize();
+
+    /**
+     * Gets the max damage of the item.
+     *
+     * @return the max damage of the item
+     */
+    int maxDamage();
+
+    /**
+     * Gets the tool type of the item.
+     *
+     * @return the tool type of the item
+     */
+    @Nullable String toolType();
+
+    /**
+     * Gets the tool tier of the item.
+     *
+     * @return the tool tier of the item
+     */
+    @Nullable String toolTier();
+
+    /**
+     * Gets the armor type of the item.
+     *
+     * @return the armor type of the item
+     */
+    @Nullable String armorType();
+
+    /**
+     * Gets the armor protection value of the item.
+     *
+     * @return the armor protection value of the item
+     */
+    int protectionValue();
+
+    /**
+     * Gets the item's translation string.
+     *
+     * @return the item's translation string
+     */
+    @Nullable String translationString();
+
+    /**
+     * Gets the repair materials of the item.
+     *
+     * @return the repair materials of the item
+     */
+    @Nullable Set<String> repairMaterials();
+
+    /**
+     * Gets the item's creative category, or tab id.
+     *
+     * @return the item's creative category
+     */
+    @NonNull OptionalInt creativeCategory();
+
+    /**
+     * Gets the item's creative group.
+     *
+     * @return the item's creative group
+     */
+    @Nullable String creativeGroup();
+
+    /**
+     * Gets if the item is a hat. This is used to determine if the item should be rendered on the player's head, and
+     * normally allow the player to equip it. This is not meant for armor.
+     *
+     * @return if the item is a hat
+     */
+    boolean isHat();
+
+    /**
+     * Gets if the item is a tool. This is used to set the render type of the item, if the item is handheld.
+     *
+     * @return if the item is a tool
+     */
+    boolean isTool();
+
+    static NonVanillaCustomItemData.Builder builder() {
+        return GeyserApi.api().providerManager().builderProvider().provideBuilder(NonVanillaCustomItemData.Builder.class);
+    }
+
+    interface Builder extends CustomItemData.Builder {
+        Builder name(@NonNull String name);
+
+        Builder identifier(@NonNull String identifier);
+
+        Builder javaId(@NonNegative int javaId);
+
+        Builder stackSize(@NonNegative int stackSize);
+
+        Builder maxDamage(int maxDamage);
+
+        Builder toolType(@Nullable String toolType);
+
+        Builder toolTier(@Nullable String toolTier);
+
+        Builder armorType(@Nullable String armorType);
+
+        Builder protectionValue(int protectionValue);
+
+        Builder translationString(@Nullable String translationString);
+
+        Builder repairMaterials(@Nullable Set<String> repairMaterials);
+
+        Builder creativeCategory(int creativeCategory);
+
+        Builder creativeGroup(@Nullable String creativeGroup);
+
+        Builder hat(boolean isHat);
+
+        Builder tool(boolean isTool);
+
+        @Override
+        Builder displayName(@NonNull String displayName);
+
+        @Override
+        Builder allowOffhand(boolean allowOffhand);
+
+        @Override
+        Builder textureSize(int textureSize);
+
+        @Override
+        Builder renderOffsets(@Nullable CustomRenderOffsets renderOffsets);
+
+        NonVanillaCustomItemData build();
+    }
+}

api/geyser/src/main/java/org/geysermc/geyser/api/util/TriState.java

@@ -0,0 +1,83 @@
+/*
+ * Copyright (c) 2019-2022 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
+package org.geysermc.geyser.api.util;
+
+import org.checkerframework.checker.nullness.qual.NonNull;
+import org.checkerframework.checker.nullness.qual.Nullable;
+
+/**
+ * This is a way to represent a boolean, but with a non set value added.
+ * This class was inspired by adventure's version https://github.com/KyoriPowered/adventure/blob/main/4/api/src/main/java/net/kyori/adventure/util/TriState.java
+ */
+public enum TriState {
+    /**
+     * Describes a value that is not set, null, or not present.
+     */
+    NOT_SET,
+
+    /**
+     * Describes a true value.
+     */
+    TRUE,
+
+    /**
+     * Describes a false value.
+     */
+    FALSE;
+
+    /**
+     * Converts the TriState to a boolean.
+     *
+     * @return the boolean value of the TriState
+     */
+    public @Nullable Boolean toBoolean() {
+        return switch (this) {
+            case TRUE -> true;
+            case FALSE -> false;
+            default -> null;
+        };
+    }
+
+    /**
+     * Creates a TriState from a boolean.
+     *
+     * @param value the Boolean value
+     * @return the created TriState
+     */
+    public static @NonNull TriState fromBoolean(@Nullable Boolean value) {
+        return value == null ? NOT_SET : fromBoolean(value.booleanValue());
+    }
+
+    /**
+     * Creates a TriState from a primitive boolean.
+     *
+     * @param value the boolean value
+     * @return the created TriState
+     */
+    public @NonNull static TriState fromBoolean(boolean value) {
+        return value ? TRUE : FALSE;
+    }
+}