Cursor rule

1# Compostables Mod Specific Context
2 
3## Mod Overview
4The Compostables mod extends Minecraft's composting functionality by making 107 organic items compostable that aren't in vanilla. This includes rotten flesh, spider eyes, eggs, meat, fish, soil blocks, chorus fruits, leather, leather armor, and paper.
5 
6## Project Structure
7- `src/main/java/org/survivorsunited/mods/compostables/` - Main mod code
8- `docs/` - Docusaurus documentation website 
9- `scripts/` - PowerShell build and deployment scripts
10- `gradle.properties` - Centralized mod configuration
11 
12## Current Implementation
13 
14### Main Features
15- 107 new compostable items with balanced chances (30% to 100%)
16- Farmer villagers can collect and compost portable items
17- Server-side only (no client mod required)
18- Uses vanilla composter block
19 
20### Compostable Items by Chance
21- **30%**: Dead Bush, Dirt Path, Grass Block, Rooted Dirt, Muddy Mangrove Roots, Turtle Egg, Sniffer Egg, Sculk Vein
22- **35%**: Bamboo
23- **50%**: Podzol, Chorus Fruit, Chorus Plant, Rabbit's Foot
24- **65%**: Spider Eye, Mycelium, Nylium Blocks, Popped Chorus Fruit, Egg, Raw Meat/Fish (all types), String
25- **85%**: Poisonous Potato, Chorus Flower
26- **100%**: All meat (raw and cooked), all fish (raw and cooked), all stews, all dyes, all carpets, all wool blocks, all leather items (leather, leather armor pieces, leather horse armor), paper, bone items, bamboo block, rotten flesh, fermented spider eye
27 
28### Technical Implementation
291. **Item Registration**: Uses `ComposterBlock.ITEM_TO_LEVEL_INCREASE_CHANCE` map
302. **Villager Behavior**: Mixin modifies farmer profession to include new gatherable items
313. **No new blocks/items**: Only extends existing composting system
32 
33## Project-Specific Details
34 
35### Namespace
36- Mod ID: `su-compostables`
37- Java package: `org.survivorsunited.mods.compostables`
38- Main class: `Compostables`
39- Mixin package: `org.survivorsunited.mods.compostables.mixin`
40 
41### Key Classes
42- `Compostables.java`: Registers all 107 compostable items
43- `FarmerMixin.java`: Makes farmers collect portable compostable items
44 
45## Development Guidelines
46 
47### Java Code Standards
48- Follow existing code style and patterns
49- Use proper Minecraft item names (e.g., "Block of Bamboo" not "Bamboo Block")
50- All composting chances should match the values in Compostables.java:
51  - 30% = 0.3f, 50% = 0.5f, 65% = 0.65f, 85% = 0.85f, 100% = 1.0f
52- Register items using `ComposterBlock.ITEM_TO_LEVEL_INCREASE_CHANCE.put()`
53- Always log the total count of registered items
54 
55### Important Item Names
56- "Block of Bamboo" (not "Bamboo Block")
57- All carpet items: "Color Carpet" (e.g., "White Carpet")
58- All wool items: "Color Wool" (e.g., "White Wool") 
59- All dye items: "Color Dye" (e.g., "White Dye")
60 
61### Documentation Updates
62When updating mod items, ensure consistency across:
63- `Compostables.java` (source of truth for percentages)
64- `docs/docs/intro.md` (main documentation)
65- `docs/docs/modrinth.md` (Modrinth project description)
66- `README.md` (if needed)
67 
68### Current Version
69- Mod version: 1.0.40
70- Minecraft: 1.21.1+
71- Fabric Loader: 0.16.11+
72 
73### Repository Secrets Required
74- `MODRINTH_TOKEN`: API token from Modrinth account
75- `PROJECT_ID`: Modrinth project ID (get after creating project)
76 
77## Development Notes
78- Golden items (golden carrot, golden apple) excluded as they're valuable consumables
79- Soil blocks can't be picked up by villagers but players can compost them
80- Balanced around vanilla composting rates
81- No configuration file - all values hardcoded for consistency
82- Processed organic materials (paper, leather) are 100% compost chance
83- Leather items include: raw leather, leather helmet, chestplate, leggings, boots, and leather horse armor
84 
85### Mixin Development Guidelines
86When working with mixins in this project:
871. **Always check runtime logs first** - The test server log at `test-server/logs/latest.log` provides exact method signatures
882. **Use constructor injection for VillagerProfession** - More stable than static initializer interception
893. **Watch for API changes** - Minecraft 1.21.5 changed many core APIs
90 
91### Common Issues and Solutions
92 
93#### VillagerProfession Mixin Failures
94- **Symptom**: Compilation errors about type mismatches
95- **Solution**: Check the runtime error in server logs for exact JVM descriptors
96- **Example**: In 1.21.5, VillagerProfession constructor uses `Text` not `String`
97 
98#### Build Issues
99- **Java Version**: Requires Java 21
100- **Build Command**: `./gradlew build` or use `.\build.ps1` on Windows
101- **Test Server**: Built mod is auto-copied to `test-server/mods/`
102 
103### Important File Locations
104- Mixins: `src/main/java/org/survivorsunited/mods/compostables/mixin/`
105- Mixin config: `src/main/resources/compostables.mixins.json`
106- Test server logs: `test-server/logs/latest.log`
107- Technical docs: `docs/technical.md`
108 
109### FarmerMixin Implementation Details
110- Injects into VillagerProfession constructor
111- Adds portable compostable items to farmer's gatherable items
112- Uses Text.getString() to identify farmer profession
113- Compatible with Minecraft 1.21.5 API changes
114 
115## Detailed Mixin Troubleshooting Guide
116 
117### VillagerProfession Mixin Issues (Minecraft 1.21.5)
118 
119#### Problem Description
120When upgrading to Minecraft 1.21.5, the VillagerProfession mixin failed with compilation errors indicating incompatible types. The error showed that `String` could not be converted to `Registry<VillagerProfession>`.
121 
122#### Root Cause
123Minecraft 1.21.5 significantly changed the VillagerProfession API:
124- Registration methods now require a `Registry<VillagerProfession>` as the first parameter
125- Constructor signature changed from using String id to Text name
126- Workstation parameters changed to use `Predicate<RegistryEntry<PointOfInterestType>>`
127 
128#### Resolution Process
129 
1301. **Initial Error Analysis**
131   - Compilation error: `String cannot be converted to Registry<VillagerProfession>`
132   - This indicated the method signature had changed
133 
1342. **Key Debugging Steps**
135   - Check the actual runtime error in `test-server/logs/latest.log`
136   - The runtime error provides the EXACT expected method signature
137   - Example error message:
138```
139     Expected (Lnet/minecraft/class_2561;Ljava/util/function/Predicate;Ljava/util/function/Predicate;Lcom/google/common/collect/ImmutableSet;Lcom/google/common/collect/ImmutableSet;Lnet/minecraft/class_3414;Lorg/spongepowered/asm/mixin/injection/callback/CallbackInfo;)V
140```
141 
1423. **Decoding the JVM Descriptors**
143   - `Lnet/minecraft/class_2561;` = Text (not String)
144   - `Ljava/util/function/Predicate;` = Predicate type
145   - `Lnet/minecraft/class_3414;` = SoundEvent
146 
1474. **Final Solution**
148   Instead of trying to intercept static registration, inject into the constructor:
149```java
150   @Inject(method = "<init>", at = @At("RETURN"))
151   private void modifyFarmerGatherables(Text name, Predicate<RegistryEntry<PointOfInterestType>> heldWorkstation, 
152                                       Predicate<RegistryEntry<PointOfInterestType>> acquirableWorkstation, 
153                                       ImmutableSet<Item> gatherableItems, ImmutableSet<Block> secondaryJobSites, 
154                                       SoundEvent workSound, CallbackInfo ci)
155```
156 
157#### Key Learnings
158 
1591. **Always check runtime logs** - The test server log provides exact method signatures expected by the mixin system
1602. **Constructor injection is more stable** - Injecting into constructors is often more reliable than trying to intercept static initializers
1613. **JVM descriptors tell the truth** - The error messages show the exact types needed in JVM format
1624. **API changes between versions** - Major Minecraft updates often change fundamental APIs
163 
164### Quick Reference: Common Mixin Descriptor Mappings
165 
166| JVM Descriptor | Java Type |
167|----------------|-----------|
168| `Lnet/minecraft/class_2561;` | `Text` |
169| `Lnet/minecraft/class_3414;` | `SoundEvent` |
170| `Lnet/minecraft/class_3852;` | `VillagerProfession` |
171| `Ljava/util/function/Predicate;` | `Predicate<?>` |
172| `Lcom/google/common/collect/ImmutableSet;` | `ImmutableSet<?>` |
173 
174### Debugging Workflow
175 
1761. **Build fails** → Check compilation error for type mismatches
1772. **Runtime fails** → Check `test-server/logs/latest.log` for exact signatures
1783. **Decode descriptors** → Map JVM types to Java types
1794. **Update mixin** → Use exact types from error message
1805. **Test** → Run server to verify mixin applies correctly