feat: implement "mutable" transform holder for random rotations

 - also implement random rotation to schematic loadall
 - "mutable" transform allows random rotation of schematics outside of clipboard brush
 - fixes #3129

Author: dordsor21

worldedit-core/src/main/java/com/fastasyncworldedit/core/extent/clipboard/MultiClipboardHolder.java

@@ -3,18 +3,20 @@
 import com.sk89q.worldedit.extent.clipboard.Clipboard;
 import com.sk89q.worldedit.session.ClipboardHolder;
 
+import javax.annotation.Nonnull;
 import java.io.IOException;
 import java.net.URI;
 import java.util.ArrayList;
 import java.util.HashSet;
+import java.util.Iterator;
 import java.util.List;
 import java.util.Set;
 import java.util.UUID;
 import java.util.concurrent.ThreadLocalRandom;
 
 import static com.google.common.base.Preconditions.checkNotNull;
 
-public class MultiClipboardHolder extends URIClipboardHolder {
+public class MultiClipboardHolder extends URIClipboardHolder implements Iterable<URIClipboardHolder> {
 
     private final List<URIClipboardHolder> holders;
     private Clipboard[] cached;
@@ -194,4 +196,9 @@ public void flush() {
         }
     }
 
+    @Override
+    public @Nonnull Iterator<URIClipboardHolder> iterator() {
+        return holders.iterator();
+    }
+
 }

worldedit-core/src/main/java/com/fastasyncworldedit/core/function/generator/SchemGen.java

@@ -92,6 +92,7 @@ public boolean spawn(Random random, int x, int z) throws WorldEditException {
         if (transform.isIdentity()) {
             clipboard.paste(extent, mutable, false);
         } else {
+            transform.mutate();
             clipboard.paste(extent, mutable, false, transform);
         }
         mutable.mutY(y);

worldedit-core/src/main/java/com/fastasyncworldedit/core/function/pattern/RandomFullClipboardPattern.java

@@ -67,6 +67,7 @@ public boolean apply(Extent extent, BlockVector3 get, BlockVector3 set) throws W
         if (newTransform.isIdentity()) {
             clipboard.paste(extent, set, false);
         } else {
+            newTransform.mutate();
             clipboard.paste(extent, set, false, newTransform);
         }
         return true;

worldedit-core/src/main/java/com/fastasyncworldedit/core/math/transform/MutatingOperationTransformHolder.java

@@ -0,0 +1,62 @@
+package com.fastasyncworldedit.core.math.transform;
+
+import com.sk89q.worldedit.math.Vector3;
+import com.sk89q.worldedit.math.transform.Transform;
+
+import java.util.function.Function;
+
+/**
+ * Applies an operation on a {@link Transform} when {@link MutatingOperationTransformHolder#mutate()} is called. Typically at
+ * the start of an operation.
+ *
+ * @param <T> transform to mutate type
+ * @since TODO
+ */
+public class MutatingOperationTransformHolder<T extends Transform> implements Transform {
+
+    private final Function<? super T, ? extends T> operation;
+    private T transform;
+
+    /**
+     * Construct new instance
+     *
+     * @param transform transform to mutate
+     * @since TODO
+     */
+    public MutatingOperationTransformHolder(T transform, Function<? super T, ? extends T> operation) {
+        this.transform = transform;
+        this.operation = operation;
+    }
+
+    /**
+     * Apply the mutator to the transform
+     *
+     * @since TODO
+     */
+    public void mutate() {
+        if (operation != null) {
+            transform = operation.apply(transform);
+        }
+    }
+
+    @Override
+    public boolean isIdentity() {
+        return transform.isIdentity();
+    }
+
+    @Override
+    public Vector3 apply(final Vector3 input) {
+        return transform.apply(input);
+    }
+
+    @Override
+    public Transform inverse() {
+        return transform.inverse();
+    }
+
+    @Override
+    public Transform combine(final Transform other) {
+        return transform.combine(other);
+    }
+
+}

worldedit-core/src/main/java/com/sk89q/worldedit/command/ClipboardCommands.java

@@ -404,6 +404,7 @@ public void run(OutputStream out) {
             final Clipboard target;
             // If we have a transform, bake it into the copy
             if (!transform.isIdentity()) {
+                transform.mutate();
                 target = clipboard.transform(transform);
             } else {
                 target = clipboard;
@@ -472,9 +473,10 @@ public void place(
         Region region = clipboard.getRegion().clone();
         if (selectPasted || onlySelect || removeEntities) {
             BlockVector3 clipboardOffset = clipboard.getRegion().getMinimumPoint().subtract(clipboard.getOrigin());
-            BlockVector3 realTo = to.add(holder.getTransform().apply(clipboardOffset.toVector3()).toBlockPoint());
-            BlockVector3 max = realTo.add(holder
-                    .getTransform()
+            Transform transform = holder.getTransform();
+            transform.mutate();
+            BlockVector3 realTo = to.add(transform.apply(clipboardOffset.toVector3()).toBlockPoint());
+            BlockVector3 max = realTo.add(transform
                     .apply(region.getMaximumPoint().subtract(region.getMinimumPoint()).toVector3())
                     .toBlockPoint());
             if (removeEntities) {
@@ -564,6 +566,7 @@ public void paste(
 
         if (selectPasted || onlySelect || removeEntities) {
             BlockVector3 clipboardOffset = clipboard.getRegion().getMinimumPoint().subtract(clipboard.getOrigin());
+            holder.getTransform().mutate(); //FAWE: mutate transform
             Vector3 realTo = to.toVector3().add(holder.getTransform().apply(clipboardOffset.toVector3()));
             Vector3 max = realTo.add(holder
                     .getTransform()

worldedit-core/src/main/java/com/sk89q/worldedit/command/SchematicCommands.java

@@ -24,7 +24,7 @@
 import com.fastasyncworldedit.core.event.extent.ActorSaveClipboardEvent;
 import com.fastasyncworldedit.core.extent.clipboard.MultiClipboardHolder;
 import com.fastasyncworldedit.core.extent.clipboard.URIClipboardHolder;
-import com.fastasyncworldedit.core.extent.clipboard.io.schematic.MinecraftStructure;
+import com.fastasyncworldedit.core.math.transform.MutatingOperationTransformHolder;
 import com.fastasyncworldedit.core.util.MainUtil;
 import com.google.common.collect.Multimap;
 import com.sk89q.worldedit.LocalConfiguration;
@@ -158,9 +158,11 @@ public void loadall(
             @Arg(desc = "File name.")
                     String filename,
             @Switch(name = 'o', desc = "Overwrite/replace existing clipboard(s)")
-                    boolean overwrite
-//            @Switch(name = 'r', desc = "Apply random rotation") <- not implemented below.
-//                    boolean randomRotate
+                    boolean overwrite,
+            @Switch(name = 'r', desc = "Apply random rotation (static by default)")
+                    boolean randomRotate,
+            @Switch(name = 'd', desc = "Random rotation is dynamic, changing each use")
+                    boolean dynamicRandom
     ) throws FilenameException {
         final ClipboardFormat format = ClipboardFormats.findByAlias(formatName);
         if (format == null) {
@@ -169,19 +171,44 @@ public void loadall(
         }
         try {
             MultiClipboardHolder all = ClipboardFormats.loadAllFromInput(actor, filename, null, true);
-            if (all != null) {
-                if (overwrite) {
-                    session.setClipboard(all);
-                } else {
-                    session.addClipboard(all);
-                }
+            if (all == null) {
                 actor.print(Caption.of("fawe.worldedit.schematic.schematic.loaded", filename));
+                return;
+            }
+            if (randomRotate) {
+                for (ClipboardHolder holder : all) {
+                    setRandomRotateTransform(dynamicRandom, holder);
+                }
+                setRandomRotateTransform(dynamicRandom, all);
+            }
+            if (overwrite) {
+                session.setClipboard(all);
+            } else {
+                session.addClipboard(all);
             }
+            actor.print(Caption.of("fawe.worldedit.schematic.schematic.loaded", filename));
         } catch (IOException e) {
             throw new RuntimeException(e);
         }
     }
 
+    private static void setRandomRotateTransform(boolean dynamicRandom, ClipboardHolder holder) {
+        if (dynamicRandom) {
+            MutatingOperationTransformHolder<AffineTransform> mutating = new MutatingOperationTransformHolder<>(
+                    new AffineTransform(), t -> {
+                int rotate = 90 * ThreadLocalRandom.current().nextInt(4);
+                return t.rotateY(rotate);
+            }
+            );
+            holder.setTransform(mutating);
+        } else {
+            AffineTransform transform = new AffineTransform();
+            int rotate = 90 * ThreadLocalRandom.current().nextInt(4);
+            transform = transform.rotateY(rotate);
+            holder.setTransform(transform);
+        }
+    }
+
     @Command(
             name = "clear",
             desc = "Clear your clipboard"
@@ -319,7 +346,9 @@ public void load(
             @Arg(desc = "Format name.", def = "")
                     String formatName,
             @Switch(name = 'r', desc = "Apply random rotation to the clipboard")
-                    boolean randomRotate
+                    boolean randomRotate,
+            @Switch(name = 'd', desc = "Random rotation is dynamic, changing each use")
+                    boolean dynamicRandom
             //FAWE end
     ) throws FilenameException {
         LocalConfiguration config = worldEdit.getConfiguration();
@@ -435,10 +464,7 @@ public void load(
             closer.register(in);
             format.hold(actor, uri, in);
             if (randomRotate) {
-                AffineTransform transform = new AffineTransform();
-                int rotate = 90 * ThreadLocalRandom.current().nextInt(4);
-                transform = transform.rotateY(rotate);
-                session.getClipboard().setTransform(transform);
+                setRandomRotateTransform(dynamicRandom, session.getClipboard());
             }
             actor.print(Caption.of("fawe.worldedit.schematic.schematic.loaded", filename));
         } catch (IllegalArgumentException e) {
@@ -889,6 +915,7 @@ private abstract static class SchematicOutputTask<T> implements Callable<T> {
         protected void writeToOutputStream(OutputStream outputStream) throws IOException, WorldEditException {
             Clipboard clipboard = holder.getClipboard();
             Transform transform = holder.getTransform();
+            transform.mutate(); //FAWE: mutate transform
             Clipboard target = clipboard.transform(transform);
 
             try (Closer closer = Closer.create()) {
@@ -928,6 +955,7 @@ public Void call() throws Exception {
             Clipboard target;
 
             //FAWE start
+            transform.mutate();
             boolean checkFilesize = Settings.settings().PATHS.PER_PLAYER_SCHEMATICS
                     && actor.getLimit().SCHEM_FILE_SIZE_LIMIT > -1;
 

worldedit-core/src/main/java/com/sk89q/worldedit/command/argument/FactoryConverter.java

@@ -98,6 +98,7 @@ public static void register(WorldEdit worldEdit, CommandManager commandManager)
                             try {
                                 ClipboardHolder holder = context.getSession().getClipboard();
                                 Transform transform = holder.getTransform();
+                                transform.mutate(); //FAWE: mutate transform
                                 Extent target;
                                 if (transform.isIdentity()) {
                                     target = holder.getClipboard();

worldedit-core/src/main/java/com/sk89q/worldedit/command/tool/brush/ClipboardBrush.java

@@ -90,6 +90,7 @@ public void build(EditSession editSession, BlockVector3 position, Pattern patter
             int rotate = 90 * ThreadLocalRandom.current().nextInt(4);
             transform = ((AffineTransform) transform).rotateY(rotate);
             if (originalTransform != null) {
+                originalTransform.mutate();
                 transform = originalTransform.combine(transform);
             }
         }

worldedit-core/src/main/java/com/sk89q/worldedit/math/transform/CombinedTransform.java

@@ -96,4 +96,11 @@ public Transform combine(Transform other) {
         }
     }
 
+    @Override
+    public void mutate() {
+        for (Transform transform : transforms) {
+            transform.mutate();
+        }
+    }
+
 }

worldedit-core/src/main/java/com/sk89q/worldedit/math/transform/Transform.java

@@ -58,4 +58,18 @@ public interface Transform {
      */
     Transform combine(Transform other);
 
+    //FAWE start- mutating transforms
+
+    /**
+     * Perform a mutation on this transform, if supported. Else, does nothing. This mutation will depend on the specific
+     * transform implementation.
+     * <p>
+     * Implementation detail: it may be possible for this method to be called multiple times before an operation actually occurs.
+     *
+     * @since TODO
+     */
+    default void mutate() {
+    }
+    //FAWE end
+
 }