Cursor rule

1# Development Workflow
2 
3## Local Development Setup
41. **Java Environment**: Install JDK 21 (required for Minecraft 1.21.x)
52. **Build Scripts**: 
6   - Windows: Use `build.ps1` with correct JDK path
7   - Linux/Mac: Use `build.sh` with correct JDK path
83. **IDE**: Any Java IDE with Gradle support (IntelliJ IDEA recommended)
9 
10## Development Process
111. **Code Changes**: Modify Java files in `src/main/java/`
122. **Recipe Changes**: Update JSON files in `src/main/resources/data/{modid}/recipes/`
133. **Assets**: Add textures, models, and sounds to `src/main/resources/assets/{modid}/`
144. **Localization**: Update language files in `src/main/resources/assets/{modid}/lang/`
155. **Documentation**: Update Markdown files in `docs/docs/`
16 
17## Testing Workflow
18### Standard Testing Process
191. **Build Project**: 
20   - Windows: `./build.ps1`
21   - Linux/Mac: `./build.sh`
22   - Direct: `./gradlew build`
232. **Client Testing**: `./gradlew runClient` - Test in single-player
243. **Server Testing**: `./gradlew runServer` - Test multiplayer compatibility
254. **Documentation**: `cd docs && npm start` - Preview documentation locally
265. **Unit Tests**: `./gradlew test` - Run automated tests (if configured)
27 
28### Project-Specific Testing Workflow
291. Build: `.\build.ps1`
302. Start test server: `.\build.ps1 -StartServer`
313. Check logs: `test-server/logs/latest.log`
324. Fix issues based on runtime errors
335. Rebuild and test again
34 
35## Build and Deployment
36 
37### Build System
38- Use Gradle with Fabric toolchain
39- Configuration centralized in `gradle.properties`
40- PowerShell scripts in `/scripts/` directory for automation
41- Always test builds before deployment
42 
43### PowerShell Scripts
44- `build.ps1` - Main build script with optional server start
45- `scripts/start-server.ps1` - Advanced server management
46- `scripts/update-modrinth.ps1` - Update Modrinth project description
47- `scripts/generate-web-icons.ps1` - Generate documentation icons
48- `release.ps1` - Automated release script (updates version, creates tag)
49 
50### Release Process
511. Update version in `gradle.properties`
522. Update documentation with new features
533. Build and test thoroughly: `.\build.ps1`
544. Run release script: `.\release.ps1 -Version "X.Y.Z"`
555. GitHub Actions handles automated publishing to Modrinth and GitHub Releases
56 
57### Environment Variables
58- `MODRINTH_TOKEN` - For Modrinth API access
59- `PROJECT_ID` - Modrinth project identifier
60- Set in GitHub repository secrets for CI/CD
61 
62### File Patterns to Ignore
63- `/build/` - Gradle build output
64- `/run/` - Development server files
65- `/test-server/` - Test server instance
66- `node_modules/` - NPM dependencies
67- `.gradle/` - Gradle cache
68 
69### Debugging Commands
70```bash
71# Check for compilation errors
72./gradlew compileJava
73 
74# Run with more details
75./gradlew build --stacktrace
76 
77# Clean build
78./gradlew clean build
79```
80 
81## Version Management
821. Update `mod_version` in `gradle.properties`
832. Update changelog/release notes
843. Commit changes: `git commit -m "Bump version to X.Y.Z"`
854. Create Git tag: `git tag X.Y.Z`
865. Push changes and tag: `git push origin main && git push origin X.Y.Z`
87 
88## Key Commands
89```bash
90# Setup
91./gradlew clean         # Clean build artifacts
92 
93# Development
94./gradlew build         # Build mod JAR
95./gradlew runClient     # Test in Minecraft client
96./gradlew runServer     # Test on Minecraft server
97./gradlew test          # Run tests
98 
99# Documentation
100cd docs
101npm install             # Install dependencies (first time)
102npm start               # Local preview
103npm run build           # Build for production
104 
105# Release
106git tag X.Y.Z           # Create version tag
107git push origin X.Y.Z   # Push tag (triggers release)
108```
109 
110## File Organization
111- **Source Code**: `src/main/java/{package}/` - Java classes
112- **Resources**: `src/main/resources/`
113  - `fabric.mod.json` - Mod metadata
114  - `data/{modid}/` - Data files (recipes, loot tables, etc.)
115  - `assets/{modid}/` - Client assets (textures, models, lang)
116- **Documentation**: `docs/` - Docusaurus site
117- **Configuration**: Root directory
118  - `build.gradle` - Build configuration
119  - `gradle.properties` - Project properties
120  - `settings.gradle` - Gradle settings
121 
122## Best Practices
123- **Version Control**: 
124  - Use descriptive commit messages
125  - Create feature branches for major changes
126  - Keep commits atomic and focused
127- **Testing**:
128  - Test all features in both client and server
129  - Verify recipes work as intended
130  - Check for mod compatibility issues
131- **Code Quality**:
132  - Follow Java coding standards
133  - Keep mod logic simple and maintainable
134  - Document complex functionality
135- **Performance**:
136  - Profile performance impact
137  - Optimize resource usage
138  - Minimize startup time
139description:
140globs:
141alwaysApply: false
142---
143