Add ProgressBar/EnergyBar/FluidTank composables and energy storage

[KP2048]

Summary

• New GUI composables (gui/composables/basic/): ProgressBar (themed linear fill, 4 directions), EnergyBar (bottom-up by default, reads an ArchieEnergyStorage), FluidTank (renders the real fluid texture + tint via a new per-loader render bridge, since Fabric's FluidRenderHandlerRegistry and NeoForge's IClientFluidTypeExtensions expose a fluid's client appearance through unrelated APIs).
• New ArchieEnergyStorage (transfer/): implements Common Storage Lib's ValueStorage (the energy analogue of the CommonStorage<ItemResource>/CommonStorage<FluidResource> ArchieItemStorage/ArchieFluidStorage implement) plus Archie's NBT serialization, mirroring their shape exactly. Archie doesn't auto-register it with CSL's EnergyApi.BLOCK/ITEM/ENTITY lookups or bridge a platform energy capability (NeoForge IEnergyStorage, Fabric Team Reborn Energy) - matching the current (also-unregistered) state of item/fluid storage, left as consistent future work for all three.
• Filled a pre-existing gap: NBTHolder only exposed itemField() even though ArchieFluidStorage already existed. Added fluidField()/energyField() across all three NBTHolder implementations (NBTHolderImpl, ItemStackNBTHolderImpl, FluidStackNBTHolderImpl).
• Ships default "java" theme JSON + sprites for all three new composables (required, not optional - ComposableTheme throws if a composable's theme isn't registered).
• Docs updated: gui.md, transfer.md, serialization.md.

Test plan

• ./gradlew :common:compileKotlin - succeeds
• ./gradlew :fabric:compileKotlin - succeeds
• ./gradlew :neoforge:compileKotlin - succeeds
• ./gradlew :common:verifyGuiSpriteAssets - succeeds
• Full GameTest suite (not run this session - worth running before merge)
• Manual in-game check of FluidTank's fluid rendering (compile-verified only; the tint/sprite math wasn't visually confirmed against a running client)

🤖 Generated with Claude Code

[KP2048]

Caught + fixed: ArchieEnergyStorage now implements Common Storage Lib's ValueStorage (already an Archie dependency, exposes EnergyApi/EnergyProvider/ValueStorage that the first commit missed) instead of standing alone - matches ArchieItemStorage/ArchieFluidStorage's CommonStorage<T> pattern exactly. getAmount() renamed to getStoredAmount() to match the interface. Recompiled all three modules clean.

[Copilot]

Pull request overview

Adds new GUI indicators (progress/energy/fluid) and introduces a platform-agnostic energy storage type, extending NBTHolder to support item/fluid/energy delegated storage fields across its implementations. This fits into Archie’s existing GUI framework (Compose-based widgets + theme sprites) and transfer/serialization patterns (CSL storage types + NBT snapshotting + optional @Sync state-container wiring).

Changes:

• Added ProgressBar, EnergyBar, and FluidTank composables, including a cross-loader fluid render bridge for real fluid sprite + tint rendering.
• Introduced ArchieEnergyStorage (CSL ValueStorage + Archie NBT snapshot serialization).
• Extended NBTHolder (+ all implementations) with fluidField(...) and energyField(...), and updated docs + theme assets for the new composables.

Reviewed changes

Copilot reviewed 20 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
Archie/neoforge/src/main/kotlin/net/kernelpanicsoft/archie/gui/render/AFluidRenderPlatform.neoforge.kt	NeoForge actual implementation for fluid sprite/tint lookup via IClientFluidTypeExtensions.
Archie/fabric/src/main/kotlin/net/kernelpanicsoft/archie/gui/render/AFluidRenderPlatform.fabric.kt	Fabric actual implementation for fluid sprite/tint lookup via FluidRenderHandlerRegistry.
Archie/common/src/main/kotlin/net/kernelpanicsoft/archie/gui/render/AFluidRenderPlatform.common.kt	Common expect API for cross-loader fluid appearance lookups used by GUI rendering.
Archie/common/src/main/kotlin/net/kernelpanicsoft/archie/gui/composables/basic/ProgressBar.kt	New themed progress bar composable + shared fill rendering core.
Archie/common/src/main/kotlin/net/kernelpanicsoft/archie/gui/composables/basic/EnergyBar.kt	New energy bar composable (wraps shared fill bar; supports raw values or ArchieEnergyStorage).
Archie/common/src/main/kotlin/net/kernelpanicsoft/archie/gui/composables/basic/FluidTank.kt	New tank composable rendering real fluid sprite+tint with scissored fill.
Archie/common/src/main/kotlin/net/kernelpanicsoft/archie/transfer/ArchieEnergyStorage.kt	New energy buffer type implementing CSL ValueStorage + NBT snapshot serialization.
Archie/common/src/main/kotlin/net/kernelpanicsoft/archie/serialization/NBTHolder.kt	Adds fluidField(...) and energyField(...) delegate APIs to NBTHolder.
Archie/common/src/main/kotlin/net/kernelpanicsoft/archie/serialization/NBTHolderImpl.kt	Implements fluidField(...)/energyField(...) for general NBTHolder (incl. BE sync/persistence hooks).
Archie/common/src/main/kotlin/net/kernelpanicsoft/archie/serialization/ItemStackNBTHolderImpl.kt	Implements fluidField(...)/energyField(...) for item stack-backed holders + save/load wiring.
Archie/common/src/main/kotlin/net/kernelpanicsoft/archie/serialization/FluidStackNBTHolderImpl.kt	Implements fluidField(...)/energyField(...) for fluid stack-backed holders + save/load wiring.
Archie/docs/gui.md	Documents the new indicator composables and usage examples.
Archie/docs/transfer.md	Documents ArchieFluidStorage and ArchieEnergyStorage usage + GUI integration points.
Archie/docs/serialization.md	Updates NBTHolder field-type documentation + examples for fluid/energy.
Archie/common/src/main/resources/assets/archie/textures/gui/sprites/java/progress_bar.png.mcmeta	Adds nine-slice metadata for the progress bar sprite.
Archie/common/src/main/resources/assets/archie/textures/gui/sprites/java/energy_bar.png.mcmeta	Adds nine-slice metadata for the energy bar sprite.
Archie/common/src/main/resources/assets/archie/textures/gui/sprites/java/fluid_tank.png.mcmeta	Adds nine-slice metadata for the fluid tank sprite.
Archie/common/src/main/resources/assets/archie/archie_themes/java/progress_bar.json	Registers default “java” theme entry for progress bar.
Archie/common/src/main/resources/assets/archie/archie_themes/java/energy_bar.json	Registers default “java” theme entry for energy bar.
Archie/common/src/main/resources/assets/archie/archie_themes/java/fluid_tank.json	Registers default “java” theme entry for fluid tank.

Suppressed comments (1)

Archie/common/src/main/kotlin/net/kernelpanicsoft/archie/transfer/ArchieEnergyStorage.kt:118

• Serializer.deserialize can construct an ArchieEnergyStorage with a negative capacity or an out-of-range stored amount. Since this data may come from NBT/network sync, it should be sanitized the same way as readSnapshot to avoid invalid runtime state.

		override fun deserialize(decoder: Decoder): ArchieEnergyStorage
		{
			val capacity = decoder.decodeLong()
			val amount = decoder.decodeLong()
			return ArchieEnergyStorage(capacity).also { it.amount = amount }
		}

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.