Skip to content

Add complete Folia support #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
OPmasterLEO wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add complete Folia support #40

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fb6a5eb
Add platform detection and scheduler abstraction for Folia support
OPmasterLEO Jan 7, 2026
827f0c3
Update Maven compiler and plugin versions
OPmasterLEO Jan 7, 2026
9a28246
Improve Folia scheduler error handling and docs
OPmasterLEO Jan 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion 1_17_R1/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>16</source>
<target>16</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_18_R1/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>17</source>
<target>17</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_18_R2/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>17</source>
<target>17</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_19_R1/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>17</source>
<target>17</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_19_R2/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>17</source>
<target>17</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_19_R3/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>17</source>
<target>17</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_20_R1/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>17</source>
<target>17</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_20_R2/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>17</source>
<target>17</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_20_R3/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>17</source>
<target>17</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_20_R4/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand Down
13 changes: 9 additions & 4 deletions 1_21_R1/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,8 @@

<dependencies>
<dependency>
<groupId>org.spigotmc</groupId>
<artifactId>spigot</artifactId>
<groupId>io.papermc.paper</groupId>
<artifactId>paper-api</artifactId>
<version>1.21.1-R0.1-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
Expand All @@ -29,13 +29,18 @@
<scope>provided</scope>
</dependency>
</dependencies>

<repositories>
<repository>
<id>papermc</id>
<url>https://repo.papermc.io/repository/maven-public/</url>
</repository>
</repositories>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_21_R2/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_21_R3/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_21_R4/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand Down
2 changes: 1 addition & 1 deletion 1_21_R5/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand Down
4 changes: 2 additions & 2 deletions Mojang1_20_R4/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,8 +52,8 @@
<plugin>
<groupId>ca.bkaw</groupId>
<artifactId>paper-nms-maven-plugin</artifactId>
<version>1.4.7</version>
<version>1.4.10</version>
</plugin>
</plugins>
</build>
</project>
</project>
4 changes: 2 additions & 2 deletions Mojang1_21_R1/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand All @@ -52,7 +52,7 @@
<plugin>
<groupId>ca.bkaw</groupId>
<artifactId>paper-nms-maven-plugin</artifactId>
<version>1.4.7</version>
<version>1.4.10</version>
</plugin>
</plugins>
</build>
Expand Down
4 changes: 2 additions & 2 deletions Mojang1_21_R2/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand All @@ -52,7 +52,7 @@
<plugin>
<groupId>ca.bkaw</groupId>
<artifactId>paper-nms-maven-plugin</artifactId>
<version>1.4.7</version>
<version>1.4.10</version>
</plugin>
</plugins>
</build>
Expand Down
4 changes: 2 additions & 2 deletions Mojang1_21_R3/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand All @@ -52,7 +52,7 @@
<plugin>
<groupId>ca.bkaw</groupId>
<artifactId>paper-nms-maven-plugin</artifactId>
<version>1.4.7</version>
<version>1.4.10</version>
</plugin>
</plugins>
</build>
Expand Down
4 changes: 2 additions & 2 deletions Mojang1_21_R4/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand All @@ -52,7 +52,7 @@
<plugin>
<groupId>ca.bkaw</groupId>
<artifactId>paper-nms-maven-plugin</artifactId>
<version>1.4.7</version>
<version>1.4.10</version>
</plugin>
</plugins>
</build>
Expand Down
4 changes: 2 additions & 2 deletions Mojang1_21_R5/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.8.1</version>
<version>3.14.1</version>
<configuration>
<source>21</source>
<target>21</target>
Expand All @@ -52,7 +52,7 @@
<plugin>
<groupId>ca.bkaw</groupId>
<artifactId>paper-nms-maven-plugin</artifactId>
<version>1.4.7</version>
<version>1.4.10</version>
</plugin>
</plugins>
</build>
Expand Down
14 changes: 14 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,14 @@ An api to get input text via a sign in Minecraft.
The api supports the Minecraft versions from `1.8` to `1.21`.
Also supports adventure text and mojang-mapped Paper plugins (1.20.5+).

## ✨ Full Platform Support
- ✅ **Bukkit / Spigot / Paper** - Full support
- ✅ **Folia** - Complete regionized multithreading support
- ✅ **CanvasMC** - Full support
- ✅ **Archlight** - Full support (Forge+Bukkit hybrid)

SignGUI automatically detects your server platform and uses the appropriate scheduler for thread-safe operation!

## Integration

Maven dependency:
Expand Down Expand Up @@ -120,6 +128,10 @@ try {
return Collections.emptyList();
})

// RECOMMENDED: Call handler synchronously for thread safety
// REQUIRED for Folia; RECOMMENDED for CanvasMC, Archlight, and other platforms
.callHandlerSynchronously(this) // "this" = your JavaPlugin instance

// build the SignGUI
.build();

Expand All @@ -135,6 +147,8 @@ try {

You don't have to call all methods. Only `setHandler` is mandatory.

**Important:** `callHandlerSynchronously(plugin)` is **REQUIRED for Folia** and **RECOMMENDED for all other platforms for thread safety**. On Folia, this ensures tasks run on the correct region thread. On other platforms, it ensures tasks run on the main thread.

By default, the handler is called by an asynchronous thread. You can change that behaviour by calling the method `callHandlerSynchronously` of the builder.
Comment on lines +150 to 152
Copy link

Copilot AI Jan 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation on line 150 states that callHandlerSynchronously is "REQUIRED for Folia", but line 152 says "By default, the handler is called by an asynchronous thread." This creates a contradiction: if it's required for Folia, then Folia users won't have working code by default.

Consider clarifying this by either: 1) Making callHandlerSynchronously the default behavior (to avoid breaking Folia), 2) Adding a note that without calling this method, the plugin will not work correctly on Folia, or 3) Automatically detecting Folia and forcing synchronous execution internally.

Suggested change
**Important:** `callHandlerSynchronously(plugin)` is **REQUIRED for Folia** and **RECOMMENDED for all other platforms for thread safety**. On Folia, this ensures tasks run on the correct region thread. On other platforms, it ensures tasks run on the main thread.
By default, the handler is called by an asynchronous thread. You can change that behaviour by calling the method `callHandlerSynchronously` of the builder.
**Important:** On **Folia**, SignGUI automatically runs the handler synchronously on the correct region thread. On other platforms, calling `callHandlerSynchronously(plugin)` is **RECOMMENDED** for thread safety, as it ensures tasks run on the main server thread.
By default on **non-Folia** platforms, the handler is called by an asynchronous thread. You can change that behaviour by calling the method `callHandlerSynchronously` of the builder.

Copilot uses AI. Check for mistakes.
An explanation for the different methods can be found on the [Javadoc](https://javadoc.io/doc/de.rapha149.signgui/signgui).

Expand Down
6 changes: 6 additions & 0 deletions api/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,12 @@
<version>1.8-R0.1-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>dev.folia</groupId>
<artifactId>folia-api</artifactId>
<version>1.21.11-R0.1-SNAPSHOT</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>de.rapha149.signgui</groupId>
<artifactId>signgui-wrapper</artifactId>
Expand Down
9 changes: 6 additions & 3 deletions api/src/main/java/de/rapha149/signgui/SignGUI.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
import de.rapha149.signgui.SignGUIAction.SignGUIActionInfo;
import de.rapha149.signgui.exception.SignGUIException;
import de.rapha149.signgui.exception.SignGUIVersionException;
import de.rapha149.signgui.util.scheduler.SchedulerFactory;
import de.rapha149.signgui.version.VersionMatcher;
import org.apache.commons.lang.Validate;
import org.bukkit.Bukkit;
Expand Down Expand Up @@ -107,10 +108,12 @@ public void open(Player player) throws SignGUIException {
action.execute(this, signEditor, player);
};

if (callHandlerSynchronously)
Bukkit.getScheduler().runTask(plugin, runnable);
else
if (callHandlerSynchronously) {
// Use platform-aware scheduler that works on Folia, CanvasMC, Archlight, and Bukkit
SchedulerFactory.getScheduler().runTask(plugin, player, runnable);
} else {
runnable.run();
}
});
} catch (Exception e) {
throw new SignGUIException("Failed to open sign gui", e);
Expand Down
5 changes: 4 additions & 1 deletion api/src/main/java/de/rapha149/signgui/SignGUIBuilder.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,10 @@ public SignGUIBuilder setHandler(SignGUIFinishHandler handler) {
}

/**
* If called the handler will be called synchronously by calling the method {@link org.bukkit.scheduler.BukkitScheduler#runTask(Plugin, Runnable)}
* If called the handler will be called synchronously by using the appropriate scheduler.
* This is required for Folia, CanvasMC, and Archlight support and ensures thread-safe execution.
* On Folia, tasks are scheduled via the player's entity scheduler (on the thread owning the player's region).
* On Bukkit/Spigot/Paper, tasks are scheduled on the main thread.
*
* @param plugin Your {@link org.bukkit.plugin.java.JavaPlugin} instance.
* @return The {@link SignGUIBuilder} instance
Expand Down
Loading