From c94421bfd0d7d4be6ac9381c32083baa405298d2 Mon Sep 17 00:00:00 2001 From: FlorianMichael <60033407+FlorianMichael@users.noreply.github.com> Date: Mon, 27 Nov 2023 22:02:41 +0100 Subject: [PATCH] Update documentation folder --- README.md | 14 +-- docs/DEVELOPER_API.md | 89 +++++++----------- docs/UPDATE_INSTRUCTIONS.md | 59 ++++++++++++ docs/USAGE.md | 37 ++++++-- docs/preview/betacraft.png | Bin 391349 -> 152834 bytes docs/preview/classicube-login.png | Bin 353784 -> 0 bytes docs/preview/classicube.png | Bin 402367 -> 158362 bytes docs/preview/classicube_login.png | Bin 0 -> 115062 bytes docs/preview/debug_hud.png | Bin 0 -> 22127 bytes docs/preview/force.png | Bin 141093 -> 763707 bytes docs/preview/protocol.png | Bin 380351 -> 133341 bytes docs/preview/settings.png | Bin 406075 -> 152342 bytes .../fixes/data/ItemRegistryDiff.java | 22 ++++- .../fixes/data/ResourcePackHeaderDiff.java | 1 + .../mixin/base/integration/MixinDebugHud.java | 2 +- .../screen/MixinConnectScreen_1.java | 25 ++--- 16 files changed, 155 insertions(+), 94 deletions(-) create mode 100644 docs/UPDATE_INSTRUCTIONS.md delete mode 100644 docs/preview/classicube-login.png create mode 100644 docs/preview/classicube_login.png create mode 100644 docs/preview/debug_hud.png diff --git a/README.md b/README.md index d16fe7b5..92b61568 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ # Why another protocol translator? -ViaFabricPlus is a deep integration of ViaVersion on the Fabric platform, unlike the classic Via* implementations, ViaFabricPlus implements many changes that can't be fixed on protocol level (old animations, old movement/swimming, collisions and general rendering changes). +ViaFabricPlus is a deep integration of ViaVersion on the Fabric platform, it implements many changes that can't be fixed on protocol level (old animations, old movement/swimming, collisions and general rendering changes). At the time of writing, VFP is the only protocol translation platform for the client with which you can play on all Minecraft multiplayer versions with many QoL features and get the feel of the old versions. ### Supported Server versions - Release (1.0.0 - 1.20.3 snapshot) @@ -60,17 +60,9 @@ At the time of writing, VFP is the only protocol translation platform for the cl # For developers and translators -Contributions in the form of pull requests are always welcome, please just stick to my code style and make sure your code is easy to update and compatible with other mods. +### Contributions in the form of pull requests are always welcome, [here](docs/UPDATE_INSTRUCTIONS.md) are some guidelines for contributing to the project. +#### A detailed TODO list can be found at the class header of [this](https://github.com/ViaVersion/ViaFabricPlus/blob/main/src/main/java/de/florianmichael/viafabricplus/ViaFabricPlus.java) file. -### Translations -Translations for other languages are always welcome, in **~/resources/assets/viafabricplus/lang** you can find all translations,
-if you know a language well, feel free to make a PR and add translations for that language
- -### Changes to the code base -If you want to make changes to the code base, please make sure that your changes are compatible with other mods and that they are easy to update. -Also, please follow my code style and make sure that cursed parts of your code are documented :tm: - -A detailed TODO List can be found at the class header of [this](https://github.com/ViaVersion/ViaFabricPlus/blob/main/src/main/java/de/florianmichael/viafabricplus/ViaFabricPlus.java) file. ### Dependencies For compiling only! **You do not need to install these!** diff --git a/docs/DEVELOPER_API.md b/docs/DEVELOPER_API.md index 70cd9f17..2e16f057 100644 --- a/docs/DEVELOPER_API.md +++ b/docs/DEVELOPER_API.md @@ -1,87 +1,64 @@ # Developer API -There is no real addon base, to create addons you can simply use the event system, which uses Fabric's Event-API. -```java -public class ViaFabricPlusExampleAddon implements ClientModInitializer { +ViaFabricPlus provides various events and APIs for developers to use. This page explains how to use them. - @Override - public void onInitializeClient() { - ChangeProtocolVersionCallback.EVENT.register(versionEnum -> { - System.out.println("Version changed to " + versionEnum.getName()); - }); - } -} +## Events +ViaFabricPlus events are using the [Fabric Event API](https://fabricmc.net/wiki/tutorial:events). You can register to them like this: +```java +ChangeProtocolVersionCallback.EVENT.register(versionEnum -> { + System.out.println("Version changed to " + versionEnum.getName()); +}); ``` -#### ViaFabricPlus has 7 events at the moment: +### ViaFabricPlus has 7 events at the moment | 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. | -| FinishMinecraftLoadCallback | Called when Minecraft is finished with loading all its components | -| FinishViaVersionStartupCallback | Called when ViaVersion is loaded and ready to use | -| InitializeSettingsCallback | Called after the default setting groups are loaded and before the setting config is loaded | +| DisconnectCallback | Called when the user disconnects from a server. | +| 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 | | LoadClassicProtocolExtensionCallback | Called when the classic server sends the protocol extensions (only in **c0.30 CPE**) | -| PreLoadCallback | Called before everything (Pre-pre load) | -| DisconnectConnectionCallback | Called when the user disconnects from a server. | +| LoadCallback | Called at the earliest point ViaFabricPlus is injecting too | -### General API -#### Add CustomPayload channels for versions below 1.13 +## 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"); ``` -#### Get the release version of a material: +### Check if an item exists in a specific version ```java -final VersionRange range = ItemReleaseVersionDefinition.INSTANCE.getItemMap().get(Items.WRITABLE_BOOK); // If an item does not appear in the item map, it has always existed +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(VersionEnum.r1_8))) { + // Do something +} ``` -#### Creating own settings for the settings screen: +### Creating own settings for the settings screen ```java public class ExampleSettingGroup extends SettingGroup { - public static final ExampleSettingGroup INSTANCE = new ExampleSettingGroup(); + private static final ExampleSettingGroup instance = new ExampleSettingGroup(); - public final BooleanSetting test = new BooleanSetting("Test", false); + public final BooleanSetting test = new BooleanSetting(this, Text.of("Test"), false); public ExampleSettingGroup() { super("Example"); } + + public static ExampleSettingGroup global() { + return instance; + } } ``` -and then you register the setting group in your onLoad method: + +and then you register the setting group in your onLoad method ```java -PreLoadCallback.EVENT.register(() -> { - ViaFabricPlus.INSTANCE.getSettingsSystem().addGroup(ExampleSettingGroup.INSTANCE); +RegisterSettingsCallback.EVENT.register(state -> { + if (state == RegisterSettingsCallback.State.POST) { + ViaFabricPlus.global().getSettingsManager().addGroup(ExampleSettingGroup.INSTANCE); + } }); ``` - -#### Implementing custom classic protocol extensions: -```java -public class ExampleExtensionSupport implements ClientModInitializer { - - public static ClientboundPacketsc0_30cpe EXT_CLICK_DISTANCE; - - @Override - public void onInitializeClient() { - PreLoadCallback.EVENT.register(() -> { - CustomClassicProtocolExtensions.allowExtension(ClassicProtocolExtension.CLICK_DISTANCE); // Register extension as supported - - EXT_CLICK_DISTANCE = CustomClassicProtocolExtensions.createNewPacket(ClassicProtocolExtension.CLICK_DISTANCE, 0x12, (user, buf) -> buf.readShort()); - }); - - FinishViaLoadingBaseStartupCallback.EVENT.register(() -> { - Via.getManager().getProtocolManager().getProtocol(Protocolc0_30toc0_30cpe.class).registerClientbound(EXT_CLICK_DISTANCE, null, new PacketHandlers() { - @Override - protected void register() { - handler(wrapper -> { - wrapper.cancel(); - final short distance = wrapper.read(Type.SHORT); - // Do your stuff... - }); - } - }, true); - }); - } -} -``` \ No newline at end of file diff --git a/docs/UPDATE_INSTRUCTIONS.md b/docs/UPDATE_INSTRUCTIONS.md new file mode 100644 index 00000000..699b4c5d --- /dev/null +++ b/docs/UPDATE_INSTRUCTIONS.md @@ -0,0 +1,59 @@ +# Updating instructions for the project + +## Update translation files +Translation files are located in `src/main/resources/assets/viafabricplus/lang/`. To update them, you need to do the following: +1. Copy the `en_us.json` file and rename it to the language code of the language you want to update (e.g. `de_de.json` for German) +2. Translate all values in the file to the language you want to update +3. Do not change the keys of the values, only the values themselves +4. Do not change the formatting of the file (e.g. the spaces between the keys and values or the order of the keys) +5. Try to be consistent with Minecraft language files. +6. Take a look at UN's guidelines for Gender-inclusive language: https://www.un.org/en/gender-inclusive-language/guidelines.shtml +7. Create a pull request and wait for it to be reviewed and merged. +8. You're done, congrats! + +## Add a new feature or fix a bug +1. Create a new branch for your feature/bugfix (e.g. `feature/fix-xyz` or `fix/fix-xyz`) +2. Implement your feature/bugfix and make sure it works correctly +3. Clean your code and make sure it is readable and understandable (e.g. use proper variable names) +4. Use the Google java code style (https://google.github.io/styleguide/javaguide.html) and format your code accordingly +5. If you're changing API, make sure to update the documentation in the `docs` folder, add javadocs to your code and don't break backwards compatibility if not necessary +6. Increment the version number in `gradle.properties` by at least a patch version (e.g. 1.0.0 -> 1.0.1) +7. Create a pull request and wait for it to be reviewed and merged. +8. You're done, congrats! + +## Update to a new Minecraft version +1. Update all upstream versions in `gradle.properties`. The main versions you need to update are: + - `minecraft_version` + - `yarn_mappings` + - `loader_version` + - `fabric_api_version` + - `viaversion_version` + - `viabackwards_version` + - `mod_menu_version` +2. Update the `NATIVE_VERSION` field in the ProtocolHack class to the new version +3. Check all mixins in the injection package if they still apply correctly, here is a list of some critical ones: + - `MixinClientPlayerEntity#removeBl8Boolean` + - `MixinClientWorld#tickEntity` and `MixinClientWorld#tickPassenger` + - `MixinPlayer#getBlockBreakingSpeed` +4. Decompile the game source code with the tool of your choice. +5. Check all data dumps and diffs in the fixes/data package and update them if necessary, here is a list of some critical ones: + - `ResourcePackHeaderDiff` (add the new version at the top of the list) + - `ItemRegistryDiff` (add all new items/blocks added in the new version) +6. Diff the game code with the code of the previous version (e.g. using git) and implement all changes that could be relevant for ViaFabricPlus, those are: + - General logic changes (e.g. `if (a && b)` -> `if (b || a)`) + - Changes to the movement code (e.g. `player.yaw` -> `player.headYaw`) + - Networking changes (e.g. sending a new packet / changing the packet structure) + - Changes to visuals (e.g. animation changes) + - Note: ViaVersion already implements most gameplay related changes for us, but you should always check for edge-cases. Since ViaVersion + is primarily a server side plugin, it does not take care of client-side related / deeper changes. + + => If you are unsure if a change is relevant, ask in the ViaVersion discord, in general you should only implement changes + which could be detected by a server side anti cheat. +7. Check the ViaVersion/upstream protocol implementation for issues and report them if necessary or if these issues can't be fixed, + without tons of work, implement a workaround in ViaFabricPlus. +8. Run the game and check all GUIs and other visuals for issues. +9. Clean your code and make sure it is readable and understandable, clientside fixes are sorted by their protocol versions, having + newer fixes at the top of the file. +10. Increment the version number in `gradle.properties` by at least a minor version (e.g. 1.0.0 -> 1.1.0) +11. Create a pull request and wait for it to be reviewed and merged. +12. You're done, congrats! \ No newline at end of file diff --git a/docs/USAGE.md b/docs/USAGE.md index 93180e5a..a798decb 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -1,7 +1,9 @@ -# Settings and GUI -In the multiplayer screen you will find the ViaFabricPlus button in the upper left corner by default, it is the main button, -click on it, and you will see the Protocol selection, there you can choose the Minecraft version you want to connect to, -in the upper left corner you can go to the Settings. +# Usage for ViaFabricPlus + +## Introduction +At the top left of the multiplayer screen is the ViaFabricPlus button, with it you can enter the main menu of the mod +where you can change the settings and set the protocol version, the position of the button can be changed in the +Settings -> General -> multiplayer screen button orientation. ![](preview/multiplayer.png) ![](preview/protocol.png) @@ -18,18 +20,32 @@ You can use the ViaVersion commands with **/viafabricplus** or **/viaversion**, - **/viafabricplus settime