refactor(BlockItemFactory): remove code dupes; add doc; retain components (#4006)

skaldarnar · keturn · web-flow · commit 957543938f28 · 2020-05-31T11:11:25.000+02:00
* Remove code duplication
* Update doc for RetainComponentsComponent
* Keep components listed as _retain components_ when creating a block item

* doc(BlockItemFactory): doc class and builder methods

* doc(BlockItemFactory): doc for `BlockItemFactory::newInstance` methods

* doc(BlockItemFactory): finalize documentation for class

* Update engine/src/main/java/org/terasology/world/block/items/BlockItemFactory.java

Co-authored-by: Kevin Turner &lt;83819+keturn@users.noreply.github.com&gt;



Co-authored-by: Kevin Turner &lt;83819+keturn@users.noreply.github.com&gt;
diff --git a/engine/src/main/java/org/terasology/logic/common/RetainComponentsComponent.java b/engine/src/main/java/org/terasology/logic/common/RetainComponentsComponent.java
@@ -22,10 +22,11 @@
 import java.util.Set;
 
 /**
- * This component is intended to list component classes that are supposed to be retained when placing a block.
- *
- * If a block entity has a component that is not part of its prefab, retaining this component results in
- * the block entity still having this component afterwards. If not retained, it is likely to be removed instead.
+ * This component is intended to list component classes that are supposed to be retained when converting between blocks
+ * and block items.
+ * <p>
+ * If a block (item) entity has a component that is not part of its prefab, retaining this component results in the block
+ * entity still having this component afterwards. If not retained, it is likely to be removed instead.
  */
 public class RetainComponentsComponent implements Component {
     @Replicate
diff --git a/engine/src/main/java/org/terasology/world/block/items/BlockItemFactory.java b/engine/src/main/java/org/terasology/world/block/items/BlockItemFactory.java
@@ -15,68 +15,81 @@
  */
 package org.terasology.world.block.items;
 
+import com.google.common.base.Preconditions;
+import com.google.common.primitives.SignedBytes;
 import org.terasology.entitySystem.Component;
+import org.terasology.entitySystem.ComponentContainer;
 import org.terasology.entitySystem.entity.EntityBuilder;
 import org.terasology.entitySystem.entity.EntityManager;
 import org.terasology.entitySystem.entity.EntityRef;
-import org.terasology.entitySystem.prefab.Prefab;
 import org.terasology.logic.common.DisplayNameComponent;
+import org.terasology.logic.common.RetainComponentsComponent;
 import org.terasology.logic.inventory.ItemComponent;
 import org.terasology.rendering.logic.LightComponent;
 import org.terasology.world.block.family.BlockFamily;
 
+import java.util.Collections;
 import java.util.Optional;
+import java.util.Set;
 
 /**
+ * A factory to create new <em>block items</em> for a {@link BlockFamily}.
+ * <p>
+ * A <strong>block item</strong> is an entity guaranteed to have the following components.
+ * <ul>
+ *     <li>{@link BlockItemComponent}. the back-reference to the block family</li>
+ *     <li>{@link ItemComponent}. the item component with automatic stack id and quantity if block is stackable</li>
+ *     <li>{@link DisplayNameComponent}. the block family archetype display name</li>
+ * </ul>
+ * Components on the block prefab (or the reference block entity) will only be retained if the component class is
+ * annotated with {@link AddToBlockBasedItem} or the component class is listed in {@link RetainComponentsComponent}.
+ * <p>
+ * The created entity (builder) is based on the block item base prefab ({@code engine:blockItemBase}).
+ *
+ * @see AddToBlockBasedItem
+ * @see RetainComponentsComponent
  */
 public class BlockItemFactory {
-    private EntityManager entityManager;
+    private final EntityManager entityManager;
 
+    /**
+     * Instantiate new block item factory with the given entity manager.
+     *
+     * @param entityManager entity manager to create new {@link EntityBuilder}s and copy components from
+     *         reference entities or prefabs to the new block items
+     */
     public BlockItemFactory(EntityManager entityManager) {
         this.entityManager = entityManager;
     }
 
+    /**
+     * Create a new block item for the given {@link BlockFamily}.
+     * <p>
+     * Attempts to resolve the corresponding block prefab to retrieve a list of potential components to add. The item
+     * quantity defaults to 1.
+     * <p>
+     * Use {@link #newBuilder(BlockFamily, int)} if you want to modify the block item entity's properties before it gets
+     * created.
+     *
+     * @param blockFamily block family to create the block item builder for
+     * @return the block item entity
+     */
     public EntityRef newInstance(BlockFamily blockFamily) {
         return newInstance(blockFamily, 1);
     }
 
     /**
-     * Use this method instead of {@link #newInstance(BlockFamily)} to modify entity properties like the persistence
-     * flag before it gets created.
+     * Create a new block item for the given {@link BlockFamily} and item quantity.
+     * <p>
+     * Attempts to resolve the corresponding block prefab to retrieve a list of potential components to add.
+     * <p>
+     * Use {@link #newBuilder(BlockFamily, int)} if you want to modify the block item entity's properties before it gets
+     * created.
      *
-     * @param blockFamily must not be null
+     * @param blockFamily block family to create the block item builder for
+     * @param quantity item quantity (see {@link ItemComponent#stackCount}); constrained to [0...128)
+     * @return the block item entity
      */
-    public EntityBuilder newBuilder(BlockFamily blockFamily, int quantity) {
-        EntityBuilder builder = entityManager.newBuilder("engine:blockItemBase");
-        if (blockFamily.getArchetypeBlock().getLuminance() > 0) {
-            builder.addComponent(new LightComponent());
-        }
-
-        // Copy the components from block prefab into the block item
-        Optional<Prefab> prefab = blockFamily.getArchetypeBlock().getPrefab();
-        if (prefab.isPresent()) {
-            for (Component component : prefab.get().iterateComponents()) {
-                if (component.getClass().getAnnotation(AddToBlockBasedItem.class) != null) {
-                    builder.addComponent(entityManager.getComponentLibrary().copy(component));
-                }
-            }
-        }
-
-        DisplayNameComponent displayNameComponent = builder.getComponent(DisplayNameComponent.class);
-        displayNameComponent.name = blockFamily.getDisplayName();
-
-        ItemComponent item = builder.getComponent(ItemComponent.class);
-        if (blockFamily.getArchetypeBlock().isStackable()) {
-            item.stackId = "block:" + blockFamily.getURI().toString();
-            item.stackCount = (byte) quantity;
-        }
-
-        BlockItemComponent blockItem = builder.getComponent(BlockItemComponent.class);
-        blockItem.blockFamily = blockFamily;
-
-        return builder;
-    }
-
     public EntityRef newInstance(BlockFamily blockFamily, int quantity) {
         if (blockFamily == null) {
             return EntityRef.NULL;
@@ -85,37 +98,145 @@ public EntityRef newInstance(BlockFamily blockFamily, int quantity) {
         return builder.build();
     }
 
+    /**
+     * Create a new block item for the given {@link BlockFamily}, with {@code blockEntity} as reference entity to retain
+     * components from.
+     * <p>
+     * The item quantity defaults to 1.
+     * <p>
+     * Use {@link #newBuilder(BlockFamily, EntityRef, int)} if you want to modify the block item entity's properties
+     * before it gets created.
+     *
+     * @param blockFamily block family to create the block item builder for
+     * @param blockEntity reference block entity to retain components from
+     * @return the block item entity
+     */
     public EntityRef newInstance(BlockFamily blockFamily, EntityRef blockEntity) {
         if (blockFamily == null) {
             return EntityRef.NULL;
         }
 
+        return createBuilder(blockFamily, blockEntity, (byte) 1).build();
+    }
+
+    /**
+     * Create a new block item builder for the given {@link BlockFamily} and item quantity.
+     * <p>
+     * Attempts to resolve the corresponding block prefab to retrieve a list of potential components to add.
+     * <p>
+     * Use this method if you want to modify the block item entity's properties before it gets created.
+     *
+     * @param blockFamily block family to create the block item builder for
+     * @param quantity item quantity (see {@link ItemComponent#stackCount}); constrained to [0...128)
+     * @return a pre-populated entity builder for a block item entity
+     */
+    public EntityBuilder newBuilder(BlockFamily blockFamily, int quantity) {
+        final ComponentContainer components =
+                blockFamily.getArchetypeBlock().getPrefab()
+                        .map(p -> ((ComponentContainer) p))
+                        .orElse(EntityRef.NULL);
+
+        return createBuilder(blockFamily, components, SignedBytes.saturatedCast(quantity));
+    }
+
+    /**
+     * Create a new block item builder for the given {@link BlockFamily} and item quantity, with {@code blockEntity} as
+     * reference entity to retain components from.
+     * <p>
+     * Use this method if you want to modify the block item entity's properties before it gets created.
+     *
+     * @param blockFamily block family to create the block item builder for
+     * @param blockEntity reference block entity to retain components from
+     * @param quantity item quantity (see {@link ItemComponent#stackCount}); constrained to [0...128)
+     * @return a pre-populated entity builder for a block item entity
+     */
+    public EntityBuilder newBuilder(BlockFamily blockFamily, EntityRef blockEntity, int quantity) {
+        return createBuilder(blockFamily, blockEntity, SignedBytes.saturatedCast(quantity));
+    }
+
+    /**
+     * Create a new block item builder for the given {@link BlockFamily}.
+     *
+     * @param blockFamily block family to create the block item builder for
+     * @param components potential components to add to the block item entity
+     * @param quantity item quantity (see {@link ItemComponent#stackCount})
+     * @return a pre-populated entity builder for a block item entity
+     */
+    private EntityBuilder createBuilder(BlockFamily blockFamily, ComponentContainer components, byte quantity) {
+        Preconditions.checkNotNull(blockFamily, "Block family must not be null when creating block item");
+
         EntityBuilder builder = entityManager.newBuilder("engine:blockItemBase");
-        if (blockFamily.getArchetypeBlock().getLuminance() > 0) {
-            builder.addComponent(new LightComponent());
-        }
+        addComponents(builder, components);
 
-        // Copy the components from block prefab into the block item
-        for (Component component : blockEntity.iterateComponents()) {
-            if (component.getClass().getAnnotation(AddToBlockBasedItem.class) != null) {
+        adjustLightComponent(builder, blockFamily);
+        adjustDisplayNameComponent(builder, blockFamily);
+        adjustItemComponent(builder, blockFamily, quantity);
+        adjustBlockItemComponent(builder, blockFamily);
+
+        return builder;
+    }
+
+    /**
+     * Mutate the builder to add components from the given component container.
+     * <p>
+     * A component is only added to the builder if at least one of the following conditions holds:
+     * <ul>
+     *     <li>the component class is annotated with {@link AddToBlockBasedItem}</li>
+     *     <li>the container contains a {@link RetainComponentsComponent} and the component class is listed as
+     *     retained</li>
+     * </ul>
+     * <p>
+     * Components that should be added to the block item entity are <emph>copied</emph>.
+     *
+     * @param builder the builder to add the components to
+     * @param components the container with potential components to add
+     */
+    private void addComponents(EntityBuilder builder, ComponentContainer components) {
+        final Set<Class<? extends Component>> retainComponents =
+                Optional.ofNullable(components.getComponent(RetainComponentsComponent.class))
+                        .map(retain -> retain.components)
+                        .orElse(Collections.emptySet());
+
+        for (Component component : components.iterateComponents()) {
+            if (keepByAnnotation(component) || retainComponents.contains(component.getClass())) {
                 builder.addComponent(entityManager.getComponentLibrary().copy(component));
             }
         }
+    }
 
-        DisplayNameComponent displayNameComponent = builder.getComponent(DisplayNameComponent.class);
-        if (displayNameComponent != null) {
-            displayNameComponent.name = blockFamily.getDisplayName();
-        }
+    private boolean keepByAnnotation(Component component) {
+        return component.getClass().getAnnotation(AddToBlockBasedItem.class) != null;
+    }
 
-        ItemComponent item = builder.getComponent(ItemComponent.class);
-        if (blockFamily.getArchetypeBlock().isStackable()) {
-            item.stackId = "block:" + blockFamily.getURI().toString();
-            item.stackCount = (byte) 1;
+    private void adjustLightComponent(EntityBuilder builder, BlockFamily blockFamily) {
+        //TODO: set properties of the LightComponent based on the archetype block?
+        if (blockFamily.getArchetypeBlock().getLuminance() > 0 && !builder.hasComponent(LightComponent.class)) {
+            builder.addComponent(new LightComponent());
         }
+    }
 
-        BlockItemComponent blockItem = builder.getComponent(BlockItemComponent.class);
-        blockItem.blockFamily = blockFamily;
+    private void adjustDisplayNameComponent(EntityBuilder builder, BlockFamily blockFamily) {
+        builder.updateComponent(DisplayNameComponent.class, displayName -> {
+            displayName.name = blockFamily.getDisplayName();
+            return displayName;
+        });
+    }
 
-        return builder.build();
+    private void adjustItemComponent(EntityBuilder builder, BlockFamily blockFamily, byte quantity) {
+        builder.updateComponent(ItemComponent.class, item -> {
+            if (blockFamily.getArchetypeBlock().isStackable()) {
+                item.stackId = "block:" + blockFamily.getURI().toString();
+                //TODO: quantity may be greater than item.maxStackSize
+                item.stackCount = quantity;
+            }
+            return item;
+        });
+    }
+
+    private void adjustBlockItemComponent(EntityBuilder builder, BlockFamily blockFamily) {
+        builder.updateComponent(BlockItemComponent.class, blockItem -> {
+            blockItem.blockFamily = blockFamily;
+            return blockItem;
+        });
     }
 }
