Fix #8, more for commands + ItemStacks, warn people about Extension deprecation and fix typos

expansion/extensions.md

@@ -1,5 +1,9 @@
 # Extensions
 
+{% hint style="warning" %}
+Extensions are no longer available in vanilla Minestom. Use the [minestom-ce-extensions](https://github.com/hollow-cube/minestom-ce-extensions) library instead.
+{% endhint %}
+
 Summary:
 
 * [Writing your own extension for Minestom](extensions.md#writing-your-own-extension-for-minestom)

feature/commands.md

@@ -146,4 +146,46 @@ if (result.getType() == CommandResult.Type.SUCCESS) {
 }
 ```
 
+## Custom Tab Completers
+Sometimes you want to have your own custom tab completer. This can easily be done by using the `setSuggestionCallback` method. To add a suggestion use `suggestion.addEntry`, and you can get whatever the sender is typing by using `suggestion.getInput()`.
+
+```java
+// Set the command name
+super("my");
+
+// Define a string argument with a custom suggestion callback
+var customTabCompleterArgument = ArgumentType.String("completion").setSuggestionCallback((sender, context, suggestion) -> {
+    suggestion.addEntry("tab");
+    suggestion.addEntiy("completer");
+
+    // Get the sender's input
+    sender.sendMessage(suggestion.getInput());
+});
+
+addSyntax((sender, context) -> {
+    // Retrieve data from the custom tab completer
+    final String completion = context.get("completion");
+    sender.sendMessage("Your completion was " + completion);
+}, customTabCompleterArgument);
+```
+
+![Basic Tab Completer](../.gitbook/assets/Bildschirmfoto-2024-04-18-um-10.27.58.png)
+
+If you want to go for a more vanilla style of tab completer you can create enum tab completers using the `ArgumentType.Enum` method. Most enums are written upper-cased, but command arguments are usually lower-cased. Making enums lowercase is as easy as using the `setFormat(ArgumentEnum.Format.LOWER_CASED)` method.
+
+```java
+var gamemodeArgument = ArgumentType.Enum("gamemode", GameMode.class);
+
+addSyntax((sender, context) -> {
+    final GameMode gamemode = context.get("gamemode").setFormat(ArgumentEnum.Format.LOWER_CASED);
+
+    Player player = (Player) sender;
+
+    player.setGameMode(gamemode);
+    player.sendMessage("Changed own gamemode to " + String.valueOf(gamemode));
+}, gamemodeArgument);
+```
+
+![Tab Completer using an Enum](../.gitbook/assets/Bildschirmfoto-2024-04-18-um-10.34.53.png)
+
 This tool opens a lot of possibilities, including powerful scripts, remote calls, and an overall easy-to-use interface for all your APIs.

feature/entities/ai.md

@@ -36,7 +36,7 @@ public class ZombieCreature extends EntityCreature {
             List.of(
                 new MeleeAttackGoal(this, 1.6, 20, TimeUnit.SERVER_TICK), // Attack the target
                 new RandomStrollGoal(this, 20) // Walk around
-            )
+            ),
             List.of(
                 new LastEntityDamagerTarget(this, 32), // First target the last entity which attacked you
                 new ClosestEntityTarget(this, 32, entity -> entity instanceof Player) // If there is none, target the nearest player

feature/items.md

@@ -49,3 +49,23 @@ item = item.with(builder -> {
                 .displayName(Component.text("Again..."));
         });
 ```
+
+If you want to use NBT features that are not available within the `ItemStack`, you can simply add your own NBT tags to it:
+
+```java
+ItemStack item = ItemStack.fromNBT(Material.STONE, new NBTCompound().withEntries(
+        NBT.Entry("CustomModelData", new NBTInt(1))
+));
+```
+
+Or just use a full Item NBT:
+
+```java
+var ItemNBT = item.toItemNBT();
+
+ItemStack newItem = ItemStack.fromItemNBT(itemNBT);
+```
+
+{% hint style="warning" %}
+ItemNBT is still marked as Experimental, so be careful when using it
+{% endhint %}

setup/velocity-integration.md

@@ -0,0 +1,111 @@
+---
+description: Step by step guide on how to set up velocity for Minestom
+---
+
+# Velocity Integration
+
+Using Velocity in your Minestom project is very simple, you only need to follow 3 simple steps.
+
+* Install Velocity
+* Set up Velocity
+* Enable Velocity in your Minestom server
+
+## Installing Velocity
+You can download velocity from [the official website](https://papermc.io/downloads/velocity). You need to start it and let it create all necessary files. This shouldn't take too long, and it's recommended to use a starter script.
+
+{% tabs %}
+{% tab title="Bash (macOS and Linux)" %}
+For Linux create a `starter.sh` file and for macOS create a `starter.command` file. Make sure you put them into the same folder as your Velocity jar. Replace `<your file without path>` with the name of your Velocity jar file.
+
+```bash
+#! /bin/bash --
+
+TIME=30
+DIR="$(dirname "$0")"
+SERVER=$(basename $DIR)
+FILENAME="<your file without path>.jar"
+
+echo "$SERVER: starting..."
+cd $DIR
+while :
+do
+	# More memory: change -Xms and -Xmx. Do not change other options.
+	java -Xms512M -Xmx512M -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -jar $FILENAME
+	echo "$SERVER: Java stopped or crashed. Waiting $TIME seconds..."
+	sleep $TIME
+done
+```
+{% endtab %}
+{% tab title="Batch (Windows)" %}
+{% hint style="warning" %}
+This has not been tested yet. If you own a Windows computer, try it and check if it works.
+{% endhint %}
+
+Create a `starter.bat` file in the same folder as your Velocity server jar. Replace `<your file without path>` with the name of your Velocity server jar file.
+
+```batch
+@echo off
+
+set time=30
+set dir=%~dp0
+set filename="<your file without path>.jar"
+
+echo "%dir%: starting..."
+cd %dir%
+:loop
+:: More memory: change -Xms and -Xmx. Do not change other options.
+java -Xms512M -Xmx512M -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -jar %filename%
+echo "%dir%: Java stopped or crashed."
+timeout %time% > NUL
+goto loop
+```
+{% endtab %}
+{% endtabs %}
+
+After you have started Velocity you should see a few new files and folders appearing such as `velocity.toml` and `forwarding.secret`.
+
+## Setting up Velocity
+The default settings in `velocity.toml` should be fine, but there are some things we need to change. In the `[servers]` category you'll see some pre-defined servers, which you most likely need to change or remove. In this example we will remove all servers except for `lobby`. Change `lobby`'s port to the port you defined when binding your Minestom server. Here's an example:
+
+```toml
+[servers]
+# Configure your servers here. Each key represents the server's name, and the value
+# represents the IP address of the server to connect to.
+lobby = "127.0.0.1:25565"
+
+# In what order we should try servers when a player logs in or is kicked from a server.
+try = [
+    "lobby"
+]
+
+[forced-hosts]
+# Configure your forced hosts here.
+"example.com" = [
+    "lobby"
+]
+```
+
+Make sure to change `player-info-forwarding-mode` to `MODERN`. You can now save the `velocity.toml` file and move onto the `forwarding.secret` file. This is a text file, so you can open it using your preferred text editor. We highly recommend changing the secret instead of using the default. You will need this secret later, so don't forget it. **Do not give out your secret to anybody!** The secret is used to ensure that player info forwarded by Velocity comes from your proxy and not from someone pretending to run Velocity. [More information](https://docs.papermc.io/velocity/configuration)
+
+## Setting up the Minestom server
+In your main file, just before binding the server, use the `VelocityProxy.enable()` method. If you use `MojangAuth` you will need to remove that, but not to worry: your server will not be in offline mode. The proxy makes sure all connections are secure.
+
+```java
+// Don't use: MojangAuth.init();
+VelocityProxy.enable("very secret secret");
+minecraftServer.start("0.0.0.0", 25565);
+```
+
+You're done! You can now start the proxy and the Minestom server.
+
+## Troubleshooting
+* Connection lost: "Invalid proxy response!"\
+You entered the wrong port, IP address or didn't start the proxy. You can find the port of the proxy in the `velocity.toml` under `bind`
+
+* Connection lost: "Unable to connect you to (server). Invalid proxy response!"\
+Make sure you changed `player-info-forwarding-mode` to `MODERN`
+
+* Connection lost: "Unable to connect you to (server). Please try again later."\
+You didn't set up the proxy correctly (in the `velocity.toml`) file. Make sure it has the correct port and IP address, the Minestom server is running, and you are using the correct secret.
+
+If you still have issues you can join the [Discord server](https://discord.gg/Pt9Mgd9cgR)

setup/your-first-server.md

@@ -46,6 +46,7 @@ import net.minestom.server.event.GlobalEventHandler;
 import net.minestom.server.event.player.AsyncPlayerConfigurationEvent;
 import net.minestom.server.instance.*;
 import net.minestom.server.instance.batch.ChunkBatch;
+import net.minestom.server.instance.LightingChunk;
 import net.minestom.server.instance.block.Block;
 import net.minestom.server.coordinate.Pos;
 import net.minestom.server.world.biomes.Biome;
@@ -71,6 +72,10 @@ public class MainDemo {
             event.setSpawningInstance(instanceContainer);
             player.setRespawnPoint(new Pos(0, 42, 0));
         });
+
+        // Fix lighting
+        instanceContainer.setChunkSupplier(LightingChunk::new);
+
         // Start the server on port 25565
         minecraftServer.start("0.0.0.0", 25565);
     }