From 1b15f3058f8ce892cebc3ebbe789a0c8e7ded47c Mon Sep 17 00:00:00 2001 From: rtm516 Date: Tue, 21 Apr 2020 06:28:44 +0100 Subject: [PATCH] Javadoc a bit of Geyser (#392) * A bunch of javadoc comments * Cleaned up javadocs --- .../java/org/geysermc/common/AuthType.java | 7 +++ .../java/org/geysermc/common/ChatColor.java | 14 +++++ .../common/bootstrap/IGeyserBootstrap.java | 21 ++++++++ .../common/command/ICommandManager.java | 7 +++ .../living/animal/TropicalFishEntity.java | 9 +++- .../JavaServerDeclareCommandsTranslator.java | 37 +++++++++++-- .../connector/utils/DimensionUtils.java | 6 +++ .../geysermc/connector/utils/EntityUtils.java | 19 +++++++ .../geysermc/connector/utils/FileUtils.java | 53 ++++++++++++++++--- .../geysermc/connector/utils/LocaleUtils.java | 43 ++++++++++++++- .../geysermc/connector/utils/MathUtils.java | 6 +++ .../connector/utils/MessageUtils.java | 40 +++++++++++++- .../geysermc/connector/utils/SkinUtils.java | 12 +++++ .../org/geysermc/connector/utils/Toolbox.java | 6 +++ .../geysermc/connector/utils/WebUtils.java | 12 +++++ 15 files changed, 280 insertions(+), 12 deletions(-) diff --git a/common/src/main/java/org/geysermc/common/AuthType.java b/common/src/main/java/org/geysermc/common/AuthType.java index bec51560..8edbc4d5 100644 --- a/common/src/main/java/org/geysermc/common/AuthType.java +++ b/common/src/main/java/org/geysermc/common/AuthType.java @@ -14,6 +14,13 @@ public enum AuthType { return id < VALUES.length ? VALUES[id] : OFFLINE; } + /** + * Convert the AuthType string (from config) to the enum, OFFLINE on fail + * + * @param name AuthType string + * + * @return The converted AuthType + */ public static AuthType getByName(String name) { String upperCase = name.toUpperCase(); for (AuthType type : VALUES) { diff --git a/common/src/main/java/org/geysermc/common/ChatColor.java b/common/src/main/java/org/geysermc/common/ChatColor.java index e60012e7..8868b063 100644 --- a/common/src/main/java/org/geysermc/common/ChatColor.java +++ b/common/src/main/java/org/geysermc/common/ChatColor.java @@ -51,6 +51,13 @@ public class ChatColor { public static final String ITALIC = ESCAPE + "o"; public static final String RESET = ESCAPE + "r"; + /** + * Convert chat colour codes to terminal colours + * + * @param string The text to replace colours for + * + * @return A string ready for terminal printing + */ public static String toANSI(String string) { string = string.replace(BOLD, (char) 0x1b + "[1m"); string = string.replace(OBFUSCATED, (char) 0x1b + "[5m"); @@ -81,6 +88,13 @@ public class ChatColor { return message.replace(color, ESCAPE); } + /** + * Remove all colour formatting tags from a message + * + * @param message Message to remove colour tags from + * + * @return The sanitised message + */ public static String stripColors(String message) { return message = message.replaceAll("(&([a-fk-or0-9]))","").replaceAll("(ยง([a-fk-or0-9]))","").replaceAll("s/\\x1b\\[[0-9;]*[a-zA-Z]//g",""); } diff --git a/common/src/main/java/org/geysermc/common/bootstrap/IGeyserBootstrap.java b/common/src/main/java/org/geysermc/common/bootstrap/IGeyserBootstrap.java index 280723aa..5df61953 100644 --- a/common/src/main/java/org/geysermc/common/bootstrap/IGeyserBootstrap.java +++ b/common/src/main/java/org/geysermc/common/bootstrap/IGeyserBootstrap.java @@ -31,13 +31,34 @@ import org.geysermc.common.logger.IGeyserLogger; public interface IGeyserBootstrap { + /** + * Called when the GeyserBootstrap is enabled + */ void onEnable(); + /** + * Called when the GeyserBootstrap is disabled + */ void onDisable(); + /** + * Returns the current GeyserConfig + * + * @return The current GeyserConfig + */ IGeyserConfiguration getGeyserConfig(); + /** + * Returns the current GeyserLogger + * + * @return The current GeyserLogger + */ IGeyserLogger getGeyserLogger(); + /** + * Returns the current GeyserCommandManager + * + * @return The current GeyserCommandManager + */ ICommandManager getGeyserCommandManager(); } diff --git a/common/src/main/java/org/geysermc/common/command/ICommandManager.java b/common/src/main/java/org/geysermc/common/command/ICommandManager.java index 53e85fc7..f46dfafc 100644 --- a/common/src/main/java/org/geysermc/common/command/ICommandManager.java +++ b/common/src/main/java/org/geysermc/common/command/ICommandManager.java @@ -27,5 +27,12 @@ package org.geysermc.common.command; public interface ICommandManager { + /** + * Returns the description of the given command + * + * @param command Command to get the description for + * + * @return Command description + */ String getDescription(String command); } diff --git a/connector/src/main/java/org/geysermc/connector/entity/living/animal/TropicalFishEntity.java b/connector/src/main/java/org/geysermc/connector/entity/living/animal/TropicalFishEntity.java index 5addcc2e..3ded4cbf 100644 --- a/connector/src/main/java/org/geysermc/connector/entity/living/animal/TropicalFishEntity.java +++ b/connector/src/main/java/org/geysermc/connector/entity/living/animal/TropicalFishEntity.java @@ -44,8 +44,8 @@ public class TropicalFishEntity extends AbstractFishEntity { @Override public void updateBedrockMetadata(EntityMetadata entityMetadata, GeyserSession session) { if (entityMetadata.getId() == 16) { - // Still not always the right model and colour is broken TropicalFishVariant variant = TropicalFishVariant.fromVariantNumber((int) entityMetadata.getValue()); + metadata.put(EntityData.VARIANT, variant.getShape()); // Shape 0-1 metadata.put(EntityData.MARK_VARIANT, variant.getPattern()); // Pattern 0-5 metadata.put(EntityData.COLOR, variant.getBaseColor()); // Base color 0-15 @@ -80,6 +80,13 @@ public class TropicalFishEntity extends AbstractFishEntity { private byte baseColor; private byte patternColor; + /** + * Convert the variant number from Java into separate values + * + * @param varNumber Variant number from Java edition + * + * @return The variant converted into TropicalFishVariant + */ public static TropicalFishVariant fromVariantNumber(int varNumber) { return new TropicalFishVariant((varNumber & 0xFF), ((varNumber >> 8) & 0xFF), (byte) ((varNumber >> 16) & 0xFF), (byte) ((varNumber >> 24) & 0xFF)); } diff --git a/connector/src/main/java/org/geysermc/connector/network/translators/java/JavaServerDeclareCommandsTranslator.java b/connector/src/main/java/org/geysermc/connector/network/translators/java/JavaServerDeclareCommandsTranslator.java index a383c5cc..edc20a64 100644 --- a/connector/src/main/java/org/geysermc/connector/network/translators/java/JavaServerDeclareCommandsTranslator.java +++ b/connector/src/main/java/org/geysermc/connector/network/translators/java/JavaServerDeclareCommandsTranslator.java @@ -55,7 +55,7 @@ public class JavaServerDeclareCommandsTranslator extends PacketTranslator children; + /** + * Create a new parameter info object + * + * @param paramNode CommandNode the parameter is for + * @param paramData The existing parameters for the command + */ public ParamInfo(CommandNode paramNode, CommandParamData paramData) { this.paramNode = paramNode; this.paramData = paramData; this.children = new ArrayList<>(); } + /** + * Build the array of all the child parameters (recursive) + * + * @param allNodes Every command node + */ public void buildChildren(CommandNode[] allNodes) { int enumIndex = -1; @@ -247,6 +273,11 @@ public class JavaServerDeclareCommandsTranslator extends PacketTranslator getTree() { List treeParamData = new ArrayList<>(); diff --git a/connector/src/main/java/org/geysermc/connector/utils/DimensionUtils.java b/connector/src/main/java/org/geysermc/connector/utils/DimensionUtils.java index 199c5a5c..9d874f13 100644 --- a/connector/src/main/java/org/geysermc/connector/utils/DimensionUtils.java +++ b/connector/src/main/java/org/geysermc/connector/utils/DimensionUtils.java @@ -61,6 +61,12 @@ public class DimensionUtils { session.getUpstream().sendPacket(stopSoundPacket); } + /** + * Map the Java edition dimension IDs to Bedrock edition + * + * @param javaDimension Dimension ID to convert + * @return Converted Bedrock edition dimension ID + */ public static int javaToBedrock(int javaDimension) { switch (javaDimension) { case -1: diff --git a/connector/src/main/java/org/geysermc/connector/utils/EntityUtils.java b/connector/src/main/java/org/geysermc/connector/utils/EntityUtils.java index ec1ff451..79ce9e8b 100644 --- a/connector/src/main/java/org/geysermc/connector/utils/EntityUtils.java +++ b/connector/src/main/java/org/geysermc/connector/utils/EntityUtils.java @@ -32,6 +32,12 @@ import org.geysermc.connector.entity.type.EntityType; public class EntityUtils { + /** + * Convert Java edition effect IDs to Bedrock edition + * + * @param effect Effect to convert + * @return The numeric ID for the Bedrock edition effect + */ public static int toBedrockEffectId(Effect effect) { switch (effect) { case GLOWING: @@ -51,6 +57,13 @@ public class EntityUtils { return effect.ordinal() + 1; } } + + /** + * Converts a MobType to a Bedrock edition EntityType, returns null if the EntityType is not found + * + * @param type The MobType to convert + * @return Converted EntityType + */ public static EntityType toBedrockEntity(MobType type) { try { return EntityType.valueOf(type.name()); @@ -59,6 +72,12 @@ public class EntityUtils { } } + /** + * Converts a ObjectType to a Bedrock edition EntityType, returns null if the EntityType is not found + * + * @param type The ObjectType to convert + * @return Converted EntityType + */ public static EntityType toBedrockEntity(ObjectType type) { try { return EntityType.valueOf(type.name()); diff --git a/connector/src/main/java/org/geysermc/connector/utils/FileUtils.java b/connector/src/main/java/org/geysermc/connector/utils/FileUtils.java index 0938fa7c..23da3746 100644 --- a/connector/src/main/java/org/geysermc/connector/utils/FileUtils.java +++ b/connector/src/main/java/org/geysermc/connector/utils/FileUtils.java @@ -27,24 +27,51 @@ package org.geysermc.connector.utils; import com.fasterxml.jackson.databind.ObjectMapper; import com.fasterxml.jackson.dataformat.yaml.YAMLFactory; - import org.geysermc.connector.GeyserConnector; -import java.io.*; +import java.io.File; +import java.io.FileOutputStream; +import java.io.IOException; +import java.io.InputStream; import java.util.function.Function; public class FileUtils { + /** + * Load the given YAML file into the given class + * + * @param src File to load + * @param valueType Class to load file into + * @return The data as the given class + * @throws IOException + */ public static T loadConfig(File src, Class valueType) throws IOException { ObjectMapper objectMapper = new ObjectMapper(new YAMLFactory()); return objectMapper.readValue(src, valueType); } - public static File fileOrCopiedFromResource(String name, Function s) throws IOException { - return fileOrCopiedFromResource(new File(name), name, s); + /** + * Open the specified file or copy if from resources + * + * @param name File and resource name + * @param fallback Formatting callback + * @return File handle of the specified file + * @throws IOException + */ + public static File fileOrCopiedFromResource(String name, Function fallback) throws IOException { + return fileOrCopiedFromResource(new File(name), name, fallback); } - public static File fileOrCopiedFromResource(File file, String name, Function s) throws IOException { + /** + * Open the specified file or copy if from resources + * + * @param file File to open + * @param name Name of the resource get if needed + * @param format Formatting callback + * @return File handle of the specified file + * @throws IOException + */ + public static File fileOrCopiedFromResource(File file, String name, Function format) throws IOException { if (!file.exists()) { file.createNewFile(); FileOutputStream fos = new FileOutputStream(file); @@ -54,7 +81,7 @@ public class FileUtils { input.read(bytes); - for(char c : s.apply(new String(bytes)).toCharArray()) { + for(char c : format.apply(new String(bytes)).toCharArray()) { fos.write(c); } @@ -66,6 +93,13 @@ public class FileUtils { return file; } + /** + * Writes the given data to the specified file on disk + * + * @param file File to write to + * @param data Data to write to the file + * @throws IOException + */ public static void writeFile(File file, char[] data) throws IOException { if (!file.exists()) { file.createNewFile(); @@ -81,6 +115,13 @@ public class FileUtils { fos.close(); } + /** + * Writes the given data to the specified file on disk + * + * @param name File path to write to + * @param data Data to write to the file + * @throws IOException + */ public static void writeFile(String name, char[] data) throws IOException { writeFile(new File(name), data); } diff --git a/connector/src/main/java/org/geysermc/connector/utils/LocaleUtils.java b/connector/src/main/java/org/geysermc/connector/utils/LocaleUtils.java index e8555eb0..726ad1c1 100644 --- a/connector/src/main/java/org/geysermc/connector/utils/LocaleUtils.java +++ b/connector/src/main/java/org/geysermc/connector/utils/LocaleUtils.java @@ -57,9 +57,15 @@ public class LocaleUtils { downloadAndLoadLocale(DEFAULT_LOCALE); } + /** + * Fetch the latest versions asset cache from Mojang so we can grab the locale files later + */ private static void generateAssetCache() { try { + // Get the version manifest from Mojang VersionManifest versionManifest = Toolbox.JSON_MAPPER.readValue(WebUtils.getBody("https://launchermeta.mojang.com/mc/game/version_manifest.json"), VersionManifest.class); + + // Get the url for the latest version of the games manifest String latestInfoURL = ""; for (Version version : versionManifest.getVersions()) { if (version.getId().equals(versionManifest.getLatestVersion().getRelease())) { @@ -68,12 +74,15 @@ public class LocaleUtils { } } + // Make sure we definitely got a version if (latestInfoURL.isEmpty()) { throw new Exception("Unable to get latest Minecraft version"); } + // Get the individual version manifest VersionInfo versionInfo = Toolbox.JSON_MAPPER.readValue(WebUtils.getBody(latestInfoURL), VersionInfo.class); + // Get the smallest jar for use when downloading the en_us locale, will be either the server or client int currentSize = Integer.MAX_VALUE; for (VersionDownload download : versionInfo.getDownloads().values()) { if (download.getUrl().endsWith(".jar") && download.getSize() < currentSize) { @@ -82,8 +91,10 @@ public class LocaleUtils { } } + // Get the assets list JsonNode assets = Toolbox.JSON_MAPPER.readTree(WebUtils.getBody(versionInfo.getAssetIndex().getUrl())).get("objects"); + // Put each asset into an array for use later Iterator> assetIterator = assets.fields(); while (assetIterator.hasNext()) { Map.Entry entry = assetIterator.next(); @@ -95,8 +106,15 @@ public class LocaleUtils { } } + /** + * Downloads a locale from Mojang if its not already loaded + * + * @param locale Locale to download and load + */ public static void downloadAndLoadLocale(String locale) { locale = locale.toLowerCase(); + + // Check the locale isn't already loaded if (!ASSET_MAP.containsKey("minecraft/lang/" + locale + ".json") && !locale.equals("en_us")) { GeyserConnector.getInstance().getLogger().warning("Invalid locale requested to download and load: " + locale); return; @@ -108,9 +126,15 @@ public class LocaleUtils { loadLocale(locale); } + /** + * Downloads the specified locale if its not already downloaded + * + * @param locale Locale to download + */ private static void downloadLocale(String locale) { File localeFile = new File("locales/" + locale + ".json"); + // Check if we have already downloaded the locale file if (localeFile.exists()) { GeyserConnector.getInstance().getLogger().debug("Locale already downloaded: " + locale); return; @@ -128,6 +152,11 @@ public class LocaleUtils { WebUtils.downloadFile("http://resources.download.minecraft.net/" + hash.substring(0, 2) + "/" + hash, "locales/" + locale + ".json"); } + /** + * Loads a locale already downloaded, if the file doesn't exist it just logs a warning + * + * @param locale Locale to load + */ private static void loadLocale(String locale) { File localeFile = new File("locales/" + locale + ".json"); @@ -146,7 +175,7 @@ public class LocaleUtils { try { localeObj = Toolbox.JSON_MAPPER.readTree(localeStream); } catch (Exception e) { - throw new AssertionError("Unable to load Java lang map for " + locale, e); + throw new AssertionError("Unable to load Java edition lang map for " + locale, e); } // Parse all the locale fields @@ -164,6 +193,11 @@ public class LocaleUtils { } } + /** + * Download then en_us locale by downloading the server jar and extracting it from there. + * + * @param localeFile File to save the locale to + */ private static void downloadEN_US(File localeFile) { try { // Let the user know we are downloading the JAR @@ -199,6 +233,13 @@ public class LocaleUtils { } } + /** + * Translate the given language string into the given locale, or falls back to the default locale + * + * @param messageText Language string to translate + * @param locale Locale to translate to + * @return Translated string or the original message if it was not found in the given locale + */ public static String getLocaleString(String messageText, String locale) { Map localeStrings = LocaleUtils.LOCALE_MAPPINGS.get(locale.toLowerCase()); if (localeStrings == null) diff --git a/connector/src/main/java/org/geysermc/connector/utils/MathUtils.java b/connector/src/main/java/org/geysermc/connector/utils/MathUtils.java index 79f8c274..4e8497c6 100644 --- a/connector/src/main/java/org/geysermc/connector/utils/MathUtils.java +++ b/connector/src/main/java/org/geysermc/connector/utils/MathUtils.java @@ -27,6 +27,12 @@ package org.geysermc.connector.utils; public class MathUtils { + /** + * Round the given float to the next whole number + * + * @param floatNumber Float to round + * @return Rounded number + */ public static int ceil(float floatNumber) { int truncated = (int) floatNumber; return floatNumber > truncated ? truncated + 1 : truncated; diff --git a/connector/src/main/java/org/geysermc/connector/utils/MessageUtils.java b/connector/src/main/java/org/geysermc/connector/utils/MessageUtils.java index 5be8eab1..c00d4bd5 100644 --- a/connector/src/main/java/org/geysermc/connector/utils/MessageUtils.java +++ b/connector/src/main/java/org/geysermc/connector/utils/MessageUtils.java @@ -121,6 +121,13 @@ public class MessageUtils { return getTranslatedBedrockMessage(message, null, false); } + /** + * Inserts the given parameters into the given message both in sequence and as requested + * + * @param message Message containing possible parameter replacement strings + * @param params A list of parameter strings + * @return Parsed message with all params inserted as needed + */ public static String insertParams(String message, List params) { String newMessage = message; @@ -130,7 +137,7 @@ public class MessageUtils { try { newMessage = newMessage.replaceFirst("%" + m.group(1) + "\\$s" , params.get(Integer.parseInt(m.group(1)) - 1)); } catch (Exception e) { - // Couldnt find the param to replace + // Couldn't find the param to replace } } @@ -141,6 +148,12 @@ public class MessageUtils { return newMessage; } + /** + * Gets the colour for the message style or fetches it from the parent (recursive) + * + * @param style The style to get the colour from + * @return Colour string to be used + */ private static String getColorOrParent(MessageStyle style) { ChatColor chatColor = style.getColor(); @@ -151,6 +164,12 @@ public class MessageUtils { return getColor(chatColor); } + /** + * Convert a ChatColor into a string for inserting into messages + * + * @param color ChatColor to convert + * @return The converted color string + */ private static String getColor(ChatColor color) { String base = "\u00a7"; switch (color) { @@ -213,6 +232,12 @@ public class MessageUtils { return base; } + /** + * Convert a list of ChatFormats into a string for inserting into messages + * + * @param formats ChatFormats to convert + * @return The converted chat formatting string + */ private static String getFormat(List formats) { StringBuilder str = new StringBuilder(); for (ChatFormat cf : formats) { @@ -243,6 +268,12 @@ public class MessageUtils { return str.toString(); } + /** + * Checks if the given text string is a json message + * + * @param text String to test + * @return True if its a valid message json string, false if not + */ public static boolean isMessage(String text) { JsonParser parser = new JsonParser(); try { @@ -296,6 +327,13 @@ public class MessageUtils { return ""; } + /** + * Checks if the given message is over 256 characters (Java edition server chat limit) and sends a message to the user if it is + * + * @param message Message to check + * @param session GeyserSession for the user + * @return True if the message is too long, false if not + */ public static boolean isTooLong(String message, GeyserSession session) { if (message.length() > 256) { // TODO: Add Geyser localization and translate this based on language diff --git a/connector/src/main/java/org/geysermc/connector/utils/SkinUtils.java b/connector/src/main/java/org/geysermc/connector/utils/SkinUtils.java index 7a5b9798..9480cffd 100644 --- a/connector/src/main/java/org/geysermc/connector/utils/SkinUtils.java +++ b/connector/src/main/java/org/geysermc/connector/utils/SkinUtils.java @@ -105,6 +105,12 @@ public class SkinUtils { private String capeUrl; private boolean alex; + /** + * Generate the GameProfileData from the given GameProfile + * + * @param profile GameProfile to build the GameProfileData from + * @return The built GameProfileData + */ public static GameProfileData from(GameProfile profile) { try { GameProfile.Property skinProperty = profile.getProperty("textures"); @@ -189,6 +195,12 @@ public class SkinUtils { }); } + /** + * Create a basic geometry json for the given name + * + * @param geometryName Geometry name to use + * @return Geometry data as a json string + */ private static String getLegacySkinGeometry(String geometryName) { return "{\"geometry\" :{\"default\" :\"" + geometryName + "\"}}"; } diff --git a/connector/src/main/java/org/geysermc/connector/utils/Toolbox.java b/connector/src/main/java/org/geysermc/connector/utils/Toolbox.java index 9c1e10f6..989f9a3a 100644 --- a/connector/src/main/java/org/geysermc/connector/utils/Toolbox.java +++ b/connector/src/main/java/org/geysermc/connector/utils/Toolbox.java @@ -110,6 +110,12 @@ public class Toolbox { LocaleUtils.init(); } + /** + * Get an InputStream for the given resource path, throws AssertionError if resource is not found + * + * @param resource Resource to get + * @return InputStream of the given resource + */ public static InputStream getResource(String resource) { InputStream stream = Toolbox.class.getClassLoader().getResourceAsStream(resource); if (stream == null) { diff --git a/connector/src/main/java/org/geysermc/connector/utils/WebUtils.java b/connector/src/main/java/org/geysermc/connector/utils/WebUtils.java index 065d683a..50ab76d0 100644 --- a/connector/src/main/java/org/geysermc/connector/utils/WebUtils.java +++ b/connector/src/main/java/org/geysermc/connector/utils/WebUtils.java @@ -36,6 +36,12 @@ import java.nio.file.StandardCopyOption; public class WebUtils { + /** + * Makes a web request to the given URL and returns the body as a string + * + * @param reqURL URL to fetch + * @return Body contents or error message if the request fails + */ public static String getBody(String reqURL) { URL url = null; try { @@ -61,6 +67,12 @@ public class WebUtils { } } + /** + * Downloads a file from the given URL and saves it to disk + * + * @param reqURL File to fetch + * @param fileLocation Location to save on disk + */ public static void downloadFile(String reqURL, String fileLocation) { try { InputStream in = new URL(reqURL).openStream();