Skip to content

Update README.md #19

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

Merged
TechnicallyCoded merged 4 commits into from
Aug 12, 2024
Merged

Update README.md #19

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
bf29bad
Update README.md
TechnicallyCoded Jun 21, 2024
8f16b05
Update warnings, gradle configuration, maven configuration, use jitpa…
TechnicallyCoded Aug 12, 2024
9aed731
Update api examples
TechnicallyCoded Aug 12, 2024
a78efd7
Add examples of newly supported features & better documentation
TechnicallyCoded Aug 12, 2024
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
169 changes: 128 additions & 41 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,114 @@
# FoliaLib
[![GitHub Release](https://img.shields.io/github/release/technicallycoded/FoliaLib.svg?style=flat)]()
# FoliaLib     [![GitHub Release](https://img.shields.io/github/release/technicallycoded/FoliaLib.svg?style=flat)]()

Disclaimer:
This project is not directly affiliated with Paper team or the Folia project.
Developers and contributors like you make this project possible. This project is not directly affiliated with PaperMC.

<br/>

## Description
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.
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.

**Version support**:
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.

**API 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)

<br/>

## FoliaLib as a dependency

> [!WARNING]
> You are expected to relocate the package `com.tcoded.folialib` to prevent conflicts with other plugins!
> Example configuration snippets demonstrating how to do this are available below for Maven and Gradle.

> [!WARNING]
> Ensure that you exclude FoliaLib from any `minimize` operation.

### Gradle Dependency
<details>
<summary>[Click to show Gradle example configurations]</summary>

```groovy
plugins {
id 'com.github.johnrengelman.shadow' version '8.1.1' // For up to Java 17
// id 'io.github.goooler.shadow' version '8.1.7' // Uncomment for Java 21 or higher
}

repositories {
maven {
name = "jitpack"
url = "https://jitpack.io"
}
}

dependencies {
implementation "com.github.technicallycoded:FoliaLib:main-SNAPSHOT"
}

shadowJar {
// !! MAKE SURE TO CHANGE THIS TO YOUR PLUGIN'S GROUP & PLUGIN NAME !!
relocate "com.tcoded.folialib", "CHANGE-THE-GROUP.CHANGE-THE-PLUGIN-NAME.lib.folialib"

// Optional: If you use minimize, make sure you exclude FoliaLib
// Do not uncomment this if you don't know what you are doing
// minimize {
// exclude dependency("com.tcoded:FoliaLib:.*")
// }
}
```
</details>

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)
### Maven Dependency
<details>
<summary>[Click to show Maven example configurations]</summary>

## As a dependency
### Maven
```xml
<repositories>
<repository>
<id>devmart-other</id>
<url>https://nexuslite.gcnt.net/repos/other/</url>
<id>jitpack</id>
<url>https://jitpack.io</url>
</repository>
</repositories>

<dependencies>
<dependency>
<groupId>com.tcoded</groupId>
<groupId>com.github.technicallycoded</groupId>
<artifactId>FoliaLib</artifactId>
<version>[SEE TOP OF README]</version>
<version>main-SNAPSHOT</version>
<scope>compile</scope>
</dependency>
</dependencies>
```
> [!WARNING]\
> You are expected to relocate the package "com.tcoded.folialib" to your own (ex: "me.steve.lib.folialib") to prevent conflicts with other plugins!

***

### Gradle
```groovy
repositories {
maven {
name = "devmart-other"
url = "https://nexuslite.gcnt.net/repos/other/"
}
}

dependencies {
implementation "com.tcoded:FoliaLib:[SEE TOP OF README]"
}
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.6.0</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
<configuration>
<relocations>
<relocation>
<pattern>com.tcoded.folialib</pattern>
<!-- !! MAKE SURE TO CHANGE THIS TO YOUR PLUGIN'S GROUP & PLUGIN NAME !! -->
<shadedPattern>CHANGE-THE-GROUP.CHANGE-THE-PLUGIN-NAME.lib.folialib</shadedPattern>
</relocation>
</relocations>
</configuration>
</plugin>
</plugins>
</build>
```
> [!WARNING]\
> You are expected to relocate the package "com.tcoded.folialib" to your own (ex: "me.steve.lib.folialib") to prevent conflicts with other plugins!
</details>

<br/>

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

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

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

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

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

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

// On a folia server, this will run the code using the EntityScheduler that is appropriate for the entity
// On a spigot server, this will just run the code on the main thread
foliaLib.getImpl().runAtEntity(entity, () -> {/* Code */});
foliaLib.getScheduler().runAtEntity(entity, () -> {/* Code */});

// On a folia server, this will teleport the entity (or player) asynchronously
// On a paper server (which supports async teleports), this will also teleport asynchronously
// On a spigot server, this will fallback to teleporting the player on the next tick
// Why not immediately teleport on spigot?
// 1. We don't know if you're running this from the main thread (but this could be checked)
// 2. Above all, we quickly expose any bugs that could result from expecting instant
// teleports on any platform
// Returns: A CompletableFuture<Boolean> from which you can execute any dependent code. The Boolean
// is the success state of the teleportation.
foliaLib.getScheduler().teleportAsync(entity, location, optionalTeleportCause);

// During your plugin's onDisable(), please use the following.
// This will cancel all the tasks associated with this FoliaLib instance
foliaLib.getScheduler().cancelAllTasks();

// AND MANY MORE OPTIONS...!

// You can also manually check for a specific platform if certain parts of your code
// should only run under those conditions (ex: use of specific folia-only APIs)
foliaLib.isFolia(); // true/false
foliaLib.isPaper(); // true/false
foliaLib.isSpigot(); // true/false
```

<br/>

## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details