From 214e32658bd5c501bbf97f4546012df4167e30a9 Mon Sep 17 00:00:00 2001 From: FlorianMichael Date: Thu, 31 Oct 2024 15:22:11 +0100 Subject: [PATCH] Slightly cleanup DEVELOPER_API.md --- docs/DEVELOPER_API.md | 77 ++++++++++++++++++++----------------------- 1 file changed, 35 insertions(+), 42 deletions(-) diff --git a/docs/DEVELOPER_API.md b/docs/DEVELOPER_API.md index 9f1524c2..de51d95b 100644 --- a/docs/DEVELOPER_API.md +++ b/docs/DEVELOPER_API.md @@ -1,7 +1,14 @@ # Developer API -ViaFabricPlus provides various events and APIs for developers to use. This page explains how to use them. +ViaFabricPlus provides events and various utility functions for other mods to interface with it. Note that including +ViaFabricPlus in your project comes with some requirements: +- The target version is Java 17 +- Fabric loom setup (As ViaFabricPlus is a Minecraft mod and has no API-only dependency like other projects) -## Include via Gradle/Maven +Since the API is not exposed as standalone submodule (yet), functions that shouldn't be used are marked with +`ApiStatus.Internal`. Further information about certain functions can be found in the Javadoc in the corresponding file. + +## How to include the mod as dependency +### Gradle ```groovy repositories { mavenCentral() @@ -14,8 +21,12 @@ repositories { url = "https://maven.lenni0451.net/everything" } maven { - name = "OpenCollab Snapshots" - url = "https://repo.opencollab.dev/maven-snapshots/" + name = "Jitpack" + url = "https://jitpack.io" + + content { + includeGroup "com.github.Oryxel" + } } } @@ -24,6 +35,7 @@ dependencies { } ``` +### Maven ```xml @@ -35,8 +47,8 @@ dependencies { https://maven.lenni0451.net/everything - opencollab-snapshots - https://repo.opencollab.dev/maven-snapshots/ + jitpack + https://jitpack.io @@ -49,14 +61,17 @@ dependencies { ``` -## Events -ViaFabricPlus events are using the [Fabric Event API](https://fabricmc.net/wiki/tutorial:events). You can register to them like this: +## Interacting with Events +ViaFabricPlus events are the intended way of interacting with the mod. +Events are fired in various situations and are using the [Fabric Event API](https://fabricmc.net/wiki/tutorial:events). + +#### Example ```java ChangeProtocolVersionCallback.EVENT.register((oldVersion, newVersion) -> { System.out.println("Version changed to " + newVersion.getName()); }); ``` -### ViaFabricPlus has 8 events at the moment +### List of events/callbacks | Callback class name | Description | |--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ChangeProtocolVersionCallback | Called when the user changes the target version in the screen, or if you connect to a server for which a specific version has been selected, you disconnect, the event for the actual version is also called. | @@ -68,43 +83,21 @@ ChangeProtocolVersionCallback.EVENT.register((oldVersion, newVersion) -> { | RegisterSettingsCallback | Called after the default setting groups are loaded and before the setting config is loaded | | LoadSaveFilesCallback | Called before and after the save files are loaded | -## Get and set the current protocol version +### Other API calls + +ViaFabricPlus uses [ViaVersion](https://github.com/ViaVersion/ViaVersion) for protocol translation, so the ViaVersion API can be used. + +The general API endpoint for ViaFabricPlus specifics is `ProtocolTranslator` ```java +// Get and change the current selected version final ProtocolVersion version = ProtocolTranslator.getTargetVersion(); if (version == ProtocolVersion.v1_8) { ProtocolTranslator.setTargetVersion(ProtocolVersion.v1_9); } -``` -## Get a Minecraft ClientConnection by channel -```java -final ClientConnection connection = channel.attr(ProtocolTranslator.CLIENT_CONNECTION_ATTRIBUTE_KEY).get(); -``` - -## Interact with UserConnection objects -```java -// If ViaVersion is translating, this field will return the user connection of the client -final UserConnection userConnection = ProtocolTranslator.getPlayNetworkUserConnection(); - -// If you need a dummy user connection for testing, you can use this method -final UserConnection cursedDummy = ProtocolTranslator.createDummyUserConnection(ProtocolTranslator.NATIVE_VERSION, ProtocolVersion.v1_18_2); -// The cursedDummy field now contains all protocols from the native version to 1.18.2 -``` - -## ViaVersion internals -### Add CustomPayload channels for versions below 1.13 -In order to receive custom payloads with custom channels in versions below 1.13, you need to register them, that's what you do: -```java -Protocol1_13To1_12_2.MAPPINGS.getChannelMappings().put("FML|HS", "fml:hs"); -``` - -### Check if an item exists in a specific version -```java -final VersionRange range = ItemRegistryDiff.ITEM_DIFF.get(Items.WRITABLE_BOOK); // If an item does not appear in the item map, it has always existed - -// The Range class then contains all versions in which the item occurs. -// https://github.com/ViaVersion/ViaLoader -if (ItemRegistryDiff.contains(Items.STONE, VersionRange.andOlder(ProtocolVersion.v1_8))) { - // Do something +// Gets the ViaVersion user connection object for raw packet sending using ViaVersion API +final UserConnection user = ProtocolTranslator.getPlayNetworkUserConnection(); +if (user == null) { + // Mod not active } -``` +``` \ No newline at end of file