Merge branch 'feature/blocky' of https://github.com/Kas-tle/Geyser into feature/blocky

api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockData.java

@@ -33,19 +33,50 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * This is used to store data for a custom block.
+ * This class is used to store data for a custom block.
  */
 public interface CustomBlockData {
+    /**
+     * Gets the name of the custom block
+     *
+     * @return The name of the custom block.
+     */
     @NonNull String name();
 
+    /**
+     * Gets the identifier of the custom block
+     *
+     * @return The identifier of the custom block.
+     */
     @NonNull String identifier();
 
+    /**
+     * Gets the components of the custom block
+     *
+     * @return The components of the custom block.
+     */
     CustomBlockComponents components();
 
+    /**
+     * Gets the custom block's map of block property names to CustomBlockProperty
+     * objects
+     *
+     * @return The custom block's map of block property names to CustomBlockProperty objects.
+     */
     @NonNull Map<String, CustomBlockProperty<?>> properties();
 
+    /**
+     * Gets the list of the custom block's permutations
+     *
+     * @return The permutations of the custom block.
+     */
     @NonNull List<CustomBlockPermutation> permutations();
 
+    /**
+     * Gets the custom block's default block state
+     *
+     * @return The default block state of the custom block.
+     */
     @NonNull CustomBlockState defaultBlockState();
 
     CustomBlockState.@NonNull Builder blockStateBuilder();

api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockMapping.java

@@ -1,8 +1,38 @@
+/*
+ * Copyright (c) 2019-2022 GeyserMC. http://geysermc.org
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ *
+ * @author GeyserMC
+ * @link https://github.com/GeyserMC/Geyser
+ */
+
 package org.geysermc.geyser.api.block.custom;
 
 import java.util.Map;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+/**
+ * This class is used to store a custom block mappings, which contain all of the 
+ * data required to register a custom block that overrides a group of java block
+ * states.
+ */
 public record CustomBlockMapping(@NonNull CustomBlockData data, @NonNull Map<String, CustomBlockState> states, @NonNull String javaIdentifier, @NonNull boolean overrideItem) {
 }

api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockPermutation.java

@@ -28,5 +28,9 @@ package org.geysermc.geyser.api.block.custom;
 import org.checkerframework.checker.nullness.qual.NonNull;
 import org.geysermc.geyser.api.block.custom.component.CustomBlockComponents;
 
+/**
+ * This class is used to store a custom block permutations, which contain custom 
+ * block components mapped to a Molang query that should return true or false
+ */
 public record CustomBlockPermutation(@NonNull CustomBlockComponents components, @NonNull String condition) {
 }

api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockState.java

@@ -29,11 +29,31 @@ import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.Map;
 
+/**
+ * This class is used to store a custom block state, which contains CustomBlockData 
+ * tied to defined properties and values
+ */
 public interface CustomBlockState {
+    /**
+     * Gets the custom block data associated with the state
+     *
+     * @return The custom block data for the state.
+     */
     @NonNull CustomBlockData block();
 
+    /**
+     * Gets the name of the state
+     *
+     * @return The name of the state.
+     */
     @NonNull String name();
 
+    /**
+     * Gets the given property for the state
+     *
+     * @param propertyName the property name
+     * @return The java identifier for this item.
+     */
     @NonNull <T> T property(String propertyName);
 
     @NonNull Map<String, Object> properties();

api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/BoxComponent.java

@@ -25,11 +25,20 @@
 
 package org.geysermc.geyser.api.block.custom.component;
 
+/**
+ * This class is used to store a box component for the selection and
+ * collision boxes of a custom block.
+ */
 public record BoxComponent(float originX, float originY, float originZ,
                            float sizeX, float sizeY, float sizeZ) {
     public static final BoxComponent FULL_BLOCK = new BoxComponent(-8, 0, -8, 16, 16, 16);
     public static final BoxComponent EMPTY_BOX = new BoxComponent(0, 0, 0, 0, 0, 0);
 
+    /**
+     * Gets if the box component is empty
+     *
+     * @return If the box component is empty.
+     */
     public boolean isEmpty() {
         return sizeX == 0 && sizeY == 0 && sizeZ == 0;
     }

api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/CustomBlockComponents.java

@@ -30,27 +30,101 @@ import org.checkerframework.checker.nullness.qual.NonNull;
 import java.util.Map;
 import java.util.Set;
 
+/**
+ * This class is used to store components for a custom block or custom block permutation.
+ */
 public interface CustomBlockComponents {
+    /**
+     * Gets the name component
+     *
+     * @return The name.
+     */
+    @NonNull String name();
+
+    /**
+     * Gets the selection box component
+     * Equivalent to "minecraft:selection_box"
+     *
+     * @return The selection box.
+     */
     BoxComponent selectionBox();
 
+    /**
+     * Gets the collision box component
+     * Equivalent to "minecraft:collision_box"
+     * @return The collision box.
+     */
     BoxComponent collisionBox();
-    
+
+    /**
+     * Gets the display name component
+     * Equivalent to "minecraft:display_name"
+     *
+     * @return The display name.
+     */
     String displayName();
 
+    /**
+     * Gets the geometry component
+     * Equivalent to "minecraft:geometry"
+     *
+     * @return The geometry.
+     */
     String geometry();
 
+    /**
+     * Gets the material instances component
+     * Equivalent to "minecraft:material_instances"
+     *
+     * @return The material instances.
+     */
     @NonNull Map<String, MaterialInstance> materialInstances();
 
+    /**
+     * Gets the destructible by mining component
+     * Equivalent to "minecraft:destructible_by_mining"
+     *
+     * @return The destructible by mining value.
+     */
     Float destructibleByMining();
 
+    /**
+     * Gets the friction component
+     * Equivalent to "minecraft:friction"
+     *
+     * @return The friction value.
+     */
     Float friction();
 
+    /**
+     * Gets the light emission component
+     * Equivalent to "minecraft:light_emission"
+     *
+     * @return The light emission value.
+     */
     Integer lightEmission();
 
+    /**
+     * Gets the light dampening component
+     * Equivalent to "minecraft:light_dampening"
+     *
+     * @return The light dampening value.
+     */
     Integer lightDampening();
 
+    /**
+     * Gets the rotation component
+     * Equivalent to "minecraft:rotation"
+     *
+     * @return The rotation.
+     */
     RotationComponent rotation();
 
+    /**
+     * Gets if the block should place only air
+     * Equivalent to setting a dummy event to run on "minecraft:on_player_placing"
+     * @return If the block should place only air.
+     */
     boolean placeAir();
 
     Set<String> tags();

api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/MaterialInstance.java

@@ -27,6 +27,9 @@ package org.geysermc.geyser.api.block.custom.component;
 
 import org.checkerframework.checker.nullness.qual.NonNull;
 
+/**
+ * This class is used to store a material instance for a custom block.
+ */
 public record MaterialInstance(@NonNull String texture, @NonNull String renderMethod, boolean faceDimming, boolean ambientOcclusion) {
 
 }

api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/RotationComponent.java

@@ -25,5 +25,8 @@
 
 package org.geysermc.geyser.api.block.custom.component;
 
+/**
+ * This class is used to store a rotation component for a custom block.
+ */
 public record RotationComponent(int x, int y, int z) {
 }

api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/property/CustomBlockProperty.java

@@ -29,6 +29,9 @@ import org.checkerframework.checker.nullness.qual.NonNull;
 
 import java.util.List;
 
+/**
+ * This class is used to store a property of a custom block of a generic type.
+ */
 public interface CustomBlockProperty<T> {
     @NonNull String name();
 

api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/property/PropertyType.java

@@ -27,6 +27,9 @@ package org.geysermc.geyser.api.block.custom.property;
 
 import lombok.Getter;
 
+/**
+ * This class is used to define a custom block property's type.
+ */
 public class PropertyType {
     public static final PropertyType BOOLEAN = new PropertyType(Boolean.class);
     public static final PropertyType INTEGER = new PropertyType(Integer.class);

api/geyser/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineCustomBlocksEvent.java

@@ -30,9 +30,28 @@ import org.geysermc.geyser.api.block.custom.CustomBlockData;
 import org.geysermc.geyser.api.block.custom.CustomBlockState;
 import org.geysermc.event.Event;
 
+/**
+ * Called on Geyser's startup when looking for custom blocks. Custom blocks must be registered through this event.
+ *
+ * This event will not be called if the "add-custom-blocks" setting is disabled in the Geyser config.
+ */
 public abstract class GeyserDefineCustomBlocksEvent implements Event {
 
+    /**
+     * Registers the given {@link CustomBlockData} as a custom block
+     *
+     * @param customBlockData the custom block to register
+     */
     public abstract void registerCustomBlock(@NonNull CustomBlockData customBlockData);
 
+    /**
+     * Registers the given {@link CustomBlockState} as an override for the
+     * given java state identifier
+     * Java state identifiers are listed in
+     * https://raw.githubusercontent.com/GeyserMC/mappings/master/blocks.json
+     *
+     * @param javaIdentifier the java state identifier to override
+     * @param customBlockState the custom block state with which to override java state identifier
+     */
     public abstract void registerBlockStateOverride(@NonNull String javaIdentifier, @NonNull CustomBlockState customBlockState);
 }