Upstream/ViaFabricPlus
1
0
Fork 0
mirror of https://github.com/ViaVersion/ViaFabricPlus.git synced 2025-01-06 19:18:25 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update API documentation

Browse Source
This commit is contained in:
FlorianMichael 2024-12-28 12:26:06 +01:00
parent 86060b4d62
commit 1bc66814e9
No known key found for this signature in database
GPG Key ID: C2FB87E71C425126
3 changed files with 61 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

37
api-legacy/src/main/java/de/florianmichael/viafabricplus/event/EventBridge.java
View File

@ -1,37 +0,0 @@
/*
* This file is part of ViaFabricPlus - https://github.com/ViaVersion/ViaFabricPlus
* Copyright (C) 2021-2024 the original authors
* - FlorianMichael/EnZaXD <florian.michael07@gmail.com>
* - RK_01/RaphiMC
* Copyright (C) 2023-2024 ViaVersion and contributors
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
package de.florianmichael.viafabricplus.event;
import com.viaversion.viafabricplus.ViaFabricPlus;
import com.viaversion.viafabricplus.api.events.LoadingCycleCallback;
import net.fabricmc.fabric.api.event.Event;
import net.fabricmc.fabric.api.event.EventFactory;
import java.util.function.Function;
public class EventBridge {
public static <T> Event<T> createArrayBacked(Class<? super T> type, Function<T[], T> invokerFactory) {
return EventFactory.createArrayBacked(type, invokerFactory);
}
}

87
docs/DEVELOPER_API.md
View File

@ -5,6 +5,9 @@ ViaFabricPlus in your project comes with some requirements:
- Fabric loom setup (As ViaFabricPlus is a Minecraft mod and has no API-only dependency like other projects)
## How to include the mod as dependency
If you are targetting to only use the provided API, you should include the ```viafabricplus-api``` artifact. For including the internals use
```viafabricplus```. Including the internals will also provide the legacy compatibility layer.
### Gradle
```groovy
repositories {
@ -58,43 +61,71 @@ dependencies {
</dependencies>
```
## 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).
## Using the API
Get the general API using ``ViaFabricPlus.getImpl()`` which will return a ``ViaFabricPlusBase`` interface reflecting API functions for mods to use.
All functions provided there are safe to use and will most likely never be removed.
#### Example
```java
ChangeProtocolVersionCallback.EVENT.register((oldVersion, newVersion) -> {
System.out.println("Version changed to " + newVersion.getName());
final ViaFabricPlusBase platform = ViaFabricPlus.getImpl();
```
## Using event callbacks
The API provides two event callbacks which can be used:
- ``LoadingCycleCallback`` fired in various loading stages of ViaFabricPlus such as config or settings loading.
- ``ChangeProtocolVersionCallback`` fired when the user changes the target version in the screen, or if the user joins a server with a different version.
Event callbacks can be registered through the API:
```java
final ViaFabricPlusBase platform = ViaFabricPlus.getImpl();
platform.registerOnChangeProtocolVersionCallback((oldVersion, newVersion) -> {
// Called when the target version changes
});
```
### 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. |
| DisconnectCallback | Called when the user disconnects from a server |
| LoadCallback | Called at the earliest point ViaFabricPlus is injecting too |
| LoadClassicProtocolExtensionCallback | Called when the classic server sends the protocol extensions (only in **c0.30 CPE**) |
| PostGameLoadCallback | Called when Minecraft is finished with loading all its components |
| PostViaVersionLoadCallback | Called when ViaVersion is loaded and ready to use |
| 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 |
### Other API calls
### Using the loading cycle callback
ViaFabricPlus uses [ViaVersion](https://github.com/ViaVersion/ViaVersion) for protocol translation, so the ViaVersion API can be used.
As your mod might load after ViaFabricPlus, you will need to register the loading cycle callback inside a `ViaFabricPlusLoadEntrypoint` marked as `viafabricplus`
in your `fabric.mod.json` file. The entrypoint also acts as `INITAL_LOAD` stage.
The general API point 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);
}
public class Example implements ViaFabricPlusLoadEntrypoint {
// Gets the ViaVersion user connection object for raw packet sending using ViaVersion API
final UserConnection user = ProtocolTranslator.getPlayNetworkUserConnection();
if (user == null) {
// Mod not active
@Override
public void onPlatformLoad(ViaFabricPlusBase platform) {
platform.registerLoadingCycleCallback(stage -> {
if (stage == LoadingCycleCallback.LoadingCycle.PRE_SETTINGS_LOAD) {
// Called before the settings are loaded
} else if (stage == LoadingCycleCallback.LoadingCycle.POST_SETTINGS_LOAD) {
// Called after the settings are loaded
} else if (stage == LoadingCycleCallback.LoadingCycle.PRE_FILES_LOAD) {
// Called before the files are loaded
} else if (stage == LoadingCycleCallback.LoadingCycle.POST_FILES_LOAD) {
// Called after the files are loaded
} else if (stage == LoadingCycleCallback.LoadingCycle.PRE_VIAVERSION_LOAD) {
// Called before ViaVersion is loaded
} else if (stage == LoadingCycleCallback.LoadingCycle.POST_VIAVERSION_LOAD) {
// Called after ViaVersion is loaded
} else if (stage == LoadingCycleCallback.LoadingCycle.FINAL_LOAD) {
// Called after everything is loaded
} else if (stage == LoadingCycleCallback.LoadingCycle.POST_GAME_LOAD) {
// Called after the game is loaded
}
});
}
}
```
## More extensive API
For any version specific functionality, ViaFabricPlus provides common API functions. ViaFabricPlus uses [ViaVersion](https://github.com/ViaVersion/ViaVersion)
for protocol translation, so the ViaVersion API can be used as well.
### Getting the current target version
```java
final ProtocolVersion version = ViaFabricPlus.getImpl().getTargetVersion();
```

4
src/main/java/com/viaversion/viafabricplus/ViaFabricPlusImpl.java
View File

@ -103,9 +103,9 @@ public final class ViaFabricPlusImpl implements ViaFabricPlusBase {
private CompletableFuture<Void> loadingFuture;
public void init() {
ViaFabricPlus.init(this);
ViaFabricPlus.init(INSTANCE);
FabricLoader.getInstance().getEntrypointContainers("viafabricplus", ViaFabricPlusLoadEntrypoint.class).forEach(container -> {
container.getEntrypoint().onPlatformLoad(this);
container.getEntrypoint().onPlatformLoad(INSTANCE);
});
// Create the directory if it doesn't exist