Upstream/ViaFabricPlus
1
0
Fork 0
mirror of https://github.com/ViaVersion/ViaFabricPlus.git synced 2024-11-26 12:35:54 +01:00
Code Issues Packages Projects Releases Wiki Activity

Slightly cleanup DEVELOPER_API.md

Browse Source
This commit is contained in:
FlorianMichael 2024-10-31 15:22:11 +01:00
parent f9eceeb16a
commit 214e32658b
No known key found for this signature in database
GPG Key ID: C2FB87E71C425126
1 changed files with 35 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
docs/DEVELOPER_API.md
View File

@ -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
<repositories>
<repository>
@ -35,8 +47,8 @@ dependencies {
<url>https://maven.lenni0451.net/everything</url>
</repository>
<repository>
<id>opencollab-snapshots</id>
<url>https://repo.opencollab.dev/maven-snapshots/</url>
<id>jitpack</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
@ -49,14 +61,17 @@ dependencies {
</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
}
```