CC2 Phase 1: deep-slot storage engine

[rubensworks]

Phase 1 of the Colossal Chests 2 plan (D-2, D-3). Phase 0 (#214) is merged, so the diff only contains Phase 1.

Summary

Everything is in org.cyclops.colossalchests2.storage. It uses ItemStack and components only, with no blocks, block entities or menus.

• DeepSlot: an immutable slot holding a prototype (count 1), a long count, a locked flag and an optional compression form. The form is the item the player picked to extract in, stored as an item rather than an index into the compression family so it survives datapack changes to the family. It normalizes itself: a type with count 0 only survives while locked.
• CapacityProfile: only resolved values: depth (stacks per slot), non-stackable capacity, technical cap maxItemsPerSlot (default Integer.MAX_VALUE) and acceptNonStackables. A Builder collects modifiers: the structure sets the base depth, and each installed upgrade applies its own (multiplyDepth, multiplyNonStackable, addNonStackableFactor). The profile knows nothing about upgrade types, so new upgrades, including third-party ones, need no changes here. The D-2 rules (stackables depth * maxStackSize, non-stackables 2^bundling * (1 + depthUpgrades)) are tested by expressing Depth and Bundling as those modifiers. All math saturates instead of overflowing.
• ChestStorage:
  • Insert and extract, both per slot and by type. Inserting by type fills matching slots first, then free unlocked slots.
  • Locks: lockTo, lockAllFilled, clearLocks.
  • Extract-only is derived (count > capacity), never stored. That makes "re-formed smaller" and "config lowered" one code path, and loading can never delete items.
  • validateSlotCount / validateProfile return a ResizeResult listing the offending slots. setSlotCount / setProfile only change anything when that result is ok. forceProfile always applies and returns the slots that became extract-only.
  • Dirty-slot tracking (drainDirtySlots, markAllDirty) and change listeners (slot index, or -1 for layout or capacity changes).
  • getState(): a counter that changes on every mutation. This backs the CommonCapabilities IInventoryState capability you asked for; Phase 2 exposes it.
  • Sparse codec: only filled or reserved slots are written. Loading grows the slot count rather than dropping entries that lie beyond it. A slot that can't be decoded (for example, its item's mod was removed) is skipped instead of failing the whole storage, and an unknown compression form item loads as the default form.
• CompressionFamily / CompressionFamilies: ordered forms with base units, conversion math (toBaseUnits, fromBaseUnits, remainderBaseUnits, convert) and lookup by item. Stacks with components never compress. There's no tag loading yet; tests use a hardcoded iron family.

Validation

All unit tests are in loader-common/src/test/.../storage (94 tests including Phase 0's). JaCoCo reports 100% line coverage and every method covered for the storage package.

Plan test	Covered by
Insert into empty, matching, full, locked, mismatched	TestChestStorage.testInsertInto*, testInsertPartiallyFits, testInsertDistinctComponentsAreDistinctTypes
Extract partial, full, more than present, from extract-only	TestChestStorage.testExtract*
Non-stackable capacity with and without bundling and depth upgrades	TestCapacityProfile.testCapacityNonStackable, testNonStackableCapacityIgnoresBaseDepth, testNonStackableSaturates, TestChestStorage.testNonStackableCapacityWithUpgrades
Sparse round trip with a slot at Integer.MAX_VALUE and one above it in extract-only mode	TestChestStorage.testSerializationRoundTrip (NBT), testSerializationJson, testContentsAreSparse, testLoadContentsNeverDropsEntries, testUndecodableEntrySkipped, testUnknownCompressionFormLoadsAsDefault
Resize validation, both directions	testValidateSlotCount, testSetSlotCount*, testValidateProfileBothDirections, testSetProfile, testForceProfile
Compression conversion across three forms	TestCompressionFamily.testConversionAcrossThreeForms

./gradlew build and ./gradlew runGameTestServer pass on all three loaders. There are no new game tests or clientdevbridge checks because nothing touches a level or GUI yet.

Design deviations

• Plan says: "Extract-only mode for over-capacity slots." I made it a derived state, not a flag, for the reasons above. The behaviour matches D-3.
• Compressed counts will be stored in base units (the smallest form), because D-6 needs both "1,234 blocks = 11,106 ingots" and mixed nugget/ingot/block inserts. The math is here; the storage integration and the D-3 "budget counted in the largest form" rule land in Phase 6.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RSz5r6eowhjNuANBjZE2v6

---

Generated by Claude Code

---

Generated by Claude Code