From dc505f5c932dd71a08717f9016c01dac4224e54f Mon Sep 17 00:00:00 2001
From: Timar Karels <69715898+thegatesdev@users.noreply.github.com>
Date: Mon, 8 Jul 2024 17:50:21 +0200
Subject: [PATCH] Improve introduction section
---
.vitepress/config.mts | 9 +-
docs/introduction.md | 2 +-
docs/setup/dependencies.md | 96 ----------
docs/starting-out/project-setup.md | 179 ++++++++++++++++++
.../your-first-server.md | 118 ++----------
5 files changed, 205 insertions(+), 199 deletions(-)
delete mode 100644 docs/setup/dependencies.md
create mode 100644 docs/starting-out/project-setup.md
rename docs/{setup => starting-out}/your-first-server.md (52%)
diff --git a/.vitepress/config.mts b/.vitepress/config.mts
index e8b0c20..059bca7 100644
--- a/.vitepress/config.mts
+++ b/.vitepress/config.mts
@@ -48,12 +48,15 @@ export default defineConfig({
link: "/docs/introduction",
},
{
- text: "Setup",
+ text: "Getting Started",
items: [
- { text: "Dependencies", link: "/docs/setup/dependencies" },
+ {
+ text: "Project Setup",
+ link: "/docs/starting-out/project-setup"
+ },
{
text: "Your First Server",
- link: "/docs/setup/your-first-server",
+ link: "/docs/starting-out/your-first-server",
},
],
},
diff --git a/docs/introduction.md b/docs/introduction.md
index a86d8e9..57be6d9 100644
--- a/docs/introduction.md
+++ b/docs/introduction.md
@@ -4,4 +4,4 @@ The goal of this wiki is to familiarize you with our library. The most important
The project Javadoc is currently hosted [here](https://minestom.github.io/Minestom/). Additionally, we do have a [Discord server](https://discord.gg/pkFRvqB) where you can ask anything you want.
-If you do not know how you landed here, Minestom is a complete rewrite of the Minecraft server software without any Mojang code. You can learn more about it [here](https://github.com/Minestom/Minestom).
+If you do not know how you landed here: Minestom is a complete rewrite of the Minecraft server software without any Mojang code. You can learn more about it [here](https://github.com/Minestom/Minestom).
diff --git a/docs/setup/dependencies.md b/docs/setup/dependencies.md
deleted file mode 100644
index 742eecd..0000000
--- a/docs/setup/dependencies.md
+++ /dev/null
@@ -1,96 +0,0 @@
----
-description: Describes how to add Minestom as a dependency in your project.
----
-
-
-
-# Dependencies
-
-::: info
-Minestom needs Java 21 or newer in order to run. If you are using Gradle, you must use version 8.5 or higher.
-:::
-
-Adding Minestom to your Java project is done just like a normal library.
-
-## Repositories
-
-:::tabs
-== Gradle (Groovy)
-
-```groovy
-repositories {
- mavenCentral()
-}
-```
-
-== Gradle (Kotlin)
-
-```kotlin
-repositories {
- mavenCentral()
-}
-```
-
-:::
-
-## Dependencies
-
-:::tabs
-== Gradle (Groovy)
-
-```groovy-vue
-dependencies {
- implementation 'net.minestom:minestom-snapshots:{{ version }}'
-}
-```
-
-== Gradle (Kotlin)
-
-```kotlin-vue
-dependencies {
- implementation("net.minestom:minestom-snapshots:{{version}}")
-}
-```
-
-== Maven
-
-```xml-vue
-
-
-
- net.minestom
- minestom-snapshots
- {{version}}
-
-
-```
-
-:::
-
-The version string is always the first 10 characters of a commit hash. You can view commits
-[here](https://github.com/Minestom/Minestom/commits/master/).
-
-Minestom PR branches are also published and can be used to preview upcoming features. For such branches, the version
-string is `{branch}-{first 10 chars of commit}`. For example, the 1_20_5 branch was usable with the version string
-`1_20_5-dd965f4bb8`.
diff --git a/docs/starting-out/project-setup.md b/docs/starting-out/project-setup.md
new file mode 100644
index 0000000..42aefb3
--- /dev/null
+++ b/docs/starting-out/project-setup.md
@@ -0,0 +1,179 @@
+---
+description: Describes how to set up a Minestom project.
+---
+
+
+
+# Project Setup
+
+## Adding the dependency
+
+Minestom is available on Maven Central.
+Get it by enabling Maven Central (on Gradle) and adding a version to your dependencies.
+
+:::tabs
+
+== Gradle (Groovy)
+
+```groovy-vue
+repositories {
+ mavenCentral()
+}
+dependencies {
+ implementation 'net.minestom:minestom-snapshots:{{ version }}'
+}
+```
+
+== Gradle (Kotlin)
+
+```kotlin-vue
+repositories {
+ mavenCentral()
+}
+dependencies {
+ implementation("net.minestom:minestom-snapshots:{{version}}")
+}
+```
+
+== Maven
+
+```xml-vue
+
+
+
+ net.minestom
+ minestom-snapshots
+ {{version}}
+
+
+```
+
+:::
+
+The version string is always the first 10 characters of a commit hash. You can view commits
+[here](https://github.com/Minestom/Minestom/commits/master/).
+
+Minestom PR branches are also published and can be used to preview upcoming features. For such branches, the version
+string is `{branch}-{first 10 chars of commit}`. For example, the 1_20_5 branch was usable with the version string
+`1_20_5-dd965f4bb8`.
+
+## Setting up shading
+
+For Gradle users, we will use [the "Shadow" plugin](https://imperceptiblethoughts.com/shadow/introduction/) to include Minestom in the JAR file.
+
+ For Maven users, you will need [the "Shade" plugin](https://maven.apache.org/plugins/maven-shade-plugin/). If you use Maven and would like to contribute an example
+it would be appreciated :)
+
+::: warning
+As of the time writing this, the original shadow plugin from johnrengelman has not been updated for Java 21 support, so we'll use a fork in this example.
+:::
+
+:::tabs
+
+== Gradle (Groovy)
+
+```groovy
+plugins {
+ id "io.github.goooler.shadow" version "8.1.7"
+}
+```
+
+== Gradle (Kotlin)
+
+```kts
+plugins {
+ id("io.github.goooler.shadow") version "8.1.7"
+}
+```
+
+:::
+
+## Finishing the configuration
+
+Finally, to create a runnable JAR, set your main class to be run.
+
+With all of this done, all we need to do is run the `shadowJar` task to create a working uber (fat) jar! (The jar will be put in `/build/libs/` by default)
+
+Below is a complete `build.gradle`/`build.gradle.kts` file
+
+:::tabs
+
+== Gradle (Groovy)
+
+```groovy
+plugins {
+ id 'java'
+ id "io.github.goooler.shadow" version "8.1.7"
+}
+
+group 'org.example'
+version '1.0-SNAPSHOT'
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ // Change this to the latest version
+ implementation 'net.minestom:minestom-snapshots:'
+}
+
+jar {
+ manifest {
+ // Change this to your main class
+ attributes 'Main-Class': 'org.example.Main'
+ }
+}
+```
+
+== Gradle (Kotlin)
+
+```kts
+plugins {
+ id("java")
+ // If you need Kotlin support, use the kotlin("jvm") plugin
+ id("io.github.goooler.shadow") version "8.1.7"
+}
+
+group = "org.example"
+version = "1.0-SNAPSHOT"
+
+repositories {
+ mavenCentral()
+}
+
+dependencies {
+ // Change this to the latest version
+ implementation("net.minestom:minestom-snapshots:")
+}
+
+tasks.withType {
+ manifest {
+ // Change this to your main class
+ attributes["Main-Class"] = "org.example.Main"
+ }
+}
+```
+
+:::
\ No newline at end of file
diff --git a/docs/setup/your-first-server.md b/docs/starting-out/your-first-server.md
similarity index 52%
rename from docs/setup/your-first-server.md
rename to docs/starting-out/your-first-server.md
index e8075eb..fb0b8b4 100644
--- a/docs/setup/your-first-server.md
+++ b/docs/starting-out/your-first-server.md
@@ -1,16 +1,17 @@
---
-description: Includes everything you need to have your first server running.
+description: Describes how to get a basic server running.
---
# Your first server
-Some things are needed before being able to connect to your Minestom server.
+There are a few steps necessary before you can connect to your Minestom server:
-- Initialize the server
-- Registering events/commands
-- Start the server at the specified port and address
+- Initializing the server
+- Registering your events/commands
+- Creating an instance for players to join
+- Starting the server on a port and address
-Here is a correct example:
+Here is an example of a server without an instance:
::: tabs
=== Java
@@ -20,7 +21,7 @@ public static void main(String[] args) {
// Initialize the server
MinecraftServer minecraftServer = MinecraftServer.init();
- // Register Events (set spawn instance, teleport player at spawn)
+ // Register events (set spawn instance, teleport player at spawn)
// Start the server
minecraftServer.start("0.0.0.0", 25565);
}
@@ -34,7 +35,7 @@ fun main() {
// Initialize the server
val minecraftServer = MinecraftServer.init()
- // Register Events (set spawn instance, teleport player at spawn)
+ // Register events (set spawn instance, teleport player at spawn)
// Start the server
minecraftServer.start("0.0.0.0", 25565)
}
@@ -43,15 +44,13 @@ fun main() {
===
:::
-However even after those steps, you will not be able to connect, because we are missing an instance.
-
-_Please check the_ [_instances_](/docs/world/instances) _and_ [_events_](/docs/feature/events) _pages if you have any questions about how to create/listen to one._
+Add an instance for players to connect to:
::: tabs
=== Java
```java
-Instance instance = // create instance
+Instance instance = // Create an instance
GlobalEventHandler globalEventHandler = MinecraftServer.getGlobalEventHandler();
globalEventHandler.addListener(AsyncPlayerConfigurationEvent.class, event -> {
event.setSpawningInstance(instance);
@@ -62,8 +61,8 @@ globalEventHandler.addListener(AsyncPlayerConfigurationEvent.class, event -> {
=== Kotlin
```kotlin
-val instance = // create instance
-val globalEventHandler = MinecraftServer.getGlobalEventHandler();
+val instance = // Create an instance
+val globalEventHandler = MinecraftServer.getGlobalEventHandler()
globalEventHandler.addListener(AsyncPlayerConfigurationEvent::class.java) { event ->
event.spawningInstance = instance
}
@@ -72,7 +71,9 @@ globalEventHandler.addListener(AsyncPlayerConfigurationEvent::class.java) { even
===
:::
-Here is an example of a working Minestom server
+_Check out the_ [_instances_](/docs/world/instances) _and_ [_events_](/docs/feature/events) _pages to see more on how to create and listen to instances_
+
+Here is an example of a working Minestom server:
::: tabs
=== Java
@@ -126,11 +127,11 @@ import net.minestom.server.coordinate.Pos
fun main() {
// Initialization
- val minecraftServer = MinecraftServer.init();
+ val minecraftServer = MinecraftServer.init()
// Create the instance
- val instanceManager = MinecraftServer.getInstanceManager();
- val instanceContainer = instanceManager.createInstanceContainer();
+ val instanceManager = MinecraftServer.getInstanceManager()
+ val instanceContainer = instanceManager.createInstanceContainer()
// Set the ChunkGenerator
instanceContainer.setGenerator { unit ->
@@ -149,84 +150,3 @@ fun main() {
===
:::
-
-## Building the server JAR
-
-Once you have created your Minestom server, you will probably want to build it as a single JAR. This can be achieved with the Gradle `shadow` plugin.
-
-Side note: For Maven users, you will need the "Shade" plugin. If you use Maven and would like to contribute an example
-it would be appreciated :)
-
-You can find the full documentation for the Shadow plugin [here](https://imperceptiblethoughts.com/shadow/introduction/).
-
-First, let's add the Shadow plugin to our project.
-
-::: warning
-As of the time writing this, the original shadow plugin from johnrengelman has not been updated for Java 21 support, so we'll use a fork in this example.
-:::
-
-With all of this done, all we need to do is run the `shadowJar` task to create a working uber (fat) jar! (The jar will be put in `/build/libs/` by default)
-
-Now, just to be sure that you understood everything, here is a complete `build.gradle`/`build.gradle.kts` file.
-
-:::tabs
-== groovy
-
-```groovy
-plugins {
- id 'java'
- id "io.github.goooler.shadow" version "8.1.7"
-}
-
-group 'org.example'
-version '1.0-SNAPSHOT'
-
-repositories {
- mavenCentral()
- maven { url 'https://jitpack.io' }
-}
-
-dependencies {
- // Change this to the latest version
- implementation 'net.minestom:minestom-snapshots:'
-}
-
-jar {
- manifest {
- // Change this to your main class
- attributes 'Main-Class': 'org.example.Main'
- }
-}
-```
-
-== kotlin
-
-```kts
-plugins {
- id("java")
- // If you need Kotlin support, use the kotlin("jvm") plugin
- id("io.github.goooler.shadow") version "8.1.7"
-}
-
-group = "org.example"
-version = "1.0-SNAPSHOT"
-
-repositories {
- mavenCentral()
- maven(url = "https://jitpack.io")
-}
-
-dependencies {
- // Change this to the latest version
- implementation("net.minestom:minestom-snapshots:")
-}
-
-tasks.withType {
- manifest {
- // Change this to your main class
- attributes["Main-Class"] = "org.example.Main"
- }
-}
-```
-
-:::