Add system for Dynamic Registry Flags (QuiltMC#330)

* Implement Dynamic Registry Flags.
- Currently, only one flag, `OPTIONAL`, exists.
- Modified DynamicRegistrySyncMixin in order to implement these flags. Due to the Redirect mixin header used to implement the flag filtering being taken directly from FAPI, the header of DynamicRegistrySyncMixin was changed to mention FabricMC copyright, in accordance with QSL contribution rules in CONTRIBUTING.md

* Implement Dynamic Registry Flags p2
- Modify DynamicRegistryFlagManager to use Identifiers over RegistryKeys internally, in order to avoid generic-related jank.
- Fix mixin ported from FAPI by correcting method target string to use Quilt Mappings.
- Implement very basic tests.

* Expanded upon OPTIONAL flag javadocs to elaborate use-case

* Expanded further on OPTIONAL javadocs

* Implemented some changes suggested by Pyrofab

- Added protected helper method DynamicMetaRegistryImpl#isFrozen for use in DynamicRegistryFlagManager
- Added DynamicMetaRegistryImpl#LOGGER with the name "quilt_dynamic_registries" as a logger for catching exceptions related to the setting of flags
- Removed the ability to disable dynamic registry flags, changed the signature of the related flag-enabling methods from enableFlag -> setFlag (on both DynamicRegistryFlag and DynamicRegistryFlagManager)
- DynamicRegistryFlagManager#setFlag now throws an IllegalStateException if a mod attempts to enable a flag when dynamic registries are frozen. This is caught and printed to the logger mentioned prior in DynamicRegistryFlag calls
- Added varargs for setting DynamicRegistryFlag values on dynamic registry creation
- Improved DynamicRegistryFlag#OPTIONAL javadocs slightly

* Commit most style changes

One of them needs a more specific wording change, so it's going to be done in another commit since that's easier for us

Co-authored-by: Ennui Langeweile <[email protected]>

* Make documentation for DynamicRegistryFlag more accurate

* Improve the javadocs on DynamicRegistryFlag AGAIN

accidentally dropped a word

guh

* BUT WAIT, THERE'S MORE!

Hopefully the final style change moment

Co-authored-by: Ennui Langeweile <[email protected]>

* Implement style change in DynamicRegistryFlagManager

Co-authored-by: LambdAurora <[email protected]>

* Fix binary incompatibility hopefully?
- Added back methods to DynamicMetaRegistry with the same signature as the old ones to avoid binary incompatibility. These are marked as deprecated and should be removed in a breaking/major QSL release.

* Remove deprecation annotations on compat. method overloads in DynamicMetaRegistry

---------

Co-authored-by: Ennui Langeweile <[email protected]>
Co-authored-by: LambdAurora <[email protected]>

library/core/registry/src/main/java/org/quiltmc/qsl/registry/api/dynamic/DynamicMetaRegistry.java

@@ -36,6 +36,57 @@
  * This registry will be frozen at the same time as static registries.
  */
 public final class DynamicMetaRegistry {
+	/**
+	 * Registers a server-side dynamic registry.
+	 * <p>
+	 * Entries will be loaded from {@code "data/<namespace>/<registry_namespace>/<registry_path>"} for every datapack
+	 * {@code namespace}, where {@code registry_namespace} and {@code registry_path}'s values are respectively
+	 * {@code key.getLocation().getNamespace()} and {@code key.getLocation().getPath()}.
+	 *
+	 * @param <E>        the type of elements in the dynamic registry
+	 * @param key        a {@link RegistryKey#ofRegistry(Identifier) key for the new dynamic registry}
+	 * @param entryCodec the codec used to deserialize entries from datapacks
+	 * @throws IllegalStateException if this registry of registries already got frozen
+	 */
+	public static <E> void register(RegistryKey<? extends Registry<E>> key, Codec<E> entryCodec, DynamicRegistryFlag... flags) {
+		DynamicMetaRegistryImpl.register(key, entryCodec, flags);
+	}
+
+	/**
+	 * Registers a dynamic registry which contents get synced between the server and connected clients.
+	 * <p>
+	 * Entries will be loaded from {@code "data/<namespace>/<registry_namespace>/<registry_path>"} for every datapack
+	 * {@code namespace}, where {@code registry_namespace} and {@code registry_path}'s values are respectively
+	 * {@code key.getLocation().getNamespace()} and {@code key.getLocation().getPath()}.
+	 *
+	 * @param <E>        the type of elements in the dynamic registry
+	 * @param key        a {@link RegistryKey#ofRegistry(Identifier) key for the new dynamic registry}
+	 * @param entryCodec the codec used to both deserialize entries from datapacks and (de)serialize entries to and from packets
+	 * @throws IllegalStateException if this registry of registries already got frozen
+	 * @see #registerSynced(RegistryKey, Codec, Codec, DynamicRegistryFlag...)
+	 */
+	public static <E> void registerSynced(RegistryKey<? extends Registry<E>> key, Codec<E> entryCodec, DynamicRegistryFlag... flags) {
+		DynamicMetaRegistryImpl.registerSynced(key, entryCodec, entryCodec, flags);
+	}
+
+	/**
+	 * Registers a dynamic registry which contents get synced between the server and connected clients.
+	 * <p>
+	 * Entries will be loaded from {@code "data/<namespace>/<registry_namespace>/<registry_path>"} for every datapack
+	 * {@code namespace}, where {@code registry_namespace} and {@code registry_path}'s values are respectively
+	 * {@code key.getLocation().getNamespace()} and {@code key.getLocation().getPath()}.
+	 *
+	 * @param <E>        the type of elements in the dynamic registry
+	 * @param key        a {@link RegistryKey#ofRegistry(Identifier) key for the new dynamic registry}
+	 * @param entryCodec the codec used to deserialize entries from datapacks
+	 * @param syncCodec  the codec used to (de)serialize entries to and from packets - may be the same as {@code entryCodec}
+	 * @throws IllegalStateException if this registry of registries already got frozen
+	 * @see #registerSynced(RegistryKey, Codec, DynamicRegistryFlag...)
+	 */
+	public static <E> void registerSynced(RegistryKey<? extends Registry<E>> key, Codec<E> entryCodec, Codec<E> syncCodec, DynamicRegistryFlag... flags) {
+		DynamicMetaRegistryImpl.registerSynced(key, entryCodec, syncCodec, flags);
+	}
+
 	/**
 	 * Registers a server-side dynamic registry.
 	 * <p>

library/core/registry/src/main/java/org/quiltmc/qsl/registry/api/dynamic/DynamicRegistryFlag.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright 2023 The Quilt Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.quiltmc.qsl.registry.api.dynamic;
+
+import net.minecraft.registry.RegistryKey;
+import net.minecraft.util.Identifier;
+
+import org.quiltmc.qsl.registry.impl.dynamic.DynamicMetaRegistryImpl;
+import org.quiltmc.qsl.registry.impl.dynamic.DynamicRegistryFlagManager;
+
+/**
+ * Flags that can be set on dynamic registries to define their behavior.
+ * <p>
+ * All flags are off by default, and can be enabled using static methods in this class or on dynamic registry creation via varargs.
+ *
+ * @see org.quiltmc.qsl.registry.api.sync.RegistrySynchronization  org.quiltmc.qsl.registry.api.sync.RegistrySynchronization,
+ * which contains similar flag setters/getters for static registries
+ */
+public enum DynamicRegistryFlag {
+	/**
+	 * Indicates that this registry (and the entries within) do not necessarily need to be sent
+	 * to (logical) clients for synchronization in multiplayer contexts.
+	 * <p>
+	 * <b>Note:</b> This flag is intended only for synchronized dynamic registries. On non-synced dynamic registries, this flag does nothing.
+	 * <p>
+	 * One use-case for this flag is for creating mods that are entirely compatible with vanilla, and thus do not
+	 * require the dynamic registry to exist clientside to connect to the server.
+	 * This allows for both vanilla clients/clients without the mod to connect <i>and</i> for clients with the mod
+	 * supplying the registry to connect, with the latter being able to see the contents of the registry and possibly
+	 * enable extra clientside features accordingly.
+	 */
+	OPTIONAL;
+
+	/**
+	 * Enables a specific flag on a dynamic registry.
+	 *
+	 * @param registryId the value id ({@link RegistryKey#getValue()}) of the target dynamic registry
+	 * @param flag the flag value to enable on the dynamic registry
+	 */
+	public static void setFlag(Identifier registryId, DynamicRegistryFlag flag) {
+		try {
+			DynamicRegistryFlagManager.setFlag(registryId, flag);
+		} catch (Exception e) {
+			logFlagModifyException(registryId, flag, e);
+		}
+	}
+
+	/**
+	 * Checks if a dynamic registry has the {@link DynamicRegistryFlag#OPTIONAL} flag enabled on it.
+	 *
+	 * @param registryId the value id ({@link RegistryKey#getValue()}) of the dynamic registry to check
+	 * @return whether the checked dynamic registry has the {@link DynamicRegistryFlag#OPTIONAL} flag enabled
+	 */
+	public static boolean isOptional(Identifier registryId) {
+		return DynamicRegistryFlagManager.isOptional(registryId);
+	}
+
+	/**
+	 * Helper method for logging exceptions to avoid code duplication.
+	 */
+	private static void logFlagModifyException(Identifier registryId, DynamicRegistryFlag flag, Exception e) {
+		DynamicMetaRegistryImpl.LOGGER.error("Caught exception while attempting to enable flag {} on registry id {}: {}", flag.toString(), registryId, e.toString());
+	}
+}

library/core/registry/src/main/java/org/quiltmc/qsl/registry/impl/dynamic/DynamicMetaRegistryImpl.java

@@ -22,31 +22,39 @@
 import com.google.common.collect.ImmutableMap;
 import com.mojang.serialization.Codec;
 import org.jetbrains.annotations.ApiStatus;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import net.minecraft.registry.Registry;
 import net.minecraft.registry.RegistryKey;
 import net.minecraft.registry.RegistryLoader;
 import net.minecraft.util.Identifier;
 
 import org.quiltmc.qsl.registry.mixin.DynamicRegistrySyncAccessor;
+import org.quiltmc.qsl.registry.api.dynamic.DynamicRegistryFlag;
 
 @ApiStatus.Internal
 public class DynamicMetaRegistryImpl {
 	private static boolean frozen;
 	private static final Set<Identifier> MODDED_REGISTRY_IDS = new HashSet<>();
 
+	public static final Logger LOGGER = LoggerFactory.getLogger("quilt_dynamic_registries");
+
 	public static boolean isModdedRegistryId(Identifier id) {
 		return MODDED_REGISTRY_IDS.contains(id);
 	}
 
-	public static <E> void register(RegistryKey<? extends Registry<E>> ref, Codec<E> entryCodec) {
+	public static <E> void register(RegistryKey<? extends Registry<E>> ref, Codec<E> entryCodec, DynamicRegistryFlag... flags) {
 		if (frozen) throw new IllegalStateException("Registry is already frozen");
 		MODDED_REGISTRY_IDS.add(ref.getValue());
 		RegistryLoader.WORLDGEN_REGISTRIES.add(new RegistryLoader.DecodingData<>(ref, entryCodec));
+		for (DynamicRegistryFlag flag : flags) {
+			DynamicRegistryFlagManager.setFlag(ref.getValue(), flag);
+		}
 	}
 
-	public static <E> void registerSynced(RegistryKey<? extends Registry<E>> ref, Codec<E> entryCodec, Codec<E> syncCodec) {
-		register(ref, entryCodec);
+	public static <E> void registerSynced(RegistryKey<? extends Registry<E>> ref, Codec<E> entryCodec, Codec<E> syncCodec, DynamicRegistryFlag... flags) {
+		register(ref, entryCodec, flags);
 		var builder = ImmutableMap.<RegistryKey<? extends Registry<?>>, Object>builder().putAll(DynamicRegistrySyncAccessor.quilt$getSyncedCodecs());
 		DynamicRegistrySyncAccessor.quilt$invokeAddSyncedRegistry(builder, ref, syncCodec);
 		DynamicRegistrySyncAccessor.quilt$setSyncedCodecs(builder.build());
@@ -55,4 +63,8 @@ public static <E> void registerSynced(RegistryKey<? extends Registry<E>> ref, Co
 	public static void freeze() {
 		frozen = true;
 	}
+
+	static boolean isFrozen() {
+		return frozen;
+	}
 }

library/core/registry/src/main/java/org/quiltmc/qsl/registry/impl/dynamic/DynamicRegistryFlagManager.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright 2023 The Quilt Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.quiltmc.qsl.registry.impl.dynamic;
+
+import org.jetbrains.annotations.ApiStatus;
+import com.google.common.collect.Multimap;
+import com.google.common.collect.MultimapBuilder;
+
+import net.minecraft.util.Identifier;
+
+import org.quiltmc.qsl.registry.api.dynamic.DynamicRegistryFlag;
+
+@ApiStatus.Internal
+public final class DynamicRegistryFlagManager {
+	private static final Multimap<Identifier, DynamicRegistryFlag> DYNAMIC_REGISTRY_FLAGS =
+			MultimapBuilder.hashKeys().enumSetValues(DynamicRegistryFlag.class).build();
+
+	public static void setFlag(Identifier registryId, DynamicRegistryFlag flag) throws IllegalStateException {
+		if (DynamicMetaRegistryImpl.isFrozen()) {
+			throw new IllegalStateException("Dynamic registries are frozen, and thus flags cannot be changed!");
+		}
+
+		if (!DynamicMetaRegistryImpl.isModdedRegistryId(registryId)) return;
+
+		DYNAMIC_REGISTRY_FLAGS.put(registryId, flag);
+	}
+
+	public static boolean isOptional(Identifier registryId) {
+		if (DYNAMIC_REGISTRY_FLAGS.containsKey(registryId)) {
+			return DYNAMIC_REGISTRY_FLAGS.get(registryId).contains(DynamicRegistryFlag.OPTIONAL);
+		}
+
+		return false;
+	}
+}

library/core/registry/src/main/java/org/quiltmc/qsl/registry/mixin/DynamicRegistrySyncMixin.java

@@ -1,4 +1,5 @@
 /*
+ * Copyright 2016, 2017, 2018, 2019 FabricMC
  * Copyright 2023 The Quilt Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
@@ -17,21 +18,53 @@
 package org.quiltmc.qsl.registry.mixin;
 
 import java.util.Map;
+import java.util.stream.Stream;
 
+import org.spongepowered.asm.mixin.Dynamic;
 import org.spongepowered.asm.mixin.Final;
 import org.spongepowered.asm.mixin.Mixin;
 import org.spongepowered.asm.mixin.Mutable;
 import org.spongepowered.asm.mixin.Shadow;
+import org.spongepowered.asm.mixin.Unique;
+import org.spongepowered.asm.mixin.injection.At;
+import org.spongepowered.asm.mixin.injection.Redirect;
 
+import net.minecraft.registry.DynamicRegistryManager;
 import net.minecraft.registry.DynamicRegistrySync;
 import net.minecraft.registry.Registry;
 import net.minecraft.registry.RegistryKey;
 
+import org.quiltmc.qsl.registry.impl.dynamic.DynamicRegistryFlagManager;
+
 @Mixin(DynamicRegistrySync.class)
 public abstract class DynamicRegistrySyncMixin {
 	@SuppressWarnings("unused")	// makes the field mutable for use by the accessor
 	@Shadow
 	@Final
 	@Mutable
 	private static Map<RegistryKey<? extends Registry<?>>, ?> SYNCED_CODECS;
+	@Unique
+	private static boolean filterRegistryEntry(DynamicRegistryManager.RegistryEntry<?> entry) {
+		// OPTIONAL
+		if (DynamicRegistryFlagManager.isOptional(entry.key().getValue())) {
+			return entry.value().size() > 0;
+		}
+
+		return true; // If no flags apply, always return true
+	}
+
+	@Shadow
+	private static Stream<DynamicRegistryManager.RegistryEntry<?>> streamSyncedRegistries(DynamicRegistryManager registryManager) {
+		throw new IllegalStateException("Mixin injection failed.");
+	}
+
+	/**
+	 * This redirect mixin's annotation was taken directly from Fabric API (and adapted for Quilt Mappings), the rest of this file was not.
+	 */
+	@Dynamic("method_45961: Codec.xmap in buildManagerCodec")
+	@Redirect(method = "method_45961",
+			at = @At(value = "INVOKE", target = "Lnet/minecraft/registry/DynamicRegistrySync;streamSyncedRegistries(Lnet/minecraft/registry/DynamicRegistryManager;)Ljava/util/stream/Stream;"))
+	private static Stream<DynamicRegistryManager.RegistryEntry<?>> filterNonSyncedEntries(DynamicRegistryManager drm) {
+		return streamSyncedRegistries(drm).filter(DynamicRegistrySyncMixin::filterRegistryEntry);
+	}
 }

library/core/registry/src/testmod/java/org/quiltmc/qsl/registry/test/dynamic/RegistryLibDynamicRegistryTest.java

@@ -34,6 +34,7 @@
 import org.quiltmc.loader.api.ModContainer;
 import org.quiltmc.qsl.base.api.entrypoint.ModInitializer;
 import org.quiltmc.qsl.registry.api.dynamic.DynamicMetaRegistry;
+import org.quiltmc.qsl.registry.api.dynamic.DynamicRegistryFlag;
 import org.quiltmc.qsl.registry.api.event.RegistryEvents;
 import org.quiltmc.qsl.tag.api.TagRegistry;
 import org.quiltmc.qsl.tag.api.TagRegistry.TagValues;
@@ -49,7 +50,7 @@ public class RegistryLibDynamicRegistryTest implements QuiltGameTest, ModInitial
 
 	@Override
 	public void onInitialize(ModContainer mod) {
-		DynamicMetaRegistry.registerSynced(Greetings.REGISTRY_KEY, Greetings.CODEC);
+		DynamicMetaRegistry.registerSynced(Greetings.REGISTRY_KEY, Greetings.CODEC, DynamicRegistryFlag.OPTIONAL);
 		RegistryEvents.DYNAMIC_REGISTRY_SETUP.register(context -> context.register(Greetings.REGISTRY_KEY, GREETING_B_ID, () -> GREETING_B));
 	}
 
@@ -58,6 +59,7 @@ public void greetingsGetLoaded(QuiltTestContext ctx) {
 		Registry<Greetings> greetingsRegistry = ctx.getWorld().getRegistryManager().get(Greetings.REGISTRY_KEY);
 
 		ctx.succeedIf(() -> {
+			ctx.assertTrue(DynamicRegistryFlag.isOptional(Greetings.REGISTRY_KEY.getValue()), "Registry should always have the OPTIONAL flag enabled");
 			ctx.assertTrue(greetingsRegistry.containsId(GREETING_A_ID), "Registry should contain modded data value from datapack");
 			ctx.assertTrue(Objects.requireNonNull(greetingsRegistry.get(GREETING_A_ID)).equals(GREETING_A), "Modded value should be properly parsed from data file");
 			ctx.assertTrue(GREETING_B.equals(greetingsRegistry.get(GREETING_B_ID)), "Registry should contain modded data value from event");