feat: new scheduling engine

Author: titivermeesch

build.gradle

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

docs/docs/configuration/adhoc-commands.md

@@ -0,0 +1,139 @@
+---
+sidebar_position: 3
+---
+
+# Ad-Hoc Commands
+
+Ad-hoc commands allow you to schedule one-time command executions at a specific time in the future without creating a full [task](../jargon#task). This is perfect for temporary commands, delayed actions, or one-off scheduled executions.
+
+## Overview
+
+Ad-hoc commands are single-use scheduled commands that execute once at a specified time. Unlike regular tasks, they don't have intervals, conditions, or multiple commands - they're designed for simple, one-time executions.
+
+### Key Features
+
+- **One-time execution**: Commands execute once at the scheduled time
+- **Flexible scheduling**: Schedule commands to run at any future time
+- **All gender types supported**: Use any [gender](commands.md#genders) for command execution
+- **Persistent storage**: Commands are saved to disk and survive server restarts
+- **GUI management**: View and manage scheduled ad-hoc commands through the GUI
+
+## Command Syntax
+
+Schedule an ad-hoc command using the `/cmt schedule` command:
+
+```
+/cmt schedule [-after <time>] [-gender <gender>] <command>
+```
+
+### Parameters
+
+- **`-after <time>`** (optional): Delay before execution. Format: `1h10m5s` (hours, minutes, seconds)
+  - Examples: `30s`, `5m`, `1h30m`, `2h15m30s`
+  
+- **`-gender <gender>`** (optional): The [gender](commands.md#genders) to use for execution
+  - Valid options: `CONSOLE`, `PLAYER`, `OPERATOR`, `CONSOLE_PER_USER`, `CONSOLE_PER_USER_OFFLINE`, `CONSOLE_PROXY`
+  - Default: `CONSOLE`
+  
+- **`<command>`** (required): The command to execute (without the leading `/`)
+
+### Examples
+
+#### Basic Examples
+
+```bash
+# Schedule a broadcast message in 5 minutes
+/cmt schedule -after 5m say Server maintenance in 5 minutes!
+
+# Schedule a command to run in 1 hour
+/cmt schedule -after 1h weather clear
+
+# Schedule a command to run in 2 hours, 15 minutes, and 30 seconds
+/cmt schedule -after 2h15m30s time set day
+```
+
+#### Using Different Genders
+
+```bash
+# Execute as console (default)
+/cmt schedule -after 10m say Announcement
+
+# Execute for each online player
+/cmt schedule -after 30m -gender CONSOLE_PER_USER give %player_name% diamond 1
+
+# Execute as if each player is OP
+/cmt schedule -after 1h -gender OPERATOR gamemode creative %player_name%
+
+# Execute for each player (respects permissions)
+/cmt schedule -after 2h -gender PLAYER home
+```
+
+#### Real-World Use Cases
+
+```bash
+# Schedule a server restart announcement
+/cmt schedule -after 30m say Server restarting in 30 minutes!
+/cmt schedule -after 15m say Server restarting in 15 minutes!
+/cmt schedule -after 5m say Server restarting in 5 minutes!
+/cmt schedule -after 1m say Server restarting in 1 minute!
+
+# Schedule a timed event start
+/cmt schedule -after 1h -gender CONSOLE_PER_USER title %player_name% title {"text":"Event Starting!"}
+
+# Schedule maintenance commands
+/cmt schedule -after 2h save-all
+/cmt schedule -after 2h5m say Maintenance complete!
+
+# Schedule player rewards
+/cmt schedule -after 24h -gender CONSOLE_PER_USER give %player_name% emerald 10
+```
+
+## Managing Ad-Hoc Commands
+
+### GUI Management
+
+You can view and manage ad-hoc commands through the **Scheduled Executions** menu:
+
+1. Open the main menu: `/cmt`
+2. Click on **Scheduled Executions**
+3. Use the filter button to show only ad-hoc commands (filter: "Ad-Hoc Only")
+4. Right-click on an ad-hoc command to cancel it
+
+## Differences from Regular Tasks
+
+| Feature | Ad-Hoc Commands | Regular Tasks |
+|----------|----------------|---------------|
+| **Execution** | One-time only | Recurring or event-based |
+| **Commands** | Single command | Multiple commands |
+| **Intervals** | Not supported | Supported |
+| **Conditions** | Not supported | Supported |
+| **Events** | Not supported | Supported |
+| **Execution Modes** | Not applicable | ALL, ORDERED, RANDOM, INTERVAL |
+| **Use Case** | Temporary, one-off commands | Permanent, recurring automation |
+
+## Permissions
+
+- **`commandtimer.schedule`**: Required to schedule ad-hoc commands
+- **`commandtimer.manage`**: Required to view the GUI and manage commands
+
+## Troubleshooting
+
+### Command Not Executing
+
+- Check that the scheduled time has passed
+- Verify the command syntax is correct
+- Check server logs for execution errors
+- Ensure the ad-hoc command runner is active (should start automatically)
+
+### Command Executing Too Early/Late
+
+- Commands execute within 0.5 seconds of their scheduled time
+- Server lag may cause slight delays
+- For precise timing, schedule commands slightly earlier than needed
+
+### Commands Lost After Restart
+
+- Commands are saved to disk and should persist
+- Check that the scheduled time hasn't passed yet
+- Only non-executed commands are loaded on startup
+

docs/docs/configuration/conditions.md

@@ -14,11 +14,11 @@ Conditions can have one of the following types:
 - `AND`: Creates a group of conditions. Each of these conditions needs to be true to execute your [task](../jargon#task).
 - `OR`: Creates a group of conditions. One of these conditions needs to be true to execute your [task](../jargon#task). Even if you have 50 conditions that do not match but one does, the [task](../jargon#task) will still go through
 
-When using `AND` and `OR`, more conditions can be nested. Nesting does not have a depth limit, meaning you could have an `AND` condition in an `OR` condition in an `OR` condition in an `AND` condition which itself contains 4 different `SIMPLE` and `NOT` conditions. It is good to draw a visual map yourself before doing these nested conditions, because it can be cumberstone to debug in case there is an issue.
+When using `AND` and `OR`, more conditions can be nested. Nesting does not have a depth limit, meaning you could have an `AND` condition in an `OR` condition in an `OR` condition in an `AND` condition which itself contains 4 different `SIMPLE` and `NOT` conditions. It is good to draw a visual map yourself before doing these nested conditions, because it can be cumbersome to debug in case there is an issue.
 
 ## Available conditions
 
-Conditions are made availabel through [extensions](../extensions). This means that CommandTimer by default will not have any conditions, making the whole conditions engine useless if no [extensions](../extensions) are installed.
+Conditions are made available through [extensions](../extensions). This means that CommandTimer by default will not have any conditions, making the whole conditions engine useless if no [extensions](../extensions) are installed.
 
 ## Condition values
 

docs/docs/configuration/index.md

@@ -6,5 +6,6 @@ sidebar_position: 2
 
 - [Commands](commands.md)
 - [Schedules and Intervals](schedules.md)
+- [Ad-Hoc Commands](adhoc-commands.md)
 - [Conditions](conditions.md)
 - [Others](others.md)

docs/docs/developers/index.md

@@ -23,7 +23,6 @@ dependencies {
 ### Maven
 
 ```xml
-
 <repositories>
     <repository>
         <id>jitpack.io</id>
@@ -33,7 +32,6 @@ dependencies {
 ```
 
 ```xml
-
 <dependency>
     <groupId>com.github.titivermeesch</groupId>
     <artifactId>CommandTimer</artifactId>
@@ -50,5 +48,4 @@ functionalities are not available there, the internal CommandTimer API can be us
 
 ## Contributing
 
-Did you found a bug or want to do a general improvement on the plugin or the documentation itself? Feel free to open a
-PR!
+Did you find a bug or want to make a general improvement to the plugin or the documentation? Feel free to open a PR!

docs/docs/extensions/index.md

@@ -19,7 +19,7 @@ Once the jar file is in that folder, you should see the extension in different m
 Here is a list of extensions that can be installed. Official extensions are made by the team behind CommandTimer, while
 community extensions, as the name says, are made by the community.
 
-### Oficial extensions
+### Official extensions
 
 - [Time Extension](https://www.spigotmc.org/resources/time-conditions-commandtimer-extension.105591/)
 - [Player Extension](https://www.spigotmc.org/resources/player-conditions-commandtimer-extension.97186/)

docs/docs/faq.md

@@ -5,7 +5,7 @@ sidebar_position: 8
 
 ## Can I execute a task on restart only
 
-Yes, by using [execution limits](configuration/others#Execution-limits).
+Yes, by using [execution limits](configuration/others#execution-limits).
 
 1. Set the execution limit to 1
 2. Activate the feature "reset execution after restart"

docs/docs/intro.md

@@ -25,23 +25,25 @@ Clicking the paper will create a fresh task for you.
 | `/cmt activate <task>`   | Enable the specified task                                                                         | `commandtimer.activate` or `commandtimer.toggle`    |
 | `/cmt deactivate <task>` | Disable the specified task                                                                        | `commandtimer.deactivate`  or `commandtimer.toggle` |
 | `/cmt execute <task>`    | Instantly execute the specified task                                                              | `commandtimer.execute`                              |
+| `/cmt schedule`          | Schedule a one-time [ad-hoc command](configuration/adhoc-commands)                                | `commandtimer.schedule`                             |
 | `/cmt reload`            | Reload the plugin. Extensions will not be reloaded. **It is not recommended to use this command** | `commandtimer.manage`                               |
 
 ## Configuration file
 
 The global configuration file allows you to change the global behaviour of CommandTimer:
 
-- `timeonload`: Show the current server time in the console when the plugin loads
-- `debug`: Enable debug mode. This will print additional information to the console
-- `showUpdateMessage`: Show a message in the chat when a plugin update is available
-- `timezoneOverwrite`: Overwrite the timezone of the server (**This feature does not work right now**)
-- `timezoneOverwriteValue`: The timezone to overwrite the server timezone with (**This feature does not work right now**)
-- `language`: The language to use for the plugin. You can add more languages under the `languages` folder
-- `disablePapiPlaceholderWarnings`: Disable the warning message that appears when a PAPI placeholder is not used correctly
+| Option                          | Description                                                                                 |
+|---------------------------------|---------------------------------------------------------------------------------------------|
+| `timeonload`                    | Show the current server time in the console when the plugin loads                           |
+| `debug`                         | Enable debug mode. This will print additional information to the console                    |
+| `showUpdateMessage`             | Show a message in the chat when a plugin update is available                                |
+| `timezoneOverwrite`             | Overwrite the timezone of the server (**Not working currently**)                            |
+| `timezoneOverwriteValue`        | The timezone to overwrite the server timezone with (**Not working currently**)              |
+| `language`                      | The language to use for the plugin. You can add more languages under the `languages` folder |
+| `disablePapiPlaceholderWarnings`| Disable the warning message that appears when a PAPI placeholder is not used correctly      |
 
+## Other Languages
 
-# Other languages
-
-Here is a list of community maintained translations. These are not guaranteed to always be up to date
+Here is a list of community maintained translations. These are not guaranteed to always be up to date.
 
 - Chinese: https://snowcutieowo.github.io/CommandTimer/#/

docs/docs/jargon.md

@@ -1,12 +1,25 @@
 ---
-sidebar_position: 8
+sidebar_position: 10
 ---
+
 # Jargon
 
-The jargon is a collection of names and definitions specificly targetting a certain group or topic, in this case CommandTimer.
+The jargon is a collection of names and definitions specifically targeting a certain group or topic, in this case CommandTimer.
 
-You don't necessarily need to read this; other documentation pages will directly reference to this page.
+You don't necessarily need to read this; other documentation pages will directly reference this page.
 
 ## Task
 
-A task is a group of commands linked to a group of rules and conditions. Usually a task groups together commands that are all related to each-other, or execute different things to achieve a common goal.
+A task is a group of commands linked to a group of rules and conditions. Usually a task groups together commands that are all related to each other, or execute different things to achieve a common goal.
+
+## Gender
+
+A gender defines how and for whom a command is executed. See [Genders](configuration/commands#genders) for all available options.
+
+## Interval
+
+An interval is a duration that defines how often a task should be executed. See [Intervals](configuration/schedules#intervals) for more details.
+
+## Condition
+
+A condition is a rule that must be met before a task can execute. Conditions are provided by [extensions](extensions).

docs/docs/jsonschema.md

@@ -104,7 +104,31 @@ Documentation about the Events Engine can be found [here](events)
 |-------------|------------------------------------------------------|-------------------------------------------------------------------------------------|
 | `fieldName` | Name of the parameter                                | `string`                                                                            |
 | `value`     | Given value for the configured parameter             | `any`                                                                               |
-| `compare`   | Compare value between event value and passed `value` | `EQUAL`, `GREATER_THAN`, `LESS_THAN`, `GREATER_OR_EQUAL_THAN`, `LESS_OR_EQUAL_THEN` |
+| `compare`   | Compare value between event value and passed `value` | `EQUAL`, `GREATER_THAN`, `LESS_THAN`, `GREATER_OR_EQUAL_THAN`, `LESS_OR_EQUAL_THAN` |
+
+## Ad-Hoc Command
+
+Ad-hoc commands are stored in `plugins/CommandTimer/ad-hoc-commands/` as individual JSON files. See [Ad-Hoc Commands](configuration/adhoc-commands) for more information.
+
+| Field           | Description                                                      | Type                                     |
+|-----------------|------------------------------------------------------------------|------------------------------------------|
+| `id`            | Unique identifier for the ad-hoc command. **Do not update manually** | `UUID`                                   |
+| `command`       | Command to execute. Do not include `/` in front of the command   | `string`                                 |
+| `gender`        | Gender of the command                                            | [Gender](configuration/commands#genders) |
+| `scheduledTime` | The date and time when the command should be executed            | `ISO-8601 DateTime`                      |
+| `executed`      | Whether the command has been executed. **Do not update manually** | `boolean`                                |
+
+### Ad-Hoc Command example
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "command": "say Server maintenance in 5 minutes!",
+  "gender": "CONSOLE",
+  "scheduledTime": "2025-12-07T15:30:00+01:00",
+  "executed": false
+}
+```
 
 ## Example