chore: refactor project setup page

Author: Strokkur424

CONTRIBUTING.md

@@ -132,13 +132,15 @@ These constants can be imported and used in MDX, like so:
 import {
   LATEST_MC_RELEASE,
   LATEST_PAPER_RELEASE,
+  LATEST_PAPER_BUILD_API_VERSION,
   LATEST_VELOCITY_RELEASE,
   LATEST_FOLIA_RELEASE,
   LATEST_WATERFALL_RELEASE,
   LATEST_USERDEV_RELEASE,
 } from "/src/utils/versions";
 
 Latest Paper version is {LATEST_PAPER_RELEASE}.
+Latest Paper API build version is {LATEST_PAPER_BUILD_API_VERSION}
 Latest Velocity version is {LATEST_VELOCITY_RELEASE}.
 Latest Minecraft version is {LATEST_MC_RELEASE}.
 Latest Folia version is {LATEST_FOLIA_RELEASE}.

astro.config.ts

@@ -15,6 +15,7 @@ import {
   LATEST_ANSI_RELEASE,
   LATEST_FOLIA_RELEASE,
   LATEST_MC_RELEASE,
+  LATEST_PAPER_BUILD_API_VERSION,
   LATEST_PAPER_RELEASE,
   LATEST_USERDEV_RELEASE,
   LATEST_VELOCITY_RELEASE,
@@ -560,6 +561,7 @@ export default defineConfig({
           constants: {
             LATEST_MC_RELEASE,
             LATEST_PAPER_RELEASE,
+            LATEST_PAPER_BUILD_API_VERSION,
             LATEST_VELOCITY_RELEASE,
             LATEST_FOLIA_RELEASE,
             LATEST_WATERFALL_RELEASE,

src/content/docs/paper/dev/getting-started/project-setup.mdx

@@ -24,7 +24,15 @@ You will land into the `build.gradle.kts` file where you can add your dependenci
 
 ### Adding Paper as a dependency
 
-To add Paper as a dependency, you will need to add the Paper repository to your `build.gradle.kts` or `pom.xml` file as well as the dependency itself.
+To add Paper as a dependency, you will need to add the Paper repository and dependency to your `build.gradle.kts` file.
+
+:::tip
+
+If you want to reference a specific build, you can do so by replacing the + with the build identifier
+(i.e. `{VERSION}.build.25-alpha` for the 25th alpha build of a version). Before `26.1` (`1.21.11` and below), the
+version string format used was `{VERSION}-R0.1-SNAPSHOT`, with no way to reference a specific build.
+
+:::
 
 <Tabs syncKey="build-system">
   <TabItem label="Gradle (Kotlin)">
@@ -37,29 +45,18 @@ To add Paper as a dependency, you will need to add the Paper repository to your
     }
 
     dependencies {
-      compileOnly("io.papermc.paper:paper-api:\{LATEST_PAPER_RELEASE}-R0.1-SNAPSHOT")
+      compileOnly("io.papermc.paper:paper-api:\{LATEST_PAPER_RELEASE}.build.+")
     }
 
     java {
-      toolchain.languageVersion.set(JavaLanguageVersion.of(21))
+      toolchain.languageVersion.set(JavaLanguageVersion.of(25))
     }
     ```
   </TabItem>
-  <TabItem label="Gradle (Groovy)">
-    ```groovy title="build.gradle" replace
-    repositories {
-      maven {
-        name = 'papermc'
-        url = 'https://repo.papermc.io/repository/maven-public/'
-      }
-    }
+  <TabItem label="Maven (Discouraged)">
+    Maven unfortunately does not support obtaining the latest version using version ranges the way Gradle
+    does. You will need to explicitly declare the build of a version you are targeting.
 
-    dependencies {
-      compileOnly 'io.papermc.paper:paper-api:\{LATEST_PAPER_RELEASE}-R0.1-SNAPSHOT'
-    }
-    ```
-  </TabItem>
-  <TabItem label="Maven">
     ```xml title="pom.xml" replace
     <project>
       <repositories>
@@ -73,7 +70,7 @@ To add Paper as a dependency, you will need to add the Paper repository to your
         <dependency>
           <groupId>io.papermc.paper</groupId>
           <artifactId>paper-api</artifactId>
-          <version>\{LATEST_PAPER_RELEASE}-R0.1-SNAPSHOT</version>
+          <version>\{LATEST_PAPER_BUILD_API_VERSION}</version>
           <scope>provided</scope>
         </dependency>
       </dependencies>
@@ -222,138 +219,6 @@ If everything went well, you should see something like this:
 
 ![](./assets/paper-plugin-overview.png)
 
-## Plugin remapping
-
-As of 1.20.5, Paper ships with a Mojang-mapped runtime instead of reobfuscating the server to Spigot mappings.
-If you are using Spigot/Bukkit plugins, your plugin will be assumed to be Spigot-mapped.
-This means that the server will have to deobfuscate and remap the plugin JAR when it's loaded for the first time.
-
-:::note
-
-`paperweight-userdev` already sets this attribute automatically. For more information see the [userdev](/paper/dev/userdev) documentation.
-
-:::
-
-### Mojang mappings
-
-To tell the server that your plugin is Mojang-mapped, you need to add the following code to your build script:
-
-:::note[Paper plugins]
-
-If you are using Paper plugins, this step is not needed as plugins will be assumed to be Mojang-mapped.
-
-:::
-
-<Tabs syncKey="build-system">
-  <TabItem label="Gradle (Kotlin)">
-    ```kotlin title="build.gradle.kts"
-    tasks.jar {
-      manifest {
-        attributes["paperweight-mappings-namespace"] = "mojang"
-      }
-    }
-    // if you have shadowJar configured
-    tasks.shadowJar {
-      manifest {
-        attributes["paperweight-mappings-namespace"] = "mojang"
-      }
-    }
-    ```
-  </TabItem>
-  <TabItem label="Gradle (Groovy)">
-    ```groovy title="build.gradle"
-    jar {
-      manifest {
-        attributes(
-          'paperweight-mappings-namespace': 'mojang'
-        )
-      }
-    }
-    // if you have shadowJar configured
-    shadowJar {
-      manifest {
-        attributes(
-          'paperweight-mappings-namespace': 'mojang'
-        )
-      }
-    }
-    ```
-  </TabItem>
-  <TabItem label="Maven">
-    ```xml title="pom.xml"
-    <plugin>
-      <groupId>org.apache.maven.plugins</groupId>
-      <artifactId>maven-jar-plugin</artifactId>
-      <version>3.4.1</version>
-      <configuration>
-        <archive>
-          <manifestEntries>
-            <paperweight-mappings-namespace>mojang</paperweight-mappings-namespace>
-          </manifestEntries>
-        </archive>
-      </configuration>
-    </plugin>
-    ```
-  </TabItem>
-</Tabs>
-
-### Spigot mappings
-
-If you explicitly want to tell the server that your plugin is Spigot-mapped, you need to add the following code to your build script:
-
-<Tabs syncKey="build-system">
-  <TabItem label="Gradle (Kotlin)">
-    ```kotlin title="build.gradle.kts"
-    tasks.jar {
-      manifest {
-        attributes["paperweight-mappings-namespace"] = "spigot"
-      }
-    }
-    // if you have shadowJar configured
-    tasks.shadowJar {
-      manifest {
-        attributes["paperweight-mappings-namespace"] = "spigot"
-      }
-    }
-    ```
-  </TabItem>
-  <TabItem label="Gradle (Groovy)">
-    ```groovy title="build.gradle"
-    jar {
-      manifest {
-        attributes(
-          'paperweight-mappings-namespace': 'spigot'
-        )
-      }
-    }
-    // if you have shadowJar configured
-    shadowJar {
-      manifest {
-        attributes(
-          'paperweight-mappings-namespace': 'spigot'
-        )
-      }
-    }
-    ```
-  </TabItem>
-  <TabItem label="Maven">
-    ```xml title="pom.xml"
-    <plugin>
-      <groupId>org.apache.maven.plugins</groupId>
-      <artifactId>maven-jar-plugin</artifactId>
-      <version>3.4.1</version>
-      <configuration>
-        <archive>
-          <manifestEntries>
-            <paperweight-mappings-namespace>spigot</paperweight-mappings-namespace>
-          </manifestEntries>
-        </archive>
-      </configuration>
-    </plugin>
-    ```
-  </TabItem>
-</Tabs>
-
 ## Conclusion
 
 You should now have a project set up with Paper as a dependency.

src/utils/versions.ts

@@ -56,7 +56,7 @@ const findLatest = async (project: Project): Promise<string> => {
   // find the newest version with at least one non-alpha build
   for (const version of versions) {
     const builds = await fetchBuilds(project, version);
-    if (builds.some((b) => b.channel !== "ALPHA")) {
+    if (builds.some((b) => true || b.channel !== "ALPHA")) { // TODO: Remove this, temporary change
       return version;
     }
   }
@@ -68,6 +68,10 @@ const paperProject = await fetchProject("paper");
 
 export const LATEST_PAPER_RELEASE = await findLatest(paperProject);
 
+const paperBuild = (await fetchBuilds(paperProject, LATEST_PAPER_RELEASE)).at(0);
+
+export const LATEST_PAPER_BUILD_API_VERSION = `${LATEST_PAPER_RELEASE}.build.${paperBuild?.id}-${paperBuild?.channel.toLocaleLowerCase()}`
+
 const velocityProject = await fetchProject("velocity");
 
 export const LATEST_VELOCITY_RELEASE = await findLatest(velocityProject);