5.1

src/main/java/org/mvplugins/multiverse/core/MultiverseCore.java

@@ -15,6 +15,7 @@
 import jakarta.inject.Provider;
 import org.bukkit.configuration.file.FileConfiguration;
 import org.bukkit.configuration.serialization.ConfigurationSerialization;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.jvnet.hk2.annotations.Service;
 
@@ -238,7 +239,11 @@ private void logEnableMessage() {
      * Gets the MultiverseCoreApi
      *
      * @return The MultiverseCoreApi
+     *
+     * @deprecated Use {@link MultiverseCoreApi#get()} directly.
      */
+    @Deprecated(since = "5.1", forRemoval = true)
+    @ApiStatus.ScheduledForRemoval(inVersion = "6.0")
     public MultiverseCoreApi getApi() {
         return MultiverseCoreApi.get();
     }

src/main/java/org/mvplugins/multiverse/core/MultiverseCoreApi.java

@@ -2,6 +2,7 @@
 
 import org.bukkit.Bukkit;
 import org.bukkit.plugin.ServicePriority;
+import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NotNull;
 import org.mvplugins.multiverse.core.anchor.AnchorManager;
 import org.mvplugins.multiverse.core.config.CoreConfig;
@@ -15,32 +16,78 @@
 import org.mvplugins.multiverse.core.world.biomeprovider.BiomeProviderFactory;
 import org.mvplugins.multiverse.core.world.generators.GeneratorProvider;
 
+import java.util.ArrayList;
+import java.util.List;
 import java.util.Objects;
+import java.util.function.Consumer;
 
 /**
  * Provides access to the MultiverseCore API.
  */
 public class MultiverseCoreApi {
 
     private static MultiverseCoreApi instance;
+    private static final List<Consumer<MultiverseCoreApi>> whenLoadedCallbacks = new ArrayList<>();
 
     static void init(@NotNull MultiverseCore multiverseCore) {
         if (instance != null) {
             throw new IllegalStateException("MultiverseCoreApi has already been initialized!");
         }
         instance = new MultiverseCoreApi(multiverseCore.getServiceLocator());
         Bukkit.getServicesManager().register(MultiverseCoreApi.class, instance, multiverseCore, ServicePriority.Normal);
+
+        whenLoadedCallbacks.forEach(c -> c.accept(instance));
+        whenLoadedCallbacks.clear();
     }
 
     static void shutdown() {
         Bukkit.getServicesManager().unregister(instance);
         instance = null;
     }
 
+    /**
+     * Hook your plugin into the MultiverseCoreApi here to ensure you only start using the API after it has been initialized.
+     * Use this if you know your plugin may load before Multiverse-Core is fully initialized.
+     * <br/>
+     * This handy method removes the need for you to check with plugin manager or listen to plugin enable event.
+     * <br/>
+     * Callback will be called immediately if the MultiverseCoreApi has already been initialized.
+     *
+     * @param consumer The callback to execute when the MultiverseCoreApi has been initialized.
+     *
+     * @since 5.1
+     */
+    @ApiStatus.AvailableSince("5.1")
+    public static void whenLoaded(@NotNull Consumer<MultiverseCoreApi> consumer) {
+        if (instance != null) {
+            consumer.accept(instance);
+        } else {
+            whenLoadedCallbacks.add(consumer);
+        }
+    }
+
+    /**
+     * Checks if the MultiverseCoreApi has been initialized.
+     *
+     * @return True if the MultiverseCoreApi has been initialized, false otherwise
+     *
+     * @since 5.1
+     */
+    @ApiStatus.AvailableSince("5.1")
+    public static boolean isLoaded() {
+        return instance != null;
+    }
+
     /**
      * Gets the MultiverseCoreApi. This will throw an exception if the Multiverse-Core has not been initialized.
+     * <br/>
+     * You can check if the MultiverseCoreApi has been initialized with {@link #isLoaded()} before using this method.
+     * <br/>
+     * Alternatively, you can use {@link #whenLoaded(Consumer)} to hook into the MultiverseCoreApi if your plugin may
+     * load before Multiverse-Core is fully initialized.
      *
      * @return The MultiverseCoreApi
+     * @throws IllegalStateException if the MultiverseCoreApi has not been initialized
      */
     public static @NotNull MultiverseCoreApi get() {
         if (instance == null) {

src/main/java/org/mvplugins/multiverse/core/PlaceholderExpansionHook.java

@@ -1,5 +1,6 @@
 package org.mvplugins.multiverse.core;
 
+import com.google.common.collect.Lists;
 import io.vavr.control.Option;
 import jakarta.annotation.PostConstruct;
 import jakarta.inject.Inject;
@@ -13,11 +14,16 @@
 import org.jvnet.hk2.annotations.Service;
 
 import org.mvplugins.multiverse.core.economy.MVEconomist;
+import org.mvplugins.multiverse.core.utils.MinecraftTimeFormatter;
 import org.mvplugins.multiverse.core.utils.REPatterns;
 import org.mvplugins.multiverse.core.utils.StringFormatter;
 import org.mvplugins.multiverse.core.world.LoadedMultiverseWorld;
 import org.mvplugins.multiverse.core.world.WorldManager;
 
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
 @Service
 final class PlaceholderExpansionHook extends PlaceholderExpansion {
 
@@ -68,32 +74,54 @@ public boolean persist() {
     @Override
     public @Nullable String onRequest(OfflinePlayer offlinePlayer, @NotNull String params) {
         // Split string in to an Array with underscores
-        String[] paramsArray = REPatterns.UNDERSCORE.split(params, 2);
+        List<String> paramsArray = Lists.newArrayList(REPatterns.UNDERSCORE.split(params));
 
         // No placeholder defined
-        if (paramsArray.length < 1) {
-            warning("No placeholder defined");
+        if (paramsArray.isEmpty()) {
+            warning("No placeholder key defined");
             return null;
         }
 
-        final var placeholder = paramsArray[0];
-        Option<LoadedMultiverseWorld> targetWorld;
+        final var placeholder = paramsArray.removeFirst();
+
+        String worldName = parseWorldName(offlinePlayer, paramsArray);
+        if (worldName == null) return null;
+
+        return worldManager.getLoadedWorld(worldName)
+                .onEmpty(() -> warning("Multiverse World not found: " + worldName))
+                .map(world -> getWorldPlaceHolderValue(placeholder, paramsArray, world))
+                .getOrNull();
+    }
 
-        // If no world is defined, use the player's world
-        if (paramsArray.length == 1) {
-            if (!offlinePlayer.isOnline()) {
+    private @Nullable String parseWorldName(OfflinePlayer offlinePlayer, List<String> paramsArray) {
+        // No world defined, get from player
+        if (paramsArray.isEmpty()) {
+            if (offlinePlayer instanceof Player player) {
+                return player.getWorld().getName();
+            } else {
+                warning("You must specify a world name for non-player placeholders");
                 return null;
             }
-            targetWorld = worldManager.getLoadedWorld(((Player)offlinePlayer).getWorld());
-        } else {
-            targetWorld = worldManager.getLoadedWorld(paramsArray[1]);
         }
 
-        // Fail if world is null
-        return targetWorld.map(world -> getWorldPlaceHolderValue(placeholder, world)).getOrNull();
+        // Try get from params
+        String paramWorldName = paramsArray.getLast();
+        if (worldManager.isLoadedWorld(paramWorldName)) {
+            paramsArray.removeLast();
+            return paramWorldName;
+        }
+
+        // Param not a world, fallback to player
+        if (offlinePlayer instanceof Player player) {
+            return player.getWorld().getName();
+        }
+        warning("Multiverse World not found: " + paramWorldName);
+        return null;
     }
 
-    private @Nullable String getWorldPlaceHolderValue(@NotNull String placeholder, @NotNull LoadedMultiverseWorld world) {
+    private @Nullable String getWorldPlaceHolderValue(@NotNull String placeholder,
+                                                      @NotNull List<String> placeholderParams,
+                                                      @NotNull LoadedMultiverseWorld world) {
         // Switch to find what specific placeholder we want
         switch (placeholder.toLowerCase()) {
             case "alias" -> {
@@ -151,7 +179,22 @@ public boolean persist() {
                 return String.valueOf(world.getSeed());
             }
             case "time" -> {
-                return String.valueOf(world.getBukkitWorld().map(World::getTime).getOrElse(0L));
+                String timeFormat = !placeholderParams.isEmpty() ? placeholderParams.getFirst() : "";
+                long time = world.getBukkitWorld().map(World::getTime).getOrElse(0L);
+                switch (timeFormat) {
+                    case "" -> {
+                        return String.valueOf(time);
+                    }
+                    case "12h" -> {
+                        return MinecraftTimeFormatter.format12h(time);
+                    }
+                    case "24h" -> {
+                        return MinecraftTimeFormatter.format24h(time);
+                    }
+                    default -> {
+                        return MinecraftTimeFormatter.formatTime(time, timeFormat);
+                    }
+                }
             }
             case "type" -> {
                 return world.getBukkitWorld().map(World::getWorldType).map(Enum::name).getOrElse("null");

src/main/java/org/mvplugins/multiverse/core/command/MVCommandCompletions.java

@@ -33,12 +33,15 @@
 
 import org.mvplugins.multiverse.core.anchor.AnchorManager;
 import org.mvplugins.multiverse.core.anchor.MultiverseAnchor;
+import org.mvplugins.multiverse.core.command.context.issueraware.IssuerAwareValue;
+import org.mvplugins.multiverse.core.command.context.issueraware.MultiverseWorldValue;
+import org.mvplugins.multiverse.core.command.context.issueraware.PlayerArrayValue;
 import org.mvplugins.multiverse.core.config.CoreConfig;
 import org.mvplugins.multiverse.core.config.node.functions.DefaultSuggesterProvider;
 import org.mvplugins.multiverse.core.config.handle.PropertyModifyAction;
 import org.mvplugins.multiverse.core.destination.DestinationInstance;
+import org.mvplugins.multiverse.core.destination.DestinationSuggestionPacket;
 import org.mvplugins.multiverse.core.destination.DestinationsProvider;
-import org.mvplugins.multiverse.core.destination.core.WorldDestination;
 import org.mvplugins.multiverse.core.permissions.CorePermissionsChecker;
 import org.mvplugins.multiverse.core.utils.REPatterns;
 import org.mvplugins.multiverse.core.utils.StringFormatter;
@@ -129,6 +132,22 @@ private Collection<String> completeWithPreconditions(
         if (context.hasConfig("playerOnly") && !context.getIssuer().isPlayer()) {
             return Collections.emptyList();
         }
+        if (context.hasConfig("byIssuerForArg")) {
+            Boolean byIssuerForArg = Try.of(() -> context.getContextValueByName(IssuerAwareValue.class, context.getConfig("byIssuerForArg")))
+                    .map(IssuerAwareValue::isByIssuer)
+                    .getOrElse(false);
+            if (!byIssuerForArg) {
+                return Collections.emptyList();
+            }
+        }
+        if (context.hasConfig("notByIssuerForArg")) {
+            Boolean byIssuerForArg = Try.of(() -> context.getContextValueByName(IssuerAwareValue.class, context.getConfig("notByIssuerForArg")))
+                    .map(IssuerAwareValue::isByIssuer)
+                    .getOrElse(false);
+            if (byIssuerForArg) {
+                return Collections.emptyList();
+            }
+        }
         if (context.hasConfig("resolveUntil")) {
             if (!Try.run(() -> context.getContextValueByName(Object.class, context.getConfig("resolveUntil"))).isSuccess()) {
                 return Collections.emptyList();
@@ -195,7 +214,10 @@ private boolean checkPerms(CommandIssuer issuer, RegisteredCommand<?> command) {
     }
 
     private Collection<String> suggestDestinations(BukkitCommandCompletionContext context) {
-        return Try.of(() -> context.getContextValue(Player[].class))
+        return Try.of(() -> context.getContextValue(PlayerArrayValue.class))
+                .map(PlayerArrayValue::value)
+                .recover(IllegalStateException.class, e -> context.getContextValue(Player[].class))
+                .recover(IllegalStateException.class, e -> new Player[]{context.getContextValue(Player.class)})
                 .map(players -> {
                     if (players.length == 0) {
                         // Most likely console did not specify a player
@@ -213,9 +235,7 @@ private Collection<String> suggestDestinationsWithPerms(CommandSender teleporter
         return destinationsProvider.suggestDestinations(teleporter, deststring).stream()
                 .filter(packet -> corePermissionsChecker
                         .checkDestinationPacketPermission(teleporter, Arrays.asList(players), packet))
-                .map(packet -> packet.destination() instanceof WorldDestination
-                                ? packet.destinationString()
-                                : packet.destination().getIdentifier() + ":" + packet.destinationString())
+                .map(DestinationSuggestionPacket::parsableString)
                 .toList();
     }
 
@@ -248,7 +268,7 @@ private Collection<String> suggestGeneratorPlugins(BukkitCommandCompletionContex
     private Collection<String> suggestMVConfigValues(BukkitCommandCompletionContext context) {
         return Try.of(() -> context.getContextValue(String.class))
                 .map(propertyName -> config.getStringPropertyHandle()
-                        .getSuggestedPropertyValue(propertyName, context.getInput(), PropertyModifyAction.SET))
+                        .getSuggestedPropertyValue(propertyName, context.getInput(), PropertyModifyAction.SET, context.getSender()))
                 .getOrElse(Collections.emptyList());
     }
 
@@ -283,18 +303,18 @@ private Collection<String> suggestMVWorlds(BukkitCommandCompletionContext contex
 
     private Collection<String> suggestMVWorldPropsName(BukkitCommandCompletionContext context) {
         return Try.of(() -> {
-            MultiverseWorld world = context.getContextValue(MultiverseWorld.class);
+            MultiverseWorld world = context.getContextValue(MultiverseWorldValue.class).value();
             PropertyModifyAction action = context.getContextValue(PropertyModifyAction.class);
             return world.getStringPropertyHandle().getModifiablePropertyNames(action);
         }).getOrElse(Collections.emptyList());
     }
 
     private Collection<String> suggestMVWorldPropsValue(BukkitCommandCompletionContext context) {
         return Try.of(() -> {
-            MultiverseWorld world = context.getContextValue(MultiverseWorld.class);
+            MultiverseWorld world = context.getContextValue(MultiverseWorldValue.class).value();
             PropertyModifyAction action = context.getContextValue(PropertyModifyAction.class);
             String propertyName = context.getContextValue(String.class);
-            return world.getStringPropertyHandle().getSuggestedPropertyValue(propertyName, context.getInput(), action);
+            return world.getStringPropertyHandle().getSuggestedPropertyValue(propertyName, context.getInput(), action, context.getSender());
         }).getOrElse(Collections.emptyList());
     }
 
@@ -335,7 +355,7 @@ private Collection<String> suggestSpawnCategoryPropsValue(BukkitCommandCompletio
             return world.getEntitySpawnConfig()
                     .getSpawnCategoryConfig(spawnCategory)
                     .getStringPropertyHandle()
-                    .getSuggestedPropertyValue(propertyName, context.getInput(), action);
+                    .getSuggestedPropertyValue(propertyName, context.getInput(), action, context.getSender());
         }).getOrElse(Collections.emptyList());
     }
 }