Skip to content

Commit 3e02aec

Browse files
TechnicallyCodedTechnicallyCoded
authored
Update README.md (#19) (API Update, Examples, Maven Repo)
* Update README.md * Update warnings, gradle configuration, maven configuration, use jitpack, and update affiliation disclaimer * Update api examples * Add examples of newly supported features & better documentation
1 parent ca4dc4b commit 3e02aec

1 file changed

Lines changed: 128 additions & 41 deletions

File tree

‎README.md‎

Lines changed: 128 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,114 @@
1-
# FoliaLib
2-
[![GitHub Release](https://img.shields.io/github/release/technicallycoded/FoliaLib.svg?style=flat)]()
1+
# FoliaLib     [![GitHub Release](https://img.shields.io/github/release/technicallycoded/FoliaLib.svg?style=flat)]()
32

4-
Disclaimer:
5-
This project is not directly affiliated with Paper team or the Folia project.
3+
Developers and contributors like you make this project possible. This project is not directly affiliated with PaperMC.
4+
5+
<br/>
66

77
## Description
8-
This is a wrapper library for aiding in supporting the Folia Paper Fork. This library adds multiple scheduler options to use instead of the Bukkit or Folia native schedulers. Developers are expected to depend on this library and relocate the package to their own to prevent conflicts with other plugins.
8+
This project is a wrapper library that aids developers in supporting the "Folia" Paper fork while not breaking support for Spigot or Paper. This library adds multiple scheduler options to use instead of the Bukkit or Folia native schedulers. Developers are expected to depend on this library and relocate the package to their own to prevent conflicts with other plugins.
9+
10+
**Version support**:
11+
FoliaLib attempts to be compatible with all your projects no matter how outdated the minecraft version. As of writing, FoliaLib should work in any plugin supporting 1.8.8 to 1.21+. However, we *heavily* warn against using anything below 1.13.2 since this version adds support for many features FoliaLib depends on. Workarounds are used for supporting older versions.
12+
13+
**API Note**:
14+
This project is still in its early stages and may make frequent breaking changes to the API. Additionally, I won't claim that this library is perfect; If you find any issues, please report them on the [issues page](https://github.com/TechnicallyCoded/FoliaLib/issues)
15+
16+
<br/>
17+
18+
## FoliaLib as a dependency
19+
20+
> [!WARNING]
21+
> You are expected to relocate the package `com.tcoded.folialib` to prevent conflicts with other plugins!
22+
> Example configuration snippets demonstrating how to do this are available below for Maven and Gradle.
23+
24+
> [!WARNING]
25+
> Ensure that you exclude FoliaLib from any `minimize` operation.
26+
27+
### Gradle Dependency
28+
<details>
29+
<summary>[Click to show Gradle example configurations]</summary>
30+
31+
```groovy
32+
plugins {
33+
id 'com.github.johnrengelman.shadow' version '8.1.1' // For up to Java 17
34+
// id 'io.github.goooler.shadow' version '8.1.7' // Uncomment for Java 21 or higher
35+
}
36+
37+
repositories {
38+
maven {
39+
name = "jitpack"
40+
url = "https://jitpack.io"
41+
}
42+
}
43+
44+
dependencies {
45+
implementation "com.github.technicallycoded:FoliaLib:main-SNAPSHOT"
46+
}
47+
48+
shadowJar {
49+
// !! MAKE SURE TO CHANGE THIS TO YOUR PLUGIN'S GROUP & PLUGIN NAME !!
50+
relocate "com.tcoded.folialib", "CHANGE-THE-GROUP.CHANGE-THE-PLUGIN-NAME.lib.folialib"
51+
52+
// Optional: If you use minimize, make sure you exclude FoliaLib
53+
// Do not uncomment this if you don't know what you are doing
54+
// minimize {
55+
// exclude dependency("com.tcoded:FoliaLib:.*")
56+
// }
57+
}
58+
```
59+
</details>
960

10-
Note: This project is still in its early stages and may make frequent breaking changes to the API. Additionally, I won't claim that this library is perfect; If you find any issues, please report them on the [issues page](https://github.com/TechnicallyCoded/FoliaLib/issues)
61+
### Maven Dependency
62+
<details>
63+
<summary>[Click to show Maven example configurations]</summary>
1164

12-
## As a dependency
13-
### Maven
1465
```xml
1566
<repositories>
1667
<repository>
17-
<id>devmart-other</id>
18-
<url>https://nexuslite.gcnt.net/repos/other/</url>
68+
<id>jitpack</id>
69+
<url>https://jitpack.io</url>
1970
</repository>
2071
</repositories>
2172

2273
<dependencies>
2374
<dependency>
24-
<groupId>com.tcoded</groupId>
75+
<groupId>com.github.technicallycoded</groupId>
2576
<artifactId>FoliaLib</artifactId>
26-
<version>[SEE TOP OF README]</version>
77+
<version>main-SNAPSHOT</version>
2778
<scope>compile</scope>
2879
</dependency>
2980
</dependencies>
30-
```
31-
> [!WARNING]\
32-
> You are expected to relocate the package "com.tcoded.folialib" to your own (ex: "me.steve.lib.folialib") to prevent conflicts with other plugins!
33-
34-
***
35-
36-
### Gradle
37-
```groovy
38-
repositories {
39-
maven {
40-
name = "devmart-other"
41-
url = "https://nexuslite.gcnt.net/repos/other/"
42-
}
43-
}
4481

45-
dependencies {
46-
implementation "com.tcoded:FoliaLib:[SEE TOP OF README]"
47-
}
82+
<build>
83+
<plugins>
84+
<plugin>
85+
<groupId>org.apache.maven.plugins</groupId>
86+
<artifactId>maven-shade-plugin</artifactId>
87+
<version>3.6.0</version>
88+
<executions>
89+
<execution>
90+
<phase>package</phase>
91+
<goals>
92+
<goal>shade</goal>
93+
</goals>
94+
</execution>
95+
</executions>
96+
<configuration>
97+
<relocations>
98+
<relocation>
99+
<pattern>com.tcoded.folialib</pattern>
100+
<!-- !! MAKE SURE TO CHANGE THIS TO YOUR PLUGIN'S GROUP & PLUGIN NAME !! -->
101+
<shadedPattern>CHANGE-THE-GROUP.CHANGE-THE-PLUGIN-NAME.lib.folialib</shadedPattern>
102+
</relocation>
103+
</relocations>
104+
</configuration>
105+
</plugin>
106+
</plugins>
107+
</build>
48108
```
49-
> [!WARNING]\
50-
> You are expected to relocate the package "com.tcoded.folialib" to your own (ex: "me.steve.lib.folialib") to prevent conflicts with other plugins!
109+
</details>
110+
111+
<br/>
51112

52113
## How to use
53114
Create a new instance of the FoliaLib class:
@@ -61,34 +122,60 @@ Here are some examples of how to use the library:
61122

62123
// On a folia server, runNextTick() will run using the GlobalRegionScheduler
63124
// !! This does not make it safe to use for players or block changes !!
64-
// Use other methods below for handling those
125+
// Use other methods found below for handling these cases
65126
// This should only be used for updating the following (see GlobalRegionScheduler.java for more info)
66-
// - world day time, world game time, weather cycle, sleep night skipping, executing commands for console, and other misc
127+
// - world day time
128+
// - world game time
129+
// - weather cycle
130+
// - sleep/night skipping
131+
// - executing commands for console
67132
// On a Spigot server, runNextTick() will run on the main thread
68-
foliaLib.getImpl().runNextTick(() -> {/* Code */});
133+
foliaLib.getScheduler().runNextTick(() -> {/* Code */});
69134

70135
// In both cases, this method will run asynchronously
71-
foliaLib.getImpl().runAsync(() -> {/* Code */});
136+
foliaLib.getScheduler().runAsync(() -> {/* Code */});
72137

73138
// On a Folia server, this method will run using the GlobalRegionScheduler
74139
// On a Spigot server, this method will run on the main thread
75-
foliaLib.getImpl().runTimer(() -> {/* Code */}, 1, 20); // Using ticks
76-
foliaLib.getImpl().runTimer(() -> {/* Code */}, 1, 20 * 50L, TimeUnit.MILLISECONDS); // Using TimeUnit
140+
foliaLib.getScheduler().runTimer(() -> {/* Code */}, 1, 20); // Using ticks
77141

78142
// In both cases, this method will run asynchronously
79-
foliaLib.getImpl().runTimerAsync(() -> {/* Code */}, 1, 20); // Using ticks
80-
foliaLib.getImpl().runTimerAsync(() -> {/* Code */}, 1, 20 * 50L, TimeUnit.MILLISECONDS); // Using TimeUnit
143+
foliaLib.getScheduler().runTimerAsync(() -> {/* Code */}, 1, 20); // Using ticks
144+
foliaLib.getScheduler().runTimerAsync(() -> {/* Code */}, 1, 20 * 50L, TimeUnit.MILLISECONDS); // Using TimeUnit
81145

82146
// On a folia server, this will run the code using the RegionScheduler that is appropriate for the location
83147
// On a spigot server, this will run the code on the main thread
84-
foliaLib.getImpl().runAtLocation(location, () -> {/* Code */});
148+
foliaLib.getScheduler().runAtLocation(location, () -> {/* Code */});
85149

86150
// On a folia server, this will run the code using the EntityScheduler that is appropriate for the entity
87151
// On a spigot server, this will just run the code on the main thread
88-
foliaLib.getImpl().runAtEntity(entity, () -> {/* Code */});
152+
foliaLib.getScheduler().runAtEntity(entity, () -> {/* Code */});
153+
154+
// On a folia server, this will teleport the entity (or player) asynchronously
155+
// On a paper server (which supports async teleports), this will also teleport asynchronously
156+
// On a spigot server, this will fallback to teleporting the player on the next tick
157+
// Why not immediately teleport on spigot?
158+
// 1. We don't know if you're running this from the main thread (but this could be checked)
159+
// 2. Above all, we quickly expose any bugs that could result from expecting instant
160+
// teleports on any platform
161+
// Returns: A CompletableFuture<Boolean> from which you can execute any dependent code. The Boolean
162+
// is the success state of the teleportation.
163+
foliaLib.getScheduler().teleportAsync(entity, location, optionalTeleportCause);
164+
165+
// During your plugin's onDisable(), please use the following.
166+
// This will cancel all the tasks associated with this FoliaLib instance
167+
foliaLib.getScheduler().cancelAllTasks();
89168

90169
// AND MANY MORE OPTIONS...!
170+
171+
// You can also manually check for a specific platform if certain parts of your code
172+
// should only run under those conditions (ex: use of specific folia-only APIs)
173+
foliaLib.isFolia(); // true/false
174+
foliaLib.isPaper(); // true/false
175+
foliaLib.isSpigot(); // true/false
91176
```
92177

178+
<br/>
179+
93180
## License
94181
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details

0 commit comments

Comments
 (0)