DreamParticles.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.DreamParticles;
 
import org.bukkit.Location;
import org.bukkit.Particle;
import org.bukkit.World;
import org.bukkit.util.Vector;
 
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.Objects;
 
public final class DreamParticles {
 
    private DreamParticles() {}
 
    /* ======================================================================
     * Basic single-point emission
     * ====================================================================== */
 
    public static void spawnSingle(World world, Particle particle, Location location) {
        if (world == null || particle == null || location == null || location.getWorld() == null) return;
        world.spawnParticle(particle, location, 1, 0, 0, 0, 0);
    }
 
    public static void spawnSingle(World world, Particle particle, Vector point) {
        if (world == null || particle == null || point == null) return;
        world.spawnParticle(particle, point.getX(), point.getY(), point.getZ(), 1, 0, 0, 0, 0);
    }
 
    public static void spawn(
            World world, Particle particle, Location location,
            int count, double offsetX, double offsetY, double offsetZ, double speed,
            Object data, boolean force
    ) {
        if (world == null || particle == null || location == null || location.getWorld() == null) return;
        if (count <= 0) return;
        world.spawnParticle(particle, location, count, offsetX, offsetY, offsetZ, speed, data, force);
    }
 
    /* ======================================================================
     * Legacy-style simple wrappers (kept for convenience)
     * ====================================================================== */
 
    public static void spawn(World world, Particle particle, Location location,
                             int count, double offsetX, double offsetY, double offsetZ, double speed) {
        spawn(world, particle, location, count, offsetX, offsetY, offsetZ, speed, null, false);
    }
 
    /* ======================================================================
     * Generic Shape System
     * ====================================================================== */
 
    @FunctionalInterface
    public interface ParticleShape {
        Collection<Vector> sample();
    }
 
    public static void emitShape(
            World world, Particle particle, Location origin,
            ParticleShape shape,
            int count, double offsetX, double offsetY, double offsetZ, double speed,
            Object data, boolean force
    ) {
        if (world == null || particle == null || origin == null || origin.getWorld() == null) return;
        if (shape == null) return;
        if (count <= 0) return;
 
        for (Vector rel : shape.sample()) {
            Location at = origin.clone().add(rel);
            world.spawnParticle(particle, at, count, offsetX, offsetY, offsetZ, speed, data, force);
        }
    }
 
    public static void emitShape(
            World world, Particle particle, Location origin, ParticleShape shape,
            int count, double offsetXYZ, double speed
    ) {
        emitShape(world, particle, origin, shape, count, offsetXYZ, offsetXYZ, offsetXYZ, speed, null, false);
    }
 
    /* ======================================================================
     * Ready-made shapes
     * ====================================================================== */
 
    private static int positive(int n, int fallback) {
        return (n > 0) ? n : fallback;
    }
 
    public static ParticleShape sphere(double radius, int rings, int segments) {
        final double R = Math.max(0.0, radius);
        final int RINGS = positive(rings, 12);
        final int SEGS  = positive(segments, 24);
 
        return () -> {
            List<Vector> pts = new ArrayList<>(RINGS * SEGS);
            for (int i = 0; i <= RINGS; i++) {
                double theta = Math.PI * i / RINGS; // 0..π
                double sin = Math.sin(theta);
                double cos = Math.cos(theta);
                double ringR = R * sin;
                double y = R * cos;
                for (int j = 0; j < SEGS; j++) {
                    double phi = (2 * Math.PI) * j / SEGS; // 0..2π
                    double x = Math.cos(phi) * ringR;
                    double z = Math.sin(phi) * ringR;
                    pts.add(new Vector(x, y, z));
                }
            }
            return pts;
        };
    }
 
    public static ParticleShape ring(double radius, int segments) {
        final double R = Math.max(0.0, radius);
        final int SEGS = positive(segments, 64);
        return () -> {
            List<Vector> pts = new ArrayList<>(SEGS);
            for (int j = 0; j < SEGS; j++) {
                double a = (2 * Math.PI) * j / SEGS;
                pts.add(new Vector(Math.cos(a) * R, 0, Math.sin(a) * R));
            }
            return pts;
        };
    }
 
    public static ParticleShape cube(double sideLength, int stepsPerEdge) {
        final double L = Math.max(0.0, sideLength);
        final int STEPS = positive(stepsPerEdge, 8);
        final double half = L / 2.0;
        final double step = (STEPS <= 1 ? L : L / (STEPS - 1));
 
        return () -> {
            List<Vector> pts = new ArrayList<>(STEPS * STEPS * 6);
            // Six faces: +/-X, +/-Y, +/-Z
            for (int i = 0; i < STEPS; i++) {
                double t = -half + i * step;
                for (int j = 0; j < STEPS; j++) {
                    double u = -half + j * step;
 
                    // +X, -X
                    pts.add(new Vector( half, t, u));
                    pts.add(new Vector(-half, t, u));
                    // +Y, -Y
                    pts.add(new Vector(t,  half, u));
                    pts.add(new Vector(t, -half, u));
                    // +Z, -Z
                    pts.add(new Vector(t, u,  half));
                    pts.add(new Vector(t, u, -half));
                }
            }
            return pts;
        };
    }
 
    public static ParticleShape cone(double radius, double height, int rings, int segments) {
        final double R = Math.max(0.0, radius);
        final double H = Math.max(0.0, height);
        final int RINGS = positive(rings, 12);
        final int SEGS  = Math.max(3, segments);
 
        return () -> {
            List<Vector> pts = new ArrayList<>(RINGS * SEGS);
            for (int i = 0; i <= RINGS; i++) {
                double y = (H * i) / RINGS;
                double ringR = (H == 0.0) ? 0.0 : R * (1.0 - (y / H)); // linear taper
                for (int j = 0; j < SEGS; j++) {
                    double a = (2 * Math.PI) * j / SEGS;
                    double x = Math.cos(a) * ringR;
                    double z = Math.sin(a) * ringR;
                    pts.add(new Vector(x, y, z));
                }
            }
            return pts;
        };
    }
 
    public static ParticleShape spiral(double radius, double height, double turns, int points) {
        final double R = Math.max(0.0, radius);
        final double H = Math.max(0.0, height);
        final double TURNS = Math.max(0.0, turns);
        final int PTS = positive(points, 256);
 
        return () -> {
            List<Vector> out = new ArrayList<>(PTS);
            double maxAngle = TURNS * 2.0 * Math.PI;
            for (int i = 0; i < PTS; i++) {
                double t = (PTS == 1) ? 0.0 : (double) i / (PTS - 1);
                double angle = maxAngle * t;
                double y = H * t;
                double x = Math.cos(angle) * R;
                double z = Math.sin(angle) * R;
                out.add(new Vector(x, y, z));
            }
            return out;
        };
    }
 
    /* ======================================================================
     * Orientation helpers
     * ====================================================================== */
 
    public static Vector rotateAroundAxis(Vector v, Vector axisNormalized, double angle) {
        Objects.requireNonNull(v, "v");
        Objects.requireNonNull(axisNormalized, "axisNormalized");
        Vector k = axisNormalized.clone().normalize();
        double cos = Math.cos(angle);
        double sin = Math.sin(angle);
        // v_rot = v*cos + (k x v)*sin + k*(k·v)*(1-cos)
        Vector cross = k.clone().crossProduct(v).multiply(sin);
        Vector term1 = v.clone().multiply(cos);
        Vector term2 = cross;
        Vector term3 = k.clone().multiply(k.dot(v) * (1.0 - cos));
        return term1.add(term2).add(term3);
    }
 
    public static List<Vector> rotatePoints(Collection<Vector> points, Vector axis, double angle) {
        Objects.requireNonNull(points, "points");
        Objects.requireNonNull(axis, "axis");
        List<Vector> out = new ArrayList<>(points.size());
        Vector n = axis.clone().normalize();
        for (Vector p : points) {
            out.add(rotateAroundAxis(p, n, angle));
        }
        return out;
    }
 
    public static List<Vector> orientPoints(Collection<Vector> points, Vector axis) {
        Objects.requireNonNull(points, "points");
        Objects.requireNonNull(axis, "axis");
        Vector y = new Vector(0, 1, 0);
        Vector n = axis.clone().normalize();
 
        double dot = y.dot(n);
        // Already aligned:
        if (Math.abs(dot - 1.0) < 1e-6) return new ArrayList<>(points); // same direction
        if (Math.abs(dot + 1.0) < 1e-6) {                                // opposite: rotate 180° around any perpendicular
            Vector perp = new Vector(1, 0, 0);
            if (Math.abs(y.dot(perp)) > 0.99) perp = new Vector(0, 0, 1);
            return rotatePoints(points, perp, Math.PI);
        }
 
        // Rotation axis is cross product; angle is arccos(dot)
        Vector axisRot = y.clone().crossProduct(n).normalize();
        double angle = Math.acos(dot);
        return rotatePoints(points, axisRot, angle);
    }
 
    /* ======================================================================
     * Deprecated legacy API (kept to ease migration)
     * ====================================================================== */
 
    @Deprecated
    public static void spawnParticle(World world, Particle particle, Location location) {
        spawnSingle(world, particle, location);
    }
 
    @Deprecated
    public static void spawnParticle(World world, Particle particle, Vector point) {
        spawnSingle(world, particle, point);
    }
 
    @Deprecated
    public static void spawnParticle(World world, Particle particle, Location location,
                                     int count, double offsetX, double offsetY, double offsetZ, double speed) {
        spawn(world, particle, location, count, offsetX, offsetY, offsetZ, speed);
    }
}