Backport: archaeology-tweaks — remove a dead local, add docs (26.1.2)

CLAUDE.md

@@ -107,9 +107,14 @@ for the edit→build loop in this repo.
 Generated output lives in `<mod>/common/src/main/generated/` and is committed; **regenerate, never
 hand-edit**.
 
-> On MC 26.2, datagen additionally needs item data components bound at the top of `buildRecipes()`
-> (`BuiltInRegistries.DATA_COMPONENT_INITIALIZERS`). **That is not needed on 26.1.2** and the API does
-> not exist here — components are bound at construction. Restore it if you forward-port.
+> ⚠ Datagen needs item data components bound at the top of `buildRecipes()`, because components are
+> data-driven and datagen never performs the server reload that binds them:
+> ```java
+> BuiltInRegistries.DATA_COMPONENT_INITIALIZERS.build(registryLookup).forEach(pending -> pending.apply());
+> ```
+> Without it, anything reading components at datagen time (e.g. `Item.getDefaultMaxStackSize()`) throws
+> `NullPointerException: Components not bound yet`. Same on 26.1.2 and 26.2 — see `docs/TESTING.md`
+> for the unit-test equivalent.
 
 ## Scaffolding
 

archaeology-tweaks/POTENTIAL_FEATURES.md

@@ -0,0 +1,53 @@
+# Potential Features — Archaeology Tweaks
+
+Brainstormed, thematically appropriate feature ideas. Nothing here is committed or implemented; these are
+starting points for future planning.
+
+## More suspicious blocks
+
+* **Suspicious Snow / Suspicious Powder Snow** — frozen digs in icy biomes; melts (losing its loot) if the
+  biome warms or fire is nearby, making excavation time-sensitive.
+* **Suspicious Moss** — jungle and lush-cave digs; brushing occasionally yields living things (seeds,
+  saplings, glow berries) alongside artifacts.
+* **Suspicious Mycelium / Suspicious Podzol** — mushroom-island and old-growth forest digs.
+* **Suspicious Netherrack / Suspicious End Stone** — extend archaeology to the other two dimensions, with
+  dimension-appropriate loot tables (ancient debris scraps, chorus relics).
+* **Suspicious Ash / Basalt Sand** (custom block) — volcanic dig sites near basalt deltas.
+
+## Brush improvements
+
+* **Copper, Gold, Diamond, and Netherite Brushes** — a tier ladder mirroring tools: higher tiers brush
+  faster and/or have more durability. Gold could trade durability for a luck bonus.
+* **"Keen Eye" enchantment** — suspicious blocks within a few chunks shimmer faintly while a brush with
+  this enchantment is held, solving the "they're invisible in terrain" discoverability problem.
+* **"Careful Hands" enchantment** — a chance to pull a *second* roll from the loot table on completion.
+* **Brush handle customization** — combine a brush with dye or a banner pattern purely for looks.
+
+## Dig sites & world generation
+
+* **Buried dig sites** — small worldgen features that cluster 5–15 suspicious blocks around a skeleton,
+  fossil, or ruined foundation, so players can find a "site" rather than lone blocks.
+* **Fossil excavations** — vanilla fossils generate partially encased in suspicious blocks; fully brushing
+  the site yields bonus bone blocks and rare sherds.
+* **Torn map fragments** — a loot item that, when several are combined, points to a nearby dig site
+  (treasure-map style).
+
+## Loot & progression
+
+* **Depth-tiered loot** — optional rule where suspicious blocks below a configurable Y level roll a rarer
+  loot table; deeper digs, better finds.
+* **New pottery sherds** — a set of sherd designs matching the new materials (a mushroom sherd from
+  mycelium, a soul-flame sherd from soul sand, etc.), usable on vanilla decorated pots.
+* **Field Journal item** — records every unique artifact you've brushed up; doubles as a collection
+  checklist with advancement hooks.
+* **Advancements** — "First Dig," "Gentle Touch" (complete a dig without breaking the block), "Museum
+  Quality" (collect every sherd), "Interdimensional Archaeology."
+
+## Integration & configurability
+
+* **Datapack-defined suspicious variants** — a data-driven registry so datapacks can declare *any*
+  full block as brushable with a chosen loot table, rather than being limited to the mod's built-ins.
+* **Archaeologist wandering trades** — wandering traders occasionally sell brushes and single suspicious
+  blocks, giving survival players a renewable (if pricey) way to seed their own dig sites.
+* **Config: brushing speed & loot rolls** — global multipliers so pack makers can make archaeology
+  faster/slower or more/less generous.

archaeology-tweaks/README.md

@@ -0,0 +1,52 @@
+# Archaeology Tweaks (Fabric/NeoForge)
+
+![Version: 4.0.0-alpha.0](https://img.shields.io/badge/version-4.0.0--alpha.0-blueviolet?style=flat-square) ![Modloader: Fabric](https://img.shields.io/badge/modloader-Fabric-1976d2?style=flat-square) ![Modloader: NeoForge](https://img.shields.io/badge/modloader-NeoForge-1976d2?style=flat-square) ![Client: required](https://img.shields.io/badge/client-required-4caf50?style=flat-square) ![Server: required](https://img.shields.io/badge/server-required-4caf50?style=flat-square)
+
+_Small, vanilla-friendly tweaks to Minecraft's archaeology system._
+
+## Introduction
+
+Vanilla archaeology only lets you brush two blocks: suspicious sand and suspicious gravel. Archaeology Tweaks
+extends that idea to a range of additional materials, so digs can be seeded across far more of the world without
+feeling out of place. Every block behaves like its vanilla counterpart — brush it with a brush to slowly reveal
+whatever loot has been assigned to it.
+
+### Minecraft Versions
+
+* 26.1.2: supported
+* Earlier versions: see the git history for builds targeting older releases
+
+### Current Features
+
+* Adds "suspicious" brushable variants of common terrain blocks:
+  * Suspicious Clay
+  * Suspicious Dirt
+  * Suspicious Mud
+  * Suspicious Packed Mud
+  * Suspicious Red Sand
+  * Suspicious Rooted Dirt
+  * Suspicious Soul Sand
+  * Suspicious Soul Soil
+* Each block is brushed exactly like vanilla suspicious sand/gravel, revealing its loot piece by piece
+* Includes gravity-affected variants that behave like the block they are based on (e.g. sand and red sand fall)
+* Loot is driven by loot tables, making it easy for datapacks to customize what each block can contain
+
+## Notes for Documentation
+
+This mod's blocks are intended to be placed by world generation, structures, or datapacks rather than crafted.
+When writing in-game or datapack documentation, the key player-facing behavior is simply: _find a suspicious
+block, equip a brush, and hold right-click to excavate it._
+
+## Issues & Suggestions
+
+Please use the [GitHub issue tracker](https://github.com/chimericdream/archaeology-tweaks/issues) to report any
+bugs you find.
+
+## Credits
+
+Obviously this mod would not be possible if not for the people at Mojang making an awesome game. Thanks also go to
+the developers of the Fabric and NeoForge mod loaders and the Architectury API.
+
+## License
+
+This mod is released under the MIT license. [The full text of the license can be found here.](./LICENSE)

archaeology-tweaks/TEST_PLAN.md

@@ -0,0 +1,106 @@
+# Test Plan — Archaeology Tweaks
+
+Archaeology Tweaks adds eight "suspicious" brushable terrain variants (clay, dirt, mud, packed mud,
+red sand, rooted dirt, soul sand, soul soil), each behaving like vanilla suspicious sand/gravel:
+brush to reveal loot-table-driven loot piece by piece. Key classes: per-material block classes,
+`ATBrushableBlockEntity`, `BrushableFloatingBlock`/`BrushableFloatingNonFullBlock` (gravity
+variants), the `BrushItemMixin`/`AbstractBlockMixin` hooks, and a client-side renderer for the
+partially-brushed states.
+
+## Test conventions
+
+Follow the Hopper X-Treme pattern: GameTest classes in
+`fabric/src/main/java/com/chimericdream/archtweaks/fabric/test/` (match the mod's actual package,
+`com.chimericdream.archtweaks`... verify against `ArchaeologyTweaksMod`'s package before creating),
+registered under the `fabric-gametest` entrypoint in `fabric.mod.json`, `.snbt` structures under
+`common/src/main/resources/data/archtweaks/gametest/structure/`. Brushing is player-driven, so most
+GameTests will use a mock player + programmatic brush usage, or directly drive the block entity's
+brushing methods where the mixin allows.
+
+## Manual test plan
+
+Setup: creative world; `/give` each suspicious block and a brush. Fabric full pass, NeoForge smoke
+pass.
+
+1. **Brushing happy path (per block)** — for each of the 8 blocks: place, hold right-click with a
+   brush, verify (a) progressive "dusting" animation and texture stages render, (b) loot item pops
+   out after the vanilla-length brush time, (c) block converts to its base terrain block (clay →
+   clay, soul sand → soul sand, etc.) when fully brushed.
+2. **Brush interruption** — stop brushing mid-way: block should regress to unbrushed after a moment
+   (vanilla behavior), with no dropped loot.
+3. **Gravity variants** — suspicious red sand (and any other gravity blocks): break the supporting
+   block; it should fall like sand, and — mirroring vanilla — the falling version should degrade to
+   plain red sand (or whatever behavior is intended; pin it). Non-full gravity blocks
+   (`BrushableFloatingNonFullBlock`) need the same check.
+4. **Soul sand specifics** — suspicious soul sand: confirm whether it slows entities like real soul
+   sand (block behavior parity) and works under water.
+5. **Loot customization** — override one block's loot table with a datapack; verify the brushed loot
+   changes accordingly (this is an advertised feature).
+6. **Non-brush interactions** — mining with a shovel drops nothing special (or per loot table);
+   pistons: vanilla suspicious blocks are destroyed when pushed — verify parity.
+7. **Brush durability & enchantments** — brushing consumes durability; Unbreaking/Mending behave.
+8. **Client rendering** — `ATBrushableBlockEntityRenderer`: the partially-revealed item renders
+   inside the block at the correct dusting stages; check on Fabric and NeoForge (renderer
+   registration is per-loader).
+
+## Recommended automated tests
+
+### GameTests — brushing behavior
+
+Structure `archtweaks:brushing/single_block` (a 3×3 platform with one suspicious block).
+
+* **`brushingRevealsLootAndConverts_<block>`** (parameterized across all 8 blocks, like
+  Hopper X-Treme's per-tier tests): set the block, seed its `ATBrushableBlockEntity` with a known
+  item (the BE should expose the vanilla `item` field — set directly rather than relying on the loot
+  roll), then simulate brushing. Options for driving the brush, in order of preference:
+  1. call the block entity's brush-progress method directly across ticks (deterministic);
+  2. mock player + `player.gameMode().useItemOn(...)` repeatedly with a brush.
+  Assert: an item entity of the seeded item appears (`assertItemEntityCountIs`), and the block
+  becomes the base terrain block.
+* **`brushingInterruptedResets`** — advance brushing partway, stop, wait ~40 ticks, assert dusted
+  state property returns to 0 and no loot dropped.
+* **`lootTableRolledOncePerBlock`** — brush the same block fully; assert exactly one loot drop (no
+  duplication when the conversion and the drop race — a classic bug source).
+
+### GameTests — gravity variants
+
+* **`suspiciousRedSandFalls`** — block on a support over a 3-deep hole; remove support; after
+  10 ticks assert the landing position holds the expected block and the original position is air.
+  Also assert what lands: suspicious block vs plain red sand (pin intended behavior).
+* **`fallingOntoTorchBreaksToItem`** — vanilla falling-block edge: assert the drop matches the loot
+  table.
+* **`nonFullFloatingVariantSurvives`** — whatever `BrushableFloatingNonFullBlock` exists for (verify
+  in code), place unsupported and assert intended float/fall behavior.
+
+### GameTests — loot data
+
+* **`allBlocksHaveBrushingLootTables`** — iterate `ModBlocks`; assert each block's brushing loot
+  table ID resolves in the server's reloadable registries (catches typos and missing datagen
+  output).
+* **`datapackOverrideRespected`** — ship a test-only datapack (in the fabric test source set's
+  resources) overriding one block's table to a single known item; brush and assert that item drops.
+
+### Unit tests
+
+* None of substance — the logic is engine-coupled. Keep the effort in GameTests.
+
+## ChimericLib helper opportunities
+
+* **Brushing simulation helper** — "advance brushable BE at pos by N brush strokes" +
+  `assertDustedLevel(pos, n)`. Only this mod needs it today, but a "tag-first brushable" ChimericLib
+  feature is already floated in its POTENTIAL_FEATURES; the helper belongs beside it.
+* **Loot-table resolution assertion** — `assertLootTableExists(server, id)` and
+  `rollLootTable(server, id, seed, n)` for datapack-driven mods (shared with Athenaeum, Miniblock
+  Merchants).
+* **Mock-player item-use loop** — "use item X on pos Y for N ticks" wraps the fiddly
+  `useItemOn`/`releaseUsing` dance; reused by Artificial Heart (axe/shears), Villager Tweaks
+  (bundle on villager), and Minekea (wrench).
+* **Falling-block assertions** — `assertBlockFellTo(helper, from, to, expectedBlock)`; shared with
+  Houdini Block's sand tests.
+
+## Open questions
+
+* Intended behavior when a suspicious gravity block falls: stay suspicious (keep loot) or degrade to
+  the plain block (vanilla suspicious sand degrades)? Tests must pin one.
+* Do pistons/explosions destroy the loot (vanilla: yes)? Worth an explicit decision + regression
+  test either way.

archaeology-tweaks/common/src/main/java/com/chimericdream/archaeologytweaks/block/entity/ATBrushableBlockEntity.java

@@ -156,7 +156,6 @@ public void scheduledTick(ServerLevel world) {
                 world.setBlock(this.getBlockPos(), this.getBlockState().setValue(BlockStateProperties.DUSTED, j), 3);
             }
 
-            int k = 4;
             this.nextDustTime = world.getGameTime() + 4L;
         }