feat: lock start time to time grid

build.gradle

@@ -9,7 +9,7 @@ java {
 }
 
 group = 'me.playbosswar.com'
-version = '8.16.5'
+version = '8.17.0'
 description = 'CommandTimer'
 
 repositories {
@@ -84,7 +84,7 @@ publishing {
         maven(MavenPublication) {
             groupId = 'me.playbosswar.com'
             artifactId = 'commandtimer'
-            version = '8.16.5'
+            version = '8.17.0'
 
             from components.java
         }

docs/docs/configuration/schedules.md

@@ -31,6 +31,44 @@ When configuring Minecraft time, a world also needs to be selected to use the ti
 
 If you want to know the world time, go to the world you want to check and execute `/cmt time`
 
+## Interval Start Time
+
+By default, interval-based tasks schedule executions relative to when the task was last run. This means the exact execution times can shift depending on when your server started or when the task was activated.
+
+The **Interval Start Time** feature lets you anchor executions to fixed clock times instead. When a start time is configured, executions will always land on a predictable grid.
+
+### How it works
+
+The start time acts as an anchor point. Combined with your interval, it creates a repeating grid of execution times that stays consistent regardless of server restarts.
+
+For example, if you set:
+- **Interval**: 15 minutes
+- **Start Time**: 15:00
+
+Your task will execute at: ..., 14:00, 14:15, 14:30, 14:45, 15:00, 15:15, 15:30, ...
+
+The grid extends across the entire day based on the interval. Even if your server restarts at 14:02, the next execution will still be at 14:15 — not at 14:17.
+
+### Examples
+
+| Interval | Start Time | Executions |
+|----------|-----------|------------|
+| 15 min | 15:00 | 00:00, 00:15, 00:30, ..., 14:45, 15:00, 15:15, ... |
+| 2 hours | 13:00 | 01:00, 03:00, 05:00, 07:00, 09:00, 11:00, 13:00, ... |
+| 30 min | 10:15 | 00:15, 00:45, 01:15, ..., 10:15, 10:45, 11:15, ... |
+
+### Configuring
+
+In the task scheduler menu, click the **Interval Start Time** item (compass icon). From there you can set the hours, minutes, and seconds for the anchor time. Use the **Clear** button to remove the start time and go back to the default behavior.
+
+:::tip
+This is especially useful for tasks that need to run at predictable clock-aligned times, such as hourly announcements or scheduled restarts.
+:::
+
+:::note
+The start time only affects interval-based scheduling. If your task uses [fixed times](#fixed-times), those already execute at exact clock times and don't need a start time anchor.
+:::
+
 ## Days
 
 In the days menu, you can select on which days the [task](../jargon#task) will be executed. By default all the days are selected.

java17-build.gradle

@@ -10,7 +10,7 @@ java {
 
 
 group = 'me.playbosswar.com'
-version = '8.16.5'
+version = '8.17.0'
 description = 'CommandTimer'
 
 repositories {
@@ -63,7 +63,7 @@ publishing {
         maven(MavenPublication) {
             groupId = 'me.playbosswar.com'
             artifactId = 'commandtimer-java17'
-            version = '8.16.5'
+            version = '8.17.0'
 
             from components.java
         }

java21-build.gradle

@@ -10,7 +10,7 @@ java {
 
 
 group = 'me.playbosswar.com'
-version = '8.16.5'
+version = '8.17.0'
 description = 'CommandTimer'
 
 repositories {
@@ -67,7 +67,7 @@ publishing {
         maven(MavenPublication) {
             groupId = 'me.playbosswar.com'
             artifactId = 'commandtimer-java21'
-            version = '8.16.5'
+            version = '8.17.0'
             from components.java
         }
     }

src/main/java/me/playbosswar/com/gui/tasks/scheduler/EditIntervalStartTimeMenu.java

@@ -0,0 +1,138 @@
+package me.playbosswar.com.gui.tasks.scheduler;
+
+import com.cryptomorin.xseries.XMaterial;
+import fr.minuskube.inv.ClickableItem;
+import fr.minuskube.inv.SmartInventory;
+import fr.minuskube.inv.content.InventoryContents;
+import fr.minuskube.inv.content.InventoryProvider;
+import me.playbosswar.com.CommandTimerPlugin;
+import me.playbosswar.com.gui.tasks.general.ClickableTextInputButton;
+import me.playbosswar.com.language.LanguageKey;
+import me.playbosswar.com.language.LanguageManager;
+import me.playbosswar.com.tasks.Task;
+import me.playbosswar.com.utils.Items;
+import org.bukkit.entity.Player;
+import org.bukkit.inventory.ItemStack;
+
+import java.time.LocalTime;
+
+public class EditIntervalStartTimeMenu implements InventoryProvider {
+    public final SmartInventory INVENTORY;
+    private final LanguageManager languageManager = CommandTimerPlugin.getLanguageManager();
+    private final Task task;
+    private final String[] clockLore = {"", languageManager.get(LanguageKey.LEFT_CLICK_EDIT)};
+
+    public EditIntervalStartTimeMenu(Task task) {
+        this.task = task;
+        INVENTORY = SmartInventory.builder()
+                .id("task-interval-start-time")
+                .provider(this)
+                .manager(CommandTimerPlugin.getInstance().getInventoryManager())
+                .size(5, 9)
+                .title(languageManager.get(LanguageKey.INTERVAL_START_TIME_GUI_TITLE))
+                .build();
+    }
+
+    @Override
+    public void init(Player player, InventoryContents contents) {
+        contents.fill(ClickableItem.empty(XMaterial.BLUE_STAINED_GLASS_PANE.parseItem()));
+
+        LocalTime current = task.getIntervalStartTime();
+        int hours = current != null ? current.getHour() : 0;
+        int minutes = current != null ? current.getMinute() : 0;
+        int seconds = current != null ? current.getSecond() : 0;
+
+        // Hours
+        contents.set(1, 1, ClickableItem.of(Items.getAddItem(), e -> {
+            LocalTime t = task.getIntervalStartTime() != null ? task.getIntervalStartTime() : LocalTime.MIDNIGHT;
+            task.setIntervalStartTime(t.withHour((t.getHour() + 1) % 24));
+            refresh(player);
+        }));
+        ClickableTextInputButton hoursClock = new ClickableTextInputButton(
+                Items.generateItem(languageManager.get(LanguageKey.HOURS_LABEL, String.valueOf(hours)),
+                        XMaterial.CLOCK, clockLore),
+                LanguageKey.TEXT_INPUT_DEFAULT,
+                data -> {
+                    int h = Integer.parseInt(data);
+                    LocalTime t = task.getIntervalStartTime() != null ? task.getIntervalStartTime() : LocalTime.MIDNIGHT;
+                    task.setIntervalStartTime(t.withHour(h % 24));
+                    refresh(player);
+                }
+        );
+        contents.set(2, 1, hoursClock.getItem());
+        contents.set(3, 1, ClickableItem.of(Items.getSubstractItem(), e -> {
+            LocalTime t = task.getIntervalStartTime() != null ? task.getIntervalStartTime() : LocalTime.MIDNIGHT;
+            task.setIntervalStartTime(t.withHour((t.getHour() + 23) % 24));
+            refresh(player);
+        }));
+
+        // Minutes
+        contents.set(1, 3, ClickableItem.of(Items.getAddItem(), e -> {
+            LocalTime t = task.getIntervalStartTime() != null ? task.getIntervalStartTime() : LocalTime.MIDNIGHT;
+            task.setIntervalStartTime(t.withMinute((t.getMinute() + 1) % 60));
+            refresh(player);
+        }));
+        ClickableTextInputButton minutesClock = new ClickableTextInputButton(
+                Items.generateItem(languageManager.get(LanguageKey.MINUTES_LABEL, String.valueOf(minutes)),
+                        XMaterial.CLOCK, clockLore),
+                LanguageKey.TEXT_INPUT_DEFAULT,
+                data -> {
+                    int m = Integer.parseInt(data);
+                    LocalTime t = task.getIntervalStartTime() != null ? task.getIntervalStartTime() : LocalTime.MIDNIGHT;
+                    task.setIntervalStartTime(t.withMinute(m % 60));
+                    refresh(player);
+                }
+        );
+        contents.set(2, 3, minutesClock.getItem());
+        contents.set(3, 3, ClickableItem.of(Items.getSubstractItem(), e -> {
+            LocalTime t = task.getIntervalStartTime() != null ? task.getIntervalStartTime() : LocalTime.MIDNIGHT;
+            task.setIntervalStartTime(t.withMinute((t.getMinute() + 59) % 60));
+            refresh(player);
+        }));
+
+        // Seconds
+        contents.set(1, 5, ClickableItem.of(Items.getAddItem(), e -> {
+            LocalTime t = task.getIntervalStartTime() != null ? task.getIntervalStartTime() : LocalTime.MIDNIGHT;
+            task.setIntervalStartTime(t.withSecond((t.getSecond() + 1) % 60));
+            refresh(player);
+        }));
+        ClickableTextInputButton secondsClock = new ClickableTextInputButton(
+                Items.generateItem(languageManager.get(LanguageKey.SECONDS_LABEL, String.valueOf(seconds)),
+                        XMaterial.CLOCK, clockLore),
+                LanguageKey.TEXT_INPUT_DEFAULT,
+                data -> {
+                    int s = Integer.parseInt(data);
+                    LocalTime t = task.getIntervalStartTime() != null ? task.getIntervalStartTime() : LocalTime.MIDNIGHT;
+                    task.setIntervalStartTime(t.withSecond(s % 60));
+                    refresh(player);
+                }
+        );
+        contents.set(2, 5, secondsClock.getItem());
+        contents.set(3, 5, ClickableItem.of(Items.getSubstractItem(), e -> {
+            LocalTime t = task.getIntervalStartTime() != null ? task.getIntervalStartTime() : LocalTime.MIDNIGHT;
+            task.setIntervalStartTime(t.withSecond((t.getSecond() + 59) % 60));
+            refresh(player);
+        }));
+
+        // Clear button
+        ItemStack clearItem = Items.generateItem(
+                languageManager.get(LanguageKey.INTERVAL_START_TIME_CLEAR),
+                XMaterial.BARRIER);
+        contents.set(4, 0, ClickableItem.of(clearItem, e -> {
+            task.setIntervalStartTime(null);
+            refresh(player);
+        }));
+
+        // Back button
+        contents.set(4, 8, ClickableItem.of(Items.getBackItem(),
+                e -> new MainScheduleMenu(task).INVENTORY.open(player)));
+    }
+
+    @Override
+    public void update(Player player, InventoryContents contents) {
+    }
+
+    private void refresh(Player player) {
+        this.INVENTORY.open(player);
+    }
+}

src/main/java/me/playbosswar/com/gui/tasks/scheduler/MainScheduleMenu.java

@@ -14,8 +14,9 @@
 import org.bukkit.entity.Player;
 import org.bukkit.inventory.ItemStack;
 
+import java.time.LocalTime;
+import java.time.format.DateTimeFormatter;
 import java.util.ArrayList;
-import java.util.List;
 
 public class MainScheduleMenu implements InventoryProvider {
     public SmartInventory INVENTORY;
@@ -63,6 +64,17 @@ public void init(Player player, InventoryContents contents) {
                 e -> new EditDaysMenu(task).INVENTORY.open(player));
         contents.set(1, 3, clickableDaysItem);
 
+        LocalTime startTime = task.getIntervalStartTime();
+        String startTimeDisplay = startTime != null
+                ? startTime.format(DateTimeFormatter.ofPattern("HH:mm:ss"))
+                : languageManager.get(LanguageKey.NOT_SET);
+        ArrayList<String> startTimeLore = languageManager.getList(LanguageKey.INTERVAL_START_TIME_LORE, startTimeDisplay);
+        ItemStack startTimeItem = Items.generateItem(LanguageKey.INTERVAL_START_TIME_TITLE, XMaterial.COMPASS,
+                startTimeLore.toArray(new String[]{}));
+        ClickableItem clickableStartTimeItem = ClickableItem.of(startTimeItem,
+                e -> new EditIntervalStartTimeMenu(task).INVENTORY.open(player));
+        contents.set(1, 4, clickableStartTimeItem);
+
         contents.set(2, 8, ClickableItem.of(Items.getBackItem(), e -> new EditTaskMenu(task).INVENTORY.open(player)));
     }
 

src/main/java/me/playbosswar/com/language/LanguageKey.java

@@ -165,7 +165,11 @@ public enum LanguageKey {
     FILTER_BUTTON_CURRENT,
     FILTER_ALL,
     FILTER_TASKS_ONLY,
-    FILTER_ADHOC_ONLY;
+    FILTER_ADHOC_ONLY,
+    INTERVAL_START_TIME_TITLE,
+    INTERVAL_START_TIME_LORE,
+    INTERVAL_START_TIME_GUI_TITLE,
+    INTERVAL_START_TIME_CLEAR;
 
     public static LanguageKey getByTag(String tag) {
         return Arrays.stream(values()).filter(value -> value.toString().equals(tag.toUpperCase())).findFirst()

src/main/java/me/playbosswar/com/tasks/Task.java

@@ -24,6 +24,7 @@
 import java.io.IOException;
 import java.sql.SQLException;
 import java.time.DayOfWeek;
+import java.time.LocalTime;
 import java.util.*;
 import java.util.stream.Collectors;
 
@@ -60,6 +61,8 @@ public class Task {
     private Condition condition;
     @DatabaseField(persisterClass = EventConfigurationPersistor.class)
     private Collection<EventConfiguration> events = new ArrayList<>();
+    @DatabaseField(persisterClass = LocalTimePersistor.class)
+    private LocalTime intervalStartTime = null;
 
     Task() {
         // all persisted classes must define a no-arg constructor with at least package visibility
@@ -306,6 +309,16 @@ public void setEvents(List<EventConfiguration> events) {
         this.events = events;
     }
 
+    public LocalTime getIntervalStartTime() {
+        return intervalStartTime;
+    }
+
+    public void setIntervalStartTime(LocalTime intervalStartTime) {
+        this.intervalStartTime = intervalStartTime;
+        storeInstance();
+        CommandTimerPlugin.getInstance().getTasksManager().resetScheduleForTask(this);
+    }
+
     public boolean hasCondition() {
         if(this.condition == null) {
             return false;