DreamItemDisplay.java

Go to the documentation of this file.

/*
 * MIT License
 *
 * Copyright (c) 2025 Dreamfire Studio
 *
 * 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.
 */
package com.dreamfirestudios.dreamcore.DreamItemDisplay;
 
import org.bukkit.Bukkit;
import org.bukkit.Color;
import org.bukkit.Location;
import org.bukkit.Material;
import org.bukkit.World;
import org.bukkit.entity.Display;
import org.bukkit.entity.ItemDisplay;
import org.bukkit.inventory.ItemStack;
import org.bukkit.util.Transformation;
import org.joml.Quaternionf;
import org.joml.Vector3f;
 
public final class DreamItemDisplay {
 
    private DreamItemDisplay() {}
 
    public static class ItemDisplayBuilder {
        // -------------------- Defaults --------------------
        private World world = Bukkit.getWorlds().isEmpty() ? null : Bukkit.getWorlds().get(0);
        private Location location = (world == null) ? null : world.getSpawnLocation();
 
        private float uniformScale = 1.0f;
        private Vector3f scale = null;                        // if non-null, overrides uniformScale
        private Quaternionf leftRotation = new Quaternionf(); // identity
        private Quaternionf rightRotation = new Quaternionf();// identity
        private Vector3f translation = new Vector3f(0f, 0f, 0f);
 
        // Display properties
        private float viewRange = 16.0f;
 
        private float shadowRadius = 0.3f;
 
        private float shadowStrength = 0.5f;
 
        private float displayWidth = 1f;
 
        private float displayHeight = 1f;
 
        private Display.Billboard billboard = Display.Billboard.CENTER;
        private Color itemGlowColor = null;                // null = no override
        private Display.Brightness itemBrightness = null;  // null = default brightness
 
        // -------------------- World / position --------------------
 
        public ItemDisplayBuilder world(World world) {
            if (world == null) throw new IllegalArgumentException("World cannot be null");
            this.world = world;
            if (this.location == null) this.location = world.getSpawnLocation();
            return this;
        }
 
        public ItemDisplayBuilder location(Location location) {
            if (location == null) throw new IllegalArgumentException("Location cannot be null");
            this.location = location;
            if (location.getWorld() != null) this.world = location.getWorld();
            return this;
        }
 
        public ItemDisplayBuilder translation(Vector3f translation) {
            if (translation == null) throw new IllegalArgumentException("translation cannot be null");
            this.translation = new Vector3f(translation);
            return this;
        }
 
        // -------------------- Scale --------------------
 
        public ItemDisplayBuilder scale(float uniform) {
            if (uniform <= 0f) throw new IllegalArgumentException("Scale must be > 0");
            this.uniformScale = uniform;
            this.scale = null;
            return this;
        }
 
        public ItemDisplayBuilder scale(Vector3f scale) {
            if (scale == null) throw new IllegalArgumentException("scale cannot be null");
            if (scale.x <= 0f || scale.y <= 0f || scale.z <= 0f)
                throw new IllegalArgumentException("scale components must be > 0");
            this.scale = new Vector3f(scale);
            return this;
        }
 
        // -------------------- Rotation --------------------
 
        public ItemDisplayBuilder leftRotation(Quaternionf q) {
            if (q == null) throw new IllegalArgumentException("leftRotation cannot be null");
            this.leftRotation = new Quaternionf(q);
            return this;
        }
 
        public ItemDisplayBuilder rightRotation(Quaternionf q) {
            if (q == null) throw new IllegalArgumentException("rightRotation cannot be null");
            this.rightRotation = new Quaternionf(q);
            return this;
        }
 
        public ItemDisplayBuilder eulerDegrees(float yawDeg, float pitchDeg, float rollDeg) {
            final float yaw = (float) Math.toRadians(yawDeg);
            final float pitch = (float) Math.toRadians(pitchDeg);
            final float roll = (float) Math.toRadians(rollDeg);
 
            this.leftRotation = new Quaternionf()
                    .rotateZ(yaw)
                    .rotateX(pitch)
                    .rotateY(roll);
            return this;
        }
 
        // -------------------- Display props --------------------
 
        public ItemDisplayBuilder viewRange(float viewRange) {
            if (viewRange < 0f) throw new IllegalArgumentException("viewRange must be >= 0");
            this.viewRange = viewRange;
            return this;
        }
 
        public ItemDisplayBuilder shadowRadius(float shadowRadius) {
            if (shadowRadius < 0f) throw new IllegalArgumentException("shadowRadius must be >= 0");
            this.shadowRadius = shadowRadius;
            return this;
        }
 
        public ItemDisplayBuilder shadowStrength(float shadowStrength) {
            this.shadowStrength = shadowStrength;
            return this;
        }
 
        public ItemDisplayBuilder displayHeight(float displayHeight) {
            if (displayHeight <= 0f) throw new IllegalArgumentException("displayHeight must be > 0");
            this.displayHeight = displayHeight;
            return this;
        }
 
        public ItemDisplayBuilder displayWidth(float displayWidth) {
            if (displayWidth <= 0f) throw new IllegalArgumentException("displayWidth must be > 0");
            this.displayWidth = displayWidth;
            return this;
        }
 
        public ItemDisplayBuilder billboard(Display.Billboard billboard) {
            this.billboard = (billboard == null) ? Display.Billboard.CENTER : billboard;
            return this;
        }
 
        public ItemDisplayBuilder glowColor(Color color) {
            this.itemGlowColor = color; // null clears
            return this;
        }
 
        public ItemDisplayBuilder brightness(Display.Brightness brightness) {
            this.itemBrightness = brightness; // null = default
            return this;
        }
 
        // -------------------- Spawn --------------------
 
        public ItemDisplay spawn(ItemStack itemStack) {
            if (itemStack == null || itemStack.getType() == Material.AIR)
                throw new IllegalArgumentException("ItemStack cannot be null or AIR");
            if (world == null)
                throw new IllegalStateException("No world available to spawn ItemDisplay");
            if (location == null)
                location = world.getSpawnLocation();
 
            final ItemDisplay display = world.spawn(location, ItemDisplay.class);
            display.setItemStack(itemStack);
 
            // Apply transformation
            final Vector3f sc = (scale != null) ? new Vector3f(scale) : new Vector3f(uniformScale);
            final Transformation tf = new Transformation(
                    new Vector3f(translation),
                    new Quaternionf(leftRotation),
                    sc,
                    new Quaternionf(rightRotation)
            );
            display.setTransformation(tf);
 
            // Clamp & apply display properties
            display.setViewRange(Math.max(0f, viewRange));
            display.setShadowRadius(Math.max(0f, shadowRadius));
            display.setShadowStrength(Math.max(0f, Math.min(1f, shadowStrength)));
            display.setDisplayWidth(Math.max(0.0001f, displayWidth));
            display.setDisplayHeight(Math.max(0.0001f, displayHeight));
            display.setBillboard(billboard);
 
            if (itemGlowColor != null) display.setGlowColorOverride(itemGlowColor);
            if (itemBrightness != null) display.setBrightness(itemBrightness);
 
            new ItemDisplaySpawnEvent(display);
            return display;
        }
    }
}