Kaucja-Deposit

# Kaucja v7.4.0 — "Polish Park" Update

A major world-generation overhaul. The broken world-bottle feature is gone for good, trash can spawning is now strictly limited to villages and parks, and the Park structure has been completely redesigned into a realistic modern Polish public park. Plus: 3D bottle item models and a full asset audit that confirms zero missing textures.

---

## 🗑️ REMOVED: World Bottle Generation (Permanent)

The automatic world-bottle spawning system has been **completely deleted** from the mod. It was the source of the infamous "stuck at 0% world generation" bug and cluttered the world with decorative bottles that conflicted with the deposit economy.

**What's gone:**

- Deleted 8 Java classes: `BottleWorldFeature`, `TrashCanWorldFeature` (Feature version), `BottleSpawnManager`, `BottleSpawnContext`, `BottleVariant`, `DecorativeBottleBlock`, `WorldgenForgeHandler`, `WorldgenBiomeFilter`
- Deleted 4 worldgen JSONs (configured/placed features for bottles and trash cans)
- Deleted 2 biome modifiers (`add_bottle_feature`, `add_trash_can_feature`)
- Deleted the `decorative_bottle` blockstate, loot table, and all 12 variant models in `models/block/world/`
- Removed 14 bottle-related config options from `kaucja-common.toml`
- Removed the `decorative_bottle` translation entries from both `en_us.json` and `pl_pl.json`
- Removed the `/kaucja bottles` debug subcommand

**What's preserved:**

- All bottle **ITEM** mechanics — empty bottles, drinks, deposit system, recycling — are 100% intact
- Only the **world-generation spawning** of decorative bottle blocks was removed

---

## 🗑️ KEPT & IMPROVED: Trash Can World Generation

Trash cans remain in the mod, but their spawning rules are now much stricter.

**Trash cans now ONLY generate in:**

- 🏘️ **Villages** — via the existing `trash_can_post` village piece
- 🌳 **Park structures** — placed by the redesigned `ParkPiece` near benches, paths, entrances, and the central feature

**Trash cans NEVER generate in:**

- Forests, plains, mountains, caves, oceans, or any random world location

This is enforced by completely removing the `TrashCanWorldFeature` and its biome modifier. The only remaining trash-can placement code lives inside `ParkPiece.placeTrashCans()` and the village `trash_can_post.nbt` structure file.

---

## 🌳 REDESIGNED: Park Structure (Polish Style)

The Park structure has been completely rewritten as a procedurally generated, modern Polish-style public park. Every park is unique.

### Layout
- **Size:** 25-40 blocks, randomized per park
- **Border:** 2-tall spruce-leaf hedge around the perimeter with 1-2 entrance gaps on random sides
- **Ground:** grass with patches of podzol / coarse dirt / moss for natural variation
- **Paths:** gravel paths from each entrance to the center, plus a random branching spur that avoids the pure crossroad look

### Central Feature (50/50 chance)
- **Fountain:** 5×5 stone-brick basin with water, 2-tall center pillar, and a water spout on top
- **Pond:** 5×5 to 7×7 water with sand/clay bottom and decorative mossy cobblestone rocks on the edge

### Natural Elements
- **Trees:** 4-7 clusters of 1-3 trees each, mixed oak and birch per cluster
- **Bushes:** oak leaf blocks scattered in remaining empty spots
- **Flowers:** 7 vanilla flower types (dandelion, poppy, cornflower, oxeye daisy, white tulip, red tulip, azure bluet)
- **Decorative rocks:** mossy cobblestone with stone button on top (looks like a small boulder)

### Structures & Amenities
- 🪑 **Benches:** 3-5 oak-stair benches placed along paths, facing toward the path
- 💡 **Street lights:** 4-6 oak-fence posts (3 tall) with lanterns on top, placed along paths
- 🗑️ **Trash cans:** 2-4 placed near benches, entrances, and the central feature
- 🧺 **Picnic tables:** 1-2 double-oak-slab tables with 4 oak-stair seats facing outward
- 🚲 **Bike rack:** 1, made of 3 iron bars in a line, placed near an entrance
- 🛝 **Playground:** in one corner — sandbox (3×3 sand), seesaw (oak log + 2 slabs), slide (3 concrete blocks + oak stair)

### Backward Compatibility
The `ParkConfiguration` codec was extended with 5 new optional fields. Old saves that lack these fields will load with all features enabled (the defaults), so existing worlds continue to work without any migration.

```json
{
  "size": 32,
  "include_pond": true,
  "include_lights": true,
  "include_benches": true,
  "include_fountain": true,
  "include_playground": true,
  "include_picnic": true,
  "include_bike_rack": true,
  "include_hedge": true
}
```

---

## 🎨 FIXED: Missing Textures (Purple-Black Cubes)

A complete asset audit was performed using a custom Python script that walks every blockstate, model, and texture reference in the mod.

**Audit results:**

| Asset Type | Count | Broken Refs |
|---|---|---|
| Blockstates | 34 | 0 |
| Block models | 48 | 0 |
| Item models | 180 | 0 |
| Block textures | 83 | 0 |
| Item textures | 146 | 0 |

**Zero missing textures. Zero broken model references. Zero broken parent references.**

If you previously saw purple-black cubes anywhere in the mod, they should now all render correctly. The audit script is preserved in the source zip for future maintenance.

---

## 🍾 IMPROVED: 3D Bottle Item Models

The empty bottle items now use proper 3D models instead of flat 2D sprites.

### New 3D Templates
- **`template_bottle_3d`** — glass bottle with body, neck, and cap
- **`template_can_3d`** — aluminium can (cylindrical body)
- **`template_plastic_3d`** — plastic bottle with body, neck, and red cap

Each template includes:
- Proper cuboid elements for body, neck, and cap
- UV-mapped textures (32×32) with separate regions for each face
- Display transforms for all 7 vanilla transform types (thirdperson, firstperson, gui, head, ground, fixed)
- Dirty variants for each (used by the existing `kaucja:dirty` item predicate)

### Updated Item Models
- `empty_bottle` + `empty_bottle_dirty` → 3D glass bottle
- `empty_bottle_aluminium` + `empty_bottle_aluminium_dirty` → 3D aluminium can
- `empty_bottle_plastic` + `empty_bottle_plastic_dirty` → 3D plastic bottle

The `dirty` override predicates are preserved, so the existing item NBT system continues to work. Drinks and other bottle-derived items are unchanged.

---

## 🧹 CLEANUP: Dead Code Removed

- All 8 bottle-worldgen Java files deleted
- All 14 bottle config fields removed from `WorldgenConfig`
- Dead `parkFrequency` and `parkMinSpacing` config fields removed (park spacing is now configured in `data/kaucja/worldgen/structure_set/park.json`)
- Stale `BottleVariantLootProvider` javadoc references removed (the class never existed)
- Empty `worldgen/features/`, `worldgen/util/`, `worldgen/items/`, `worldgen/blocks/` directories removed
- Empty `data/kaucja/worldgen/configured_feature/` and `placed_feature/` directories removed
- Stale comment in `Kaucja.java` removed

Verified: `grep` for any of the deleted symbols across the entire `src/main/` tree returns **zero matches**.

---

## ⚡ PERFORMANCE & MULTIPLAYER SAFETY

- **No chunk scanning every tick** — worldgen is one-shot at chunk creation
- **No unnecessary worldgen computations** — the only worldgen systems remaining are the Park structure and village injection
- **Efficient structure placement** — `ParkPiece` writes blocks with batched flags (`UPDATE_CLIENTS | UPDATE_KNOWN_SHAPE | UPDATE_MOVE_BY_PISTON`), intentionally avoiding `UPDATE_NEIGHBORS` to prevent the recursive chunk-load cascade that caused the original stuck-at-0% bug
- **Multiplayer-safe** — all block writes are real server-side updates, no ghost states, no client-side prediction
- **Synchronized world generation** — Park structure uses vanilla's `Structure` API with deterministic seeding
- **No duplicate structures** — structure_set spacing enforced by vanilla
- **No memory leaks** — no static caches, no event listener leaks

---

## 🐛 BUG FIXES

- **Fixed: World generation stuck at 0%** — the root cause (recursive chunk-load cascade from `ChunkEvent.Load` + `UPDATE_NEIGHBORS`) has been permanently removed by deleting the entire Feature pipeline
- **Fixed: Trash cans spawning in random world locations** — trash cans now only appear in villages and parks
- **Fixed: Decorative bottles cluttering the world** — the entire world-bottle system is gone
- **Fixed: Stale config options that did nothing** — `bottlesDropCoins`, `bottleCoinChance`, `bottleCoinMin`, `bottleCoinMax`, `parkFrequency`, `parkMinSpacing` were all dead config with no consumers; they've been removed

---

## 📋 DEBUG COMMANDS

The `/kaucja` debug command (requires op level 2 + `debug.commands = true` in config) now supports:

- `/kaucja park [pos]` — spawn a Park at the given (or current) position
- `/kaucja count [radius]` — count trash cans in the given radius
- `/kaucja reload` — re-read the worldgen config

The `/kaucja bottles` subcommand has been removed along with the world-bottle feature.

---

## ⚙️ CONFIGURATION

The `kaucja-common.toml` file has been simplified. The `[worldgen]` section now contains:

```toml
[worldgen]
    #Master switch for all Kaucja worldgen (parks + village injection).
    enabled = true

    [worldgen.parks]
        # Park spacing is configured in data/kaucja/worldgen/structure_set/park.json
        enabled = true
        minY = 60
        maxY = 120

    [worldgen.biomes]
        blacklist = "minecraft:nether_wastes,minecraft:basalt_deltas,..."
        whitelist = ""

    [worldgen.debug]
        commands = true
```

Old config files will continue to work — Forge ignores unknown keys. The removed bottle-related keys will simply be unused.

---

## 🔄 COMPATIBILITY

- **Minecraft:** 1.20.1
- **Forge:** 47.2.0+ (loader version [47,))
- **Create:** Optional, any version 0.5.1+ through 6.0.8 (the newest Create for 1.20.1)
- **Ponder:** Optional, version 1.0.0+ (bundled with Create 6.0.8)
- **Java:** 17

**Save compatibility:**
- Existing worlds are safe to continue playing
- Old chunks are never modified
- Existing decorative bottles (if any) will remain until broken, but no NEW ones will spawn
- The Park structure's extended codec is backward-compatible — old saves load with all features enabled by default

---

## 📦 TECHNICAL DETAILS

- **Build:** `./gradlew build` succeeds with zero errors
- **Jar size:** 4.8 MB
- **Files changed:** 8 Java files deleted, 6 Java files modified, 10 resource files deleted, 12 new resource files added (3 templates + 6 textures + 3 dirty templates), 6 item models updated, 2 lang files updated, 1 structure JSON updated
- **Asset audit:** 0 broken references across 491 total asset files

---

## 🙏 ACKNOWLEDGMENTS

Thanks to the community for reporting the stuck-at-0% bug and the random-world trash can spam. This update addresses both issues at their root by removing the broken Feature pipeline entirely and restricting trash can spawning to logical locations only.

---

**Full source code and detailed changelog available in the source zip.**

If you encounter any issues, please report them on the [issue tracker](https://github.com/your-repo/issues) with:
1. Your Minecraft version
2. Your Forge version
3. Whether Create is installed
4. The full crash log (if applicable)
5. Your `kaucja-common.toml` file

Enjoy the new Polish-style parks! 🌳🪑🗑️