1.20.1 v8.0.0 (#4628)

Admin Merge-Commit (Unsquashed)

Author: Ghostipedia

dependencies.gradle

@@ -22,8 +22,7 @@ dependencies {
     modCompileOnly(forge.bundles.rei)
     modCompileOnly(forge.emi)
 
-    // WAILA-likes
-    modCompileOnly(forge.theoneprobe)
+    // Jade (WAILA)
     modCompileOnly(forge.jade)
 
     // Curios

docs/content/Development/Data-Sync-System/Annotations.md

@@ -0,0 +1,61 @@
+---
+title: "Annotations"
+---
+
+# Annotations
+The following annotations define the sync/save behaviour for an `ISyncManaged` object.
+
+### `@SaveField`
+
+The `@SaveField` annotation defines a field that should be saved to the server. `nbtKey` is optional, the key will default to the field name.
+```java
+@SaveField(nbtKey="nbtKeyToSaveTo")
+public int mySaveInt = 10;
+```
+
+### `@SyncToClient`
+
+The `@SyncToClient` annotation defines a field with a value that should be synced to clients.
+
+!!! warning 
+    Client sync fields **do not** automatically detect changes. When changing a client sync field, call `ISyncManaged.getSyncDataHolder().markClientSyncFieldDirty(FIELD_NAME)`
+```java
+@SaveField(nbtKey="nbtKeyToSaveTo")
+@SyncToClient
+public int mySaveAndSyncInt = 10;
+
+@SyncToClient
+@RerenderOnChanged
+public long mySyncRerenderLong = 10000L;
+
+public void serverTick() {
+    int newIntValue = getNewIntValue();
+    long newLongValue = getNewLongValue();
+    if (mySaveAndSyncInt != newIntValue) {
+        mySaveAndSyncInt = newIntValue;
+        getSyncDataHolder().markClientSyncFieldDirty("mySaveAndSyncInt");
+    }
+    if (mySyncRerenderLong != newLongValue) {
+        mySyncRerenderLong = newLongValue;
+        getSyncDataHolder().markClientSyncFieldDirty("mySyncRerenderLong");
+    }
+}
+```
+
+### `@ClientFieldChangeListener` and `@RerenderOnChanged`
+
+The `@ClientFieldChangeListener` annotation defines a method to be called on the client when a client sync field has changed value;
+
+Annotating a `@SyncToClient` field with `@RerenderOnChanged` will cause clients to rerender the block entity when this field changes.
+
+```java
+@SyncToClient
+@SaveField
+@RerenderOnChanged
+public boolean isWorkingEnabled = true;
+
+@ClientFieldChangeListener(fieldName="isWorkingEnabled")
+public void isWorkingChanged() {
+    setRenderState(getRenderState().setValue(GTMachineModelProperties.IS_WORKING_ENABLED, isWorkingEnabled));
+}
+```

docs/content/Development/Data-Sync-System/Migrating-From-LDLib-SyncData.md

@@ -0,0 +1,77 @@
+---
+title: "Migrating from LDLib SyncData"
+---
+# Migrating from LDLib SyncData
+
+### Simple example
+
+This simple example covers the majority of use cases when adding sync/save fields to a standard machine, machine trait or cover.
+
+#### With LDLib:
+```java
+class CustomMachine extends SimpleTieredMachine {
+    protected static final ManagedFieldHolder MANAGED_FIELD_HOLDER = new ManagedFieldHolder(CustomMachine.class,
+            SimpleTieredMachine.MANAGED_FIELD_HOLDER);
+
+    @Override
+    public ManagedFieldHolder getFieldHolder() {
+        return MANAGED_FIELD_HOLDER;
+    }
+
+    @Getter 
+    @Persisted
+    @DescSynced
+    @RequireRerender
+    protected int customIntValue;
+    
+    @Persisted(key = "customNBTKey")
+    protected String customStringValue;
+
+    public void setCustomIntValue(int newValue) {
+        this.customIntValue = newValue;
+    }
+}
+```
+
+#### New System:
+```java
+class CustomMachine extends SimpleTieredMachine {
+    @Getter 
+    @SaveField
+    @SyncToClient
+    protected int customIntValue;
+    
+    @SaveField(nbtKey = "customNBTKey")
+    protected String customStringValue;
+    
+    public void setCustomIntValue(int newValue) {
+        this.customIntValue = newValue;
+        ////// IMPORTANT: markClientSyncFieldDirty must be called to update client synced fields.
+        getSyncDataHolder().markClientSyncFieldDirty("customIntValue");
+    }
+}
+
+```
+
+### General migration guidelines
+
+- Remove all `ManagedFieldHolder` fields.
+- Replace `FieldManagedStorage` fields with `SyncDataHolder` fields.
+- Replace `IEnhancedManaged` objects with `ISyncManaged`.
+- Replace `IAsyncAutoSyncBlockEntity`, `IAutoPersistBlockEntity`, `IAutoSyncBlockEntity` and `IManagedBlockEntity` by extending `ManagedSyncBlockEntity`.
+
+### Annotations
+
+!!! warning
+Client sync fields **do not** automatically detect changes. When changing a client sync field, call `ISyncManaged.syncDataHolder.markClientSyncFieldDirty(FIELD_NAME)`
+
+- `@DescSynced` -> `@SyncToClient`
+- `@RequireRerender` -> `@RerenderOnChanged`
+- `@Persisted` -> `@SaveField`
+- `@UpdateListener` -> `@ClientFieldChangeListener` on listener method.
+- `@DropSaved` - Removed, make machines implement `IDropSaveMachine` instead
+- `@ReadOnlyManaged` and `@LazyManaged` See usage docs for instructions on complex sync objects 
+
+### Other changes
+
+ - `saveCustomPersistedData` & `loadCustomPersistedData` methods, and serialization of custom data types - See `ValueTransformer<T>` and `ValueTransformers` classes.

docs/content/Development/Data-Sync-System/Usage.md

@@ -0,0 +1,103 @@
+---
+title: "Usage"
+---
+
+## Usage
+
+### Registering classes with the sync system
+
+At the core of the system is the interface `ISyncManaged`, which represents a class that to be synchronised with the client or saved.
+All block entities which should be synchronised or saved must extend the abstract class `ManagedSyncBlockEntity`.
+
+!!! warning 
+  Block entities that inherit `ManagedSyncBlockEntity` must call `ManagedSyncBlockEntity::updateTick`***every tick*** within their ticker, or they will not be saved.
+
+```java
+class MySyncObject implements ISyncManaged {
+    // Any class that directly implements ISyncManaged must have the following:
+     @Getter
+     protected final SyncDataHolder syncDataHolder = new SyncDataHolder(this);
+    
+    
+    /**
+     * Function called when the SyncDataHolder requests a rerender
+     */
+    void scheduleRenderUpdate();
+
+    /**
+     * Function called to notify the server that this object has been updated and must be synced to clients
+     */
+    void markAsChanged();
+}
+```
+
+### Registering fields to be managed by the system
+See [Annotations](Annotations.md)
+
+### Type compatibility
+The following field types are supported by default:
+- Any class implementing `ISyncManaged`
+- Any class implementing `INBTSerializable<Tag>`
+- All primitive types
+- If `T`, `K` are supported types:
+   - `T[]`
+   - `Set<T>`
+   - `List<T>`,
+   - `Map<T, K>`
+- `String`
+- `ItemStack`
+- `FluidStack`
+- `UUID`
+- `BlockPos`
+- `CompoundTag`
+- `GTRecipe`
+- `GTRecipeType`
+- `MachineRenderState`
+- `Material`
+- `Component`
+
+### Adding support for additional types
+
+The `ValueTransformer<T>` abstract class defines how a value of type `T` should be serialized.
+
+To add support for an additional type, call `ValueTransformers.registerTransformer(Class<T> cls, ValueTransformer<T> transformer)` or `ValueTransformers.registerTransformerSupplier(Class<T> cls, Supplier<ValueTransformer<T>> func)`
+
+Additionally, fields can be explicitly directed to use a specific value transformer:
+```java
+/**
+ * Example from HullMachine.java. This example shows serialization of an AE2 class which may or may not be loaded at runtime.
+ */
+
+@SaveField(nbtKey = "grid_node")
+private final Object gridNodeHost;
+
+private static class GridNodeHostTransformer implements ValueTransformer<Object> {
+
+  @Override
+  public Tag serializeNBT(Object value, TransformerContext<Object> context) {
+    if (GTCEu.Mods.isAE2Loaded() &&
+            (context.currentValue()) instanceof IGridConnectedBlockEntity connectedBlockEntity) {
+      var compound = new CompoundTag();
+      connectedBlockEntity.getMainNode().saveToNBT(compound);
+      return compound;
+    }
+    return new CompoundTag();
+  }
+
+  @Override
+  public @Nullable Object deserializeNBT(Tag tag, TransformerContext<Object> context) {
+    if (GTCEu.Mods.isAE2Loaded() &&
+            context.currentValue() instanceof IGridConnectedBlockEntity connectedBlockEntity &&
+            tag instanceof CompoundTag c) {
+      connectedBlockEntity.getMainNode().loadFromNBT(c);
+    }
+    return null;
+  }
+}
+
+static {
+  ClassSyncData.getClassData(HullMachine.class).setCustomTransformerForField("gridNodeHost",
+          new GridNodeHostTransformer());
+}
+
+```

docs/content/Development/Data-Sync-System/index.md

@@ -0,0 +1,12 @@
+---
+title: "Data Sync/Save system "
+---
+
+# Data Sync/Save System
+
+For serialising data to saves and synchronising with clients, a custom data sync system based on Java Annotations is used.
+
+- See [Usage](Usage.md) for a guide on using the system
+- See [Annotations](Annotations.md) for a list of annotations provided by the system
+- See [Migrating From LDLib SyncData](Migrating-From-LDLib-SyncData.md) for instructions on how to migrate from the LDLib SyncData system, which was used in versions 7.x and lower.
+