release to maven central

.github/workflows/release.yaml

@@ -0,0 +1,30 @@
+name: Gradle Publish to Maven Central
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      SONATYPE_USERNAME: ${{ secrets.SONATYPE_USERNAME }}
+      SONATYPE_PASSWORD: ${{ secrets.SONATYPE_PASSWORD }}
+      GPG_PRIVATE_KEY: ${{ secrets.GPG_PRIVATE_KEY }}
+      GPG_PASSPHRASE: ${{ secrets.GPG_PASSWORD }}
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up JDK 17
+        uses: actions/setup-java@v2
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+      - name: Setup Gradle
+        uses: gradle/gradle-build-action@v2
+      - name: Publish to Sonatype
+        env:
+          TAG_VERSION: ${{ github.ref_name }}
+        run: |
+          ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository -Peula=true
+          echo "Version: ${TAG_VERSION}" >> $GITHUB_STEP_SUMMARY

BENCHMARK.md

@@ -0,0 +1,34 @@
+# Benchmark
+
+> Reminder: The benchmark is very simple, and should only be valued as a rough estimate.
+
+The tests were run against [`minestom-ce`](https://github.com/hollow-cube/minestom-ce) on 1.19.4 (`f13a7b49fa`),
+on a Macbook Pro (M1 Max). The source code of the test can be seen below.
+
+```java
+public class ScuffedBenchmark {
+    public static void main(String[] args) throws Exception {
+        MinecraftServer.init();
+        var instance = MinecraftServer.getInstanceManager().createInstanceContainer();
+
+        long start = System.nanoTime();
+
+        for (int iter = 0; iter < 10; iter++) {
+            System.out.println("Starting iteration " + iter);
+            // TNTLoader loader = new TNTLoader(new FileTNTSource(Path.of("src/test/resources/bench/bench.tnt")));
+            // AnvilLoader loader = new AnvilLoader(Path.of("src/test/resources/bench"));
+            PolarLoader loader = new PolarLoader(PolarReader.read(Files.readAllBytes(Path.of("src/test/resources/bench.polar"))));
+            for (int x = 0; x < 32; x++) {
+                for (int z = 0; z < 32; z++) {
+                    loader.loadChunk(instance, 0, 0).join();
+                }
+            }
+
+        }
+
+        long end = System.nanoTime();
+        System.out.println("Took " + (end - start) / 1_000_000_000.0 / 10.0 + " seconds/iter");
+        MinecraftServer.stopCleanly();
+    }
+}
+```

spec.md → FORMAT.md

@@ -1,13 +1,15 @@
 # Polar v1.0
+
 The polar format resembles the anvil format in many ways, though it is binary, not NBT.
 
 ### Header
+
 ```
 int - magic number
 byte - major version
 byte - minor version
 byte - compression type (0 = none, 1 = zstd)
-varint - length of the rest of the data
+varint - length of the rest of the data (uncompressed)
 
 byte - min section
 byte - max section
@@ -17,6 +19,7 @@ varint - number of chunks
 ```
 
 ### Chunk
+
 ```
 varint - chunk x
 varint - chunk z
@@ -36,7 +39,10 @@ int - heightmap bitmask
 todo entities
 ```
 
+todo need to support block entities without ids (minestom does)
+
 ### Sections
+
 ```
 bool - is empty (if set, nothing follows)
 

README.md

@@ -1,15 +1,25 @@
 # Polar
-A world format blah blah docs
 
-## Features
+[![license](https://img.shields.io/github/license/Minestom/MinestomDataGenerator.svg)](LICENSE)
+
+A world format for Minestom designed for simpler and smaller handling of small worlds, particularly for user generated
+content where size matters.
+
+Polar generally should not be used for large worlds, since it stores worlds in a single file and does not
+allow random access of chunks (the entire world must be loaded to read chunks). As a general rule of thumb,
+Polar should only be used for worlds small enough that they are OK being completely kept in memory.
+
+The Polar format is described in [FORMAT.md](FORMAT.md).
 
-* todo
-* write
-* these
+## Features
 
-The format is described in `/spec`
+* [Fast to load](#benchmark)
+* [Small file size](#benchmark)
+* Simple to use
+* [Anvil conversion](#anvil-interop)
 
 ## Install
+
 Polar is (to be) available on [maven central](https://search.maven.org/search?q=g:dev.hollowcube%20AND%20a:polar).
 
 ```groovy
@@ -23,7 +33,66 @@ dependencies {
 ```
 
 ## Usage
-todo
+
+Polar provides a `ChunkLoader` implementation for use with Minestom `Instance`s.
+
+```
+// Loading
+Instance instance=...;
+instance.setChunkLoader(new PolarLoader(Path.of("/path/to/file.polar")));
+
+// Saving
+instance.saveChunksToStorage();
+```
+
+### Anvil interop
+
+Anvil conversion utilities are also included, and can be used something like the following.
+
+```
+var polarWorld = AnvilPolar.anvilToPolar(Path.of("/path/to/anvil/world/dir"));
+var polarWorldBytes=PolarWriter.write(polarWorld);
+```
+
+### ChunkSelector
+
+Most Polar functions take a `ChunkSelector` as an optional parameter to select which chunks to include in that
+operation.
+For example, to convert an anvil world while only selecting a 5 chunk radius around 0,0, you could do the following:
+
+```
+AnvilPolar.anvilToPolar(Path.of("/path/to/anvil/world/dir"), ChunkSelector.radius(5));
+```
 
 ## Comparison to others
-todo comparison to anvil, tnt, anything else?
+
+### "Benchmark"
+
+Using a very basic benchmark, we can make some rough guesses about performance between Polar, Anvil, and TNT.
+The benchmark loads a single region 10 times, averaging the runtime of each iteration.
+More information about the test can be found in [BENCHMARK.md](BENCHMARK.md)
+
+| Scenario        | Iterations | Polar (v1, zstd) | Polar (v1, uncompressed) | TNT (v1)       | Anvil          |
+|-----------------|------------|------------------|--------------------------|----------------|----------------|
+| 1.19.4 Region   | 10         | 0.61400 s/iter   | 0.56449 s/iter           | 3.56732 s/iter | 9.65274 s/iter |
+| EmortalMC Lobby | 10         | 0.06565 s/iter   | 0.04759 s/iter           | 0.05501 s/iter | 0.56378 s/iter |
+| EmortalMC Lobby | 500        | 0.06777 s/iter   | 0.06650 s/iter           | 0.07553 s/iter | -              |
+
+| Scenario        | Polar (v1, zstd) | Polar (v1, uncompressed) | TNT (v1) | Anvil |
+|-----------------|------------------|--------------------------|----------|-------|
+| 1.19.4 Region   | 5.9mb            | 26.1mb                   | 115.9mb  | 9.7mb |
+| EmortalMC Lobby | 105kb            | 800kb                    | 1.3mb    | 13mb* |
+
+* This is not a fair comparison. Polar and TNT are only covering the 10x10 relevant chunks, anvil has 4 regions.
+
+1.19.4 Region is a single 32x32 chunk region created in 1.19.4, see `src/test/resources/bench` for the world.
+
+EmortalMC Lobby is 10x10 chunk world, see `mc.emortal.dev` for more info.
+
+## Contributing
+
+Contributions via PRs and issues are always welcome.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

build.gradle.kts

@@ -1,9 +1,14 @@
 plugins {
-    id("java")
+    `java-library`
+
+    `maven-publish`
+    signing
+    alias(libs.plugins.nexuspublish)
 }
 
 group = "dev.hollowcube"
-version = "1.0.0"
+version = System.getenv("TAG_VERSION") ?: "dev"
+description = "Fast and small world format for Minestom"
 
 repositories {
     mavenCentral()
@@ -12,14 +17,92 @@ repositories {
 
 dependencies {
     compileOnly(libs.minestom)
-    testImplementation(libs.minestom)
-
     implementation(libs.zstd)
 
     testImplementation(platform("org.junit:junit-bom:5.9.1"))
     testImplementation("org.junit.jupiter:junit-jupiter")
+    testImplementation(libs.minestom)
+}
+
+java {
+    withSourcesJar()
+    withJavadocJar()
+
+    sourceCompatibility = JavaVersion.VERSION_17
+    targetCompatibility = JavaVersion.VERSION_17
 }
 
 tasks.test {
+    maxHeapSize = "2g"
     useJUnitPlatform()
 }
+
+nexusPublishing {
+    this.packageGroup.set("dev.hollowcube")
+
+    repositories.sonatype {
+        nexusUrl.set(uri("https://s01.oss.sonatype.org/service/local/"))
+        snapshotRepositoryUrl.set(uri("https://s01.oss.sonatype.org/content/repositories/snapshots/"))
+
+        if (System.getenv("SONATYPE_USERNAME") != null) {
+            username.set(System.getenv("SONATYPE_USERNAME"))
+            password.set(System.getenv("SONATYPE_PASSWORD"))
+        }
+    }
+}
+
+publishing.publications.create<MavenPublication>("maven") {
+    groupId = "dev.hollowcube"
+    artifactId = "polar"
+    version = project.version.toString()
+
+    from(project.components["java"])
+
+    pom {
+        name.set(artifactId)
+        description.set(project.description)
+        url.set("https://github.com/hollow-cube/polar")
+
+        licenses {
+            license {
+                name.set("MIT")
+                url.set("https://github.com/hollow-cube/polar/blob/main/LICENSE")
+            }
+        }
+
+        developers {
+            developer {
+                id.set("mworzala")
+                name.set("Matt Worzala")
+                email.set("matt@hollowcube.dev")
+            }
+        }
+
+        issueManagement {
+            system.set("GitHub")
+            url.set("https://github.com/hollow-cube/polar/issues")
+        }
+
+        scm {
+            connection.set("scm:git:git://github.com/hollow-cube/polar.git")
+            developerConnection.set("scm:git:git@github.com:hollow-cube/polar.git")
+            url.set("https://github.com/hollow-cube/polar")
+            tag.set(System.getenv("TAG_VERSION") ?: "HEAD")
+        }
+
+        ciManagement {
+            system.set("Github Actions")
+            url.set("https://github.com/hollow-cube/polar/actions")
+        }
+    }
+}
+
+signing {
+    isRequired = System.getenv("CI") != null
+
+    val privateKey = System.getenv("GPG_PRIVATE_KEY")
+    val keyPassphrase = System.getenv()["GPG_PASSPHRASE"]
+    useInMemoryPgpKeys(privateKey, keyPassphrase)
+
+    sign(publishing.publications)
+}

gradle/libs.versions.toml

@@ -4,6 +4,11 @@ metadata.format.version = "1.1"
 minestom = "f13a7b49fa"
 zstd = "1.5.5-3"
 
+nexuspublish = "1.3.0"
+
 [libraries]
 minestom = { group = "dev.hollowcube", name = "minestom-ce", version.ref = "minestom" }
 zstd = { group = "com.github.luben", name = "zstd-jni", version.ref = "zstd" }
+
+[plugins]
+nexuspublish = { id = "io.github.gradle-nexus.publish-plugin", version.ref = "nexuspublish" }