Merge branch 'chore/archie-reorg-refactor-docs' into 1.21.x

Author: KP2048

AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS Guide for Archie
+
+## Repository shape
+- Multi-module Architectury mod: `common` (shared API/logic), `fabric`, `neoforge` (`settings.gradle.kts`).
+- `common` is the source of truth; loader modules mostly provide bootstrapping, loader deps, and `actual` implementations.
+- Main entrypoint flow is `Archie.init()` -> register events/network/config/datagen/gametest gates (`common/src/main/kotlin/net/kernelpanicsoft/archie/Archie.kt`).
+
+## Architecture patterns to preserve
+- Cross-loader abstractions use Kotlin `expect/actual` files named `*.common.kt`, `*.fabric.kt`, `*.neoforge.kt` (example: `APlatform`, `ADataGeneratorPlatform`, `AGameTestPlatform`).
+- Loader entrypoints must only delegate into common init methods:
+  - Fabric: `ArchieFabric.onInitialize*` (`fabric/src/main/kotlin/net/kernelpanicsoft/archie/ArchieFabric.kt`)
+  - NeoForge: bus listeners in `ArchieNeoForge` (`neoforge/src/main/kotlin/net/kernelpanicsoft/archie/ArchieNeoForge.kt`)
+- Networking is centralized via `NetworkChannel`; packets must be `@Serializable data class` and registered before `register()` (`common/src/main/kotlin/net/kernelpanicsoft/archie/networking/NetworkChannel.kt`).
+- `ArchieNetworkChannel.init()` is the canonical registration order example (register packet producers/consumers, then call `register()`).
+
+## Build and run workflows
+- Build all modules + merged artifact: `./gradlew build` (root `build`/`assemble` finalize with `fusejars` in `build.gradle.kts`).
+- Loader-specific dev runs: `./gradlew fabric:runClient`, `./gradlew neoforge:runClient`.
+- Datagen runs are explicit tasks: `./gradlew fabric:runDatagen` / `./gradlew neoforge:runDatagen`.
+- GameTest runs: `./gradlew fabric:runGametest` / `./gradlew neoforge:runGametest`.
+- Docs pipeline: `embedDokkaIntoMkDocs` then `publishDocs` (calls `mike deploy ...`); `mkdocs.yml` contains `# !!! EMBEDDED DOKKA ... DO NOT COMMIT !!!` markers.
+
+## Project-specific conventions
+- Keep resource/manifests tokenized using Gradle properties (`${mod_id}`, `${versions.*}`) in `fabric.mod.json` and `neoforge.mods.toml`.
+- Shared assets are merged from `common` into loader modules via `processResources`; do not duplicate `assets/archie/**` directly in loader modules unless loader-specific.
+- `common/build.gradle.kts` intentionally uses `modImplementation(libs.fabric.loader)` only for annotations/mixin deps; avoid importing random Fabric-only classes in common code.
+- Utility operators are used pervasively for IDs (`Archie % "main"`, `"namespace" % "path"`) from `common/src/main/kotlin/net/kernelpanicsoft/archie/util/ResourceLocation.kt`.
+
+## Dependency and integration touchpoints
+- Versions and plugin IDs are centralized in `gradle/libs.versions.toml`; update there first.
+- Packaging/publishing is configured at root via `modfusioner` (`fusejars`) and `modpublisher` (CurseForge/Modrinth IDs and required deps) in `build.gradle.kts`.
+- Mixins are split by scope: loader mixins in `fabric/src/main/resources/archie.mixins.json` and `neoforge/src/main/resources/archie.mixins.json`, common mixin config in `common/src/main/resources/archie-common.mixins.json`.
+
+## Safe edit boundaries
+- For new gameplay/library logic: start in `common/src/main/kotlin/...`, then add loader `actual`/bootstrap only when APIs differ.
+- When adding packets/events/config sections, mirror existing object-singleton style (`Archie`, `AEvents`, `ArchieNetworkChannel`) rather than introducing DI/service containers.
+- If adding new runtime libraries to shipped jars, use `bundleRuntimeLibrary(...)` / `bundleMod(...)` in loader `build.gradle.kts` files (not plain `implementation` only).

README.md

@@ -0,0 +1,47 @@
+# Archie
+
+Archie is a Kotlin-first Architectury library mod for Minecraft 1.21.1.
+It provides shared utilities used by Kernel Panic mods across Fabric and NeoForge.
+
+## Module layout
+
+- `common/`: shared APIs and core implementation (`Archie`, networking, config, GUI, data helpers)
+- `fabric/`: Fabric entrypoints, run configs, platform `actual` implementations
+- `neoforge/`: NeoForge entrypoints, run configs, platform `actual` implementations
+
+The initialization flow is:
+
+1. Loader entrypoint (`ArchieFabric` or `ArchieNeoForge`)
+2. `Archie.init()` in `common`
+3. Shared systems register events/network/config and optional datagen/gametest hooks
+
+## Common workflows
+
+```bash
+./gradlew build
+./gradlew fabric:runClient
+./gradlew neoforge:runClient
+./gradlew fabric:runDatagen
+./gradlew neoforge:runDatagen
+./gradlew fabric:runGametest
+./gradlew neoforge:runGametest
+```
+
+`build` and `assemble` finalize with `fusejars` (merged Fabric+NeoForge artifact).
+
+## Conventions that matter
+
+- Add gameplay/library logic in `common` first, then platform-specific `actual` code only when needed.
+- Keep `expect/actual` triplets named `*.common.kt`, `*.fabric.kt`, `*.neoforge.kt`.
+- Register packet classes and handlers before calling `register()` on `NetworkChannel`.
+- Keep loader manifests tokenized (`${mod_id}`, `${versions.*}`); values come from Gradle properties/version catalog.
+- Use `bundleRuntimeLibrary(...)` / `bundleMod(...)` for shipped runtime deps in loader modules.
+
+## Key files
+
+- `common/src/main/kotlin/net/kernelpanicsoft/archie/Archie.kt`
+- `common/src/main/kotlin/net/kernelpanicsoft/archie/networking/NetworkChannel.kt`
+- `fabric/src/main/kotlin/net/kernelpanicsoft/archie/ArchieFabric.kt`
+- `neoforge/src/main/kotlin/net/kernelpanicsoft/archie/ArchieNeoForge.kt`
+- `gradle/libs.versions.toml`
+

common/src/main/kotlin/net/kernelpanicsoft/archie/Archie.kt

@@ -62,7 +62,9 @@ object Archie
 	{
 		if (Platform.isMinecraftForge())
 			error("LexForge is not supported. Switch to NeoForge, or don't use my mods.")
+		// Register mod-scoped hooks first so downstream modules can subscribe during init.
 		AEvents += MOD
+		// Register packet handlers before any features try to send packets.
 		ArchieNetworkChannel.init()
 		BlockEntityStateManager.init()
 
@@ -72,6 +74,7 @@ object Archie
 		Config.init()
 
 
+		// Datagen and GameTest code paths are only activated in dedicated run configs.
 		if (AGameTestPlatform.isGameTest)
 			ArchieGameTest.init()
 		if (ADataGeneratorPlatform.isDataGen)

common/src/main/kotlin/net/kernelpanicsoft/archie/data/ADataGeneratorPlatform.common.kt

@@ -1,6 +1,10 @@
 package net.kernelpanicsoft.archie.data
 
-
+/**
+ * Cross-loader datagen switch.
+ *
+ * Loader implementations resolve this from run configuration system properties.
+ */
 expect object ADataGeneratorPlatform
 {
 	val isDataGen: Boolean

common/src/main/kotlin/net/kernelpanicsoft/archie/data/client/model/AModelBuilder.kt

@@ -180,7 +180,7 @@ open class AModelBuilder<T : AModelBuilder<T>>(location: ResourceLocation) : AMo
 		return rootTransforms.apply(block)
 	}
 
-	private fun BlockElement.uvsByFace(face: Direction): FloatArray
+	private fun BlockElement.computeUvsByFace(face: Direction): FloatArray
 	{
 		when (face)
 		{
@@ -339,7 +339,7 @@ open class AModelBuilder<T : AModelBuilder<T>>(location: ResourceLocation) : AMo
 
 						val faceObj = JsonObject()
 						faceObj.addProperty("texture", serializeLocOrKey(face.texture))
-						if (!face.uv.uvs.contentEquals(part.uvsByFace(dir)))
+									if (!face.uv.uvs.contentEquals(part.computeUvsByFace(dir)))
 						{
 							faceObj.add("uv", Gson().toJsonTree(face.uv.uvs))
 						}

common/src/main/kotlin/net/kernelpanicsoft/archie/data/util/TransformationHelper.kt

@@ -204,18 +204,18 @@ object TransformationHelper
 			)
 
 			val matrix = Transformation(translation, leftRot, scale, rightRot)
-			return matrix.applyOrigin(Vector3f(origin))
+			return matrix.applyOriginLocal(Vector3f(origin))
 		}
 
-		fun Transformation.isIdentity(): Boolean
+		fun Transformation.isIdentityLocal(): Boolean
 		{
-			return this@isIdentity == Transformation.identity()
+			return this@isIdentityLocal == Transformation.identity()
 		}
 
-		fun Transformation.applyOrigin(origin: Vector3f): Transformation
+		fun Transformation.applyOriginLocal(origin: Vector3f): Transformation
 		{
-			val transform: Transformation = this@applyOrigin
-			if (transform.isIdentity()) return Transformation.identity()
+			val transform: Transformation = this@applyOriginLocal
+			if (transform.isIdentityLocal()) return Transformation.identity()
 
 			val ret = transform.matrix
 			val tmp = Matrix4f().translation(origin.x(), origin.y(), origin.z())

common/src/main/kotlin/net/kernelpanicsoft/archie/events/AEvents.kt

@@ -9,18 +9,27 @@ import dev.architectury.platform.Mod
 
 object AEvents
 {
+	/** Fired during datagen runs; handlers should gate by owning [Mod]. */
 	val GATHER_DATA: Event<GatherDataHandler> = EventFactory.createEventResult()
 
+	/** Fired during gametest registration runs; handlers should register test classes per [Mod]. */
 	val REGISTER_GAME_TEST: Event<RegisterGameTestHandler> = EventFactory.createEventResult()
 
-	val MODS: List<Mod> = mutableListOf()
+	private val mods: MutableList<Mod> = mutableListOf()
 
-	fun register(mod: Mod) = (MODS as MutableList<Mod>).add(mod).let {  }
+	/** Mods that opted into Archie event plumbing via `AEvents += MOD`. */
+	val MODS: List<Mod>
+		get() = mods
+
+	fun register(mod: Mod)
+	{
+		mods.add(mod)
+	}
 
 	operator fun plusAssign(mod: Mod) = register(mod)
 
 	interface Handler<T>
-	
+
 	fun interface HandlerConstructor<T, H : Handler<T>>
 	{
 		fun create(mod: Mod, block: T.() -> Unit): H

common/src/main/kotlin/net/kernelpanicsoft/archie/gametest/AGameTestPlatform.common.kt

@@ -2,9 +2,15 @@ package net.kernelpanicsoft.archie.gametest
 
 import dev.architectury.platform.Mod
 
+/**
+ * Cross-loader GameTest integration point.
+ *
+ * Implementations detect whether GameTest mode is active and collect test classes per mod.
+ */
 expect object AGameTestPlatform
 {
 	val isGameTest: Boolean
 
+	/** Register a test class for [mod] when GameTest bootstrapping occurs. */
 	fun register(clazz: Class<*>, mod: Mod)
 }

common/src/main/kotlin/net/kernelpanicsoft/archie/gui/blockentity/BlockEntityStatePacketRegistry.kt

@@ -76,6 +76,7 @@ object BlockEntityStatePacketRegistry {
 /**
  * Extension function to convert SerializedValue back to its original Kotlin type.
  */
+@OptIn(ExperimentalSerializationApi::class)
 internal fun BlockEntityStatePacket.SerializedValue.deserialize(serializer: KSerializer<out Any>? = null): Any? = when (this) {
     is BlockEntityStatePacket.SerializedValue.IntValue -> this.value
     is BlockEntityStatePacket.SerializedValue.StringValue -> this.value

common/src/main/kotlin/net/kernelpanicsoft/archie/networking/NetworkChannel.kt

@@ -146,13 +146,12 @@ open class NetworkChannel(private val id: ResourceLocation) {
     fun <T : Any> toServer(vararg packets: T) {
         require(packets.isNotEmpty()) { "You need to specify one or more packets to send" }
         packets.map {
-            @Suppress("UNCHECKED_CAST")
-            val klass = serverClasses.find { x -> x == it::class } as? KClass<T>
-                ?: throw IllegalStateException("Trying to send a packet to server but it hasn't registered the packet and its handler")
-            val index = serverClasses.indexOf(klass)
-            val bytes = SerializationManager.cbor.encodeToByteArray(klass.serializer(), it)
-
-            Payload(id.withSuffix("_client"), index, bytes)
+            createPayload(
+                packet = it,
+                classes = serverClasses,
+                payloadId = id.withSuffix("_client"),
+                missingMessage = "Trying to send a packet to server but it hasn't registered the packet and its handler",
+            )
         }.forEach { NetworkManager.sendToServer(it) }
     }
 
@@ -270,14 +269,45 @@ open class NetworkChannel(private val id: ResourceLocation) {
     @Suppress("UNCHECKED_CAST")
     private fun <T : Any> createPayloads(packets: Array<out T>): List<Payload> {
         return packets.map {
-            val klass = clientClasses.find { x -> x == it::class } as? KClass<T>
-                ?: throw IllegalStateException("Trying to send a packet to clients but client hasn't registered the packet and its handler")
-            val index = clientClasses.indexOf(klass)
-            val bytes = SerializationManager.cbor.encodeToByteArray(klass.serializer(), it)
-            Payload(id.withSuffix("_server"), index, bytes)
+            createPayload(
+                packet = it,
+                classes = clientClasses,
+                payloadId = id.withSuffix("_server"),
+                missingMessage = "Trying to send a packet to clients but client hasn't registered the packet and its handler",
+            )
         }
     }
 
+    @Suppress("UNCHECKED_CAST")
+    private fun <T : Any> createPayload(
+        packet: T,
+        classes: List<KClass<*>>,
+        payloadId: ResourceLocation,
+        missingMessage: String,
+    ): Payload {
+        val klass = classes.find { it == packet::class } as? KClass<T>
+            ?: throw IllegalStateException(missingMessage)
+        val index = classes.indexOf(klass)
+        val bytes = SerializationManager.cbor.encodeToByteArray(klass.serializer(), packet)
+        return Payload(payloadId, index, bytes)
+    }
+
+    @Suppress("UNCHECKED_CAST")
+    private fun decodeDispatchData(
+        payload: Payload,
+        classes: List<KClass<*>>,
+        handlers: List<PacketHandler<*>>,
+        missingClassMessage: String,
+        missingHandlerMessage: String,
+    ): Pair<Any, PacketHandler<Any>> {
+        val klass = classes.getOrNull(payload.index)
+            ?: throw NoSuchElementException(missingClassMessage)
+        val handler = handlers.getOrNull(payload.index) as? PacketHandler<Any>
+            ?: throw NoSuchElementException(missingHandlerMessage)
+        val msg = SerializationManager.cbor.decodeFromByteArray(klass.serializer(), payload.data)
+        return msg to handler
+    }
+
     private fun makeClientboundPacket(vararg payloads: CustomPacketPayload): Packet<*> {
         return if (payloads.size == 1) ClientboundCustomPayloadPacket(payloads.first())
         else ClientboundBundlePacket(payloads.map { ClientboundCustomPayloadPacket(it) })
@@ -292,23 +322,27 @@ open class NetworkChannel(private val id: ResourceLocation) {
     @Suppress("UNCHECKED_CAST")
     fun register() {
         NetworkManager.registerReceiver(NetworkManager.Side.S2C, serverPacketId, PayloadCodec) { payload, ctx ->
-            val klass = clientClasses.getOrNull(payload.index)
-                ?: throw NoSuchElementException("No class was found on the clientside. Did you forget to do clientbound?")
-            val handler = clientboundHandlers.getOrNull(payload.index) as? PacketHandler<Any>
-                ?: throw NoSuchElementException("No handler was found on the clientside. Did you forget to do clientbound?")
-            val msg = SerializationManager.cbor.decodeFromByteArray(klass.serializer(), payload.data)
+            val (msg, handler) = decodeDispatchData(
+                payload = payload,
+                classes = clientClasses,
+                handlers = clientboundHandlers,
+                missingClassMessage = "No class was found on the clientside. Did you forget to do clientbound?",
+                missingHandlerMessage = "No handler was found on the clientside. Did you forget to do clientbound?",
+            )
             handler(msg, object : IPacketContext {
                 override val player: Player get() = ctx.player
                 override val registryAccess: RegistryAccess get() = ctx.registryAccess()
             })
         }
 
         NetworkManager.registerReceiver(NetworkManager.Side.C2S, clientPacketId, PayloadCodec) { payload, ctx ->
-            val klass = serverClasses.getOrNull(payload.index)
-                ?: throw NoSuchElementException("No class was found on the serverside. Did you forget to do serverbound?")
-            val handler = serverboundHandlers.getOrNull(payload.index) as? PacketHandler<Any>
-                ?: throw NoSuchElementException("No handler was found on the serverside. Did you forget to do serverbound?")
-            val msg = SerializationManager.cbor.decodeFromByteArray(klass.serializer(), payload.data)
+            val (msg, handler) = decodeDispatchData(
+                payload = payload,
+                classes = serverClasses,
+                handlers = serverboundHandlers,
+                missingClassMessage = "No class was found on the serverside. Did you forget to do serverbound?",
+                missingHandlerMessage = "No handler was found on the serverside. Did you forget to do serverbound?",
+            )
             handler(msg, object : IPacketContext {
                 override val player: Player get() = ctx.player
                 override val registryAccess: RegistryAccess get() = ctx.registryAccess()