From a51ff5797c27775329ea56354ef363540411378d Mon Sep 17 00:00:00 2001 From: Kas-tle <26531652+Kas-tle@users.noreply.github.com> Date: Thu, 5 Jan 2023 15:59:29 -0800 Subject: [PATCH] Add docs for custom blocks --- .../api/block/custom/CustomBlockData.java | 33 +++++++- .../api/block/custom/CustomBlockMapping.java | 30 ++++++++ .../block/custom/CustomBlockPermutation.java | 4 + .../api/block/custom/CustomBlockState.java | 20 +++++ .../block/custom/component/BoxComponent.java | 9 +++ .../component/CustomBlockComponents.java | 76 ++++++++++++++++++- .../custom/component/MaterialInstance.java | 3 + .../custom/component/RotationComponent.java | 3 + .../custom/property/CustomBlockProperty.java | 3 + .../block/custom/property/PropertyType.java | 3 + .../GeyserDefineCustomBlocksEvent.java | 19 +++++ 11 files changed, 201 insertions(+), 2 deletions(-) diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockData.java b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockData.java index 52d90892d..14b2a5957 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockData.java +++ b/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> properties(); + /** + * Gets the list of the custom block's permutations + * + * @return The permutations of the custom block. + */ @NonNull List 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(); diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockMapping.java b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockMapping.java index d2ccfade6..ccd5e8ad8 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockMapping.java +++ b/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 states, @NonNull String javaIdentifier, @NonNull boolean overrideItem) { } diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockPermutation.java b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockPermutation.java index dfaf626f3..0d52a2a9e 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockPermutation.java +++ b/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) { } diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockState.java b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockState.java index 14af446a0..9fae9e799 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/CustomBlockState.java +++ b/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 property(String propertyName); @NonNull Map properties(); diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/BoxComponent.java b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/BoxComponent.java index 142878c5b..5da8e422a 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/BoxComponent.java +++ b/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; } diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/CustomBlockComponents.java b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/CustomBlockComponents.java index 847205c6a..5e8c2c7b8 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/CustomBlockComponents.java +++ b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/CustomBlockComponents.java @@ -29,27 +29,101 @@ import org.checkerframework.checker.nullness.qual.NonNull; import java.util.Map; +/** + * 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 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(); interface Builder { diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/MaterialInstance.java b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/MaterialInstance.java index 19ba0906d..bea22d321 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/MaterialInstance.java +++ b/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) { } diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/RotationComponent.java b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/RotationComponent.java index 6fab3c1ba..610b5365b 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/component/RotationComponent.java +++ b/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) { } diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/property/CustomBlockProperty.java b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/property/CustomBlockProperty.java index 697cfe268..6cf90b320 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/property/CustomBlockProperty.java +++ b/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 { @NonNull String name(); diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/property/PropertyType.java b/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/property/PropertyType.java index e4ac0f339..099bc0a45 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/block/custom/property/PropertyType.java +++ b/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); diff --git a/api/geyser/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineCustomBlocksEvent.java b/api/geyser/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineCustomBlocksEvent.java index b57bec855..bc8db82b8 100644 --- a/api/geyser/src/main/java/org/geysermc/geyser/api/event/lifecycle/GeyserDefineCustomBlocksEvent.java +++ b/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); }