maj/MobScores
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Addsd modernization plan and tasks for implementation.

Browse Source
This commit is contained in:
Tom Hicks
2025-07-14 05:54:58 -07:00
parent a65b8d2ca1
commit bbc512a044
3 changed files with 406 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

378
.cursor/plans/Modernize.md Normal file
View File

@@ -0,0 +1,378 @@
# Modernize MobScores Minecraft Plugin
This plan outlines the steps to modernize the MobScores plugin, migrating from an old Maven/Bukkit setup to a modern Gradle/PaperMC build, and updating project structure and configuration for best practices.
---
## 1. Analyze Current Codebase
- [ ] Review all Java source files for deprecated or removed Bukkit API usage.
- [ ] Identify any hardcoded Bukkit references or legacy patterns (e.g., using Player as HashMap key, old event registration, etc.).
- [ ] Note any custom scripts or resources that may need migration.
## 2. Migrate Build System: Maven → Gradle
- [ ] Initialize Gradle in the project root (if not already present).
- [ ] Create a `build.gradle` file with:
- Project metadata (group, version, description) from `pom.xml`.
- PaperMC API dependency (latest stable, e.g., 1.19+).
- JUnit (or modern test framework) for tests.
- Java toolchain/source compatibility (Java 17+ recommended for Paper 1.19+).
- PaperMC repository for dependencies.
- Resource handling for `plugin.yml`.
- Shadow plugin or equivalent for fat-jar if needed.
- [ ] Remove Maven-specific files:
- `pom.xml`
- `.mvn/` directory (if present)
- Any Maven wrapper scripts
- [ ] Remove Eclipse-specific files (e.g., `.classpath`, `.project`, `.settings/`) if present.
## 3. Update .gitignore
- [ ] Add Gradle-specific ignores:
- `.gradle/`
- `build/`
- `!gradle/wrapper/`
- `*.iml`, `.idea/` (if using IntelliJ)
- [ ] Remove Maven-specific ignores (e.g., `target/`).
- [ ] Remove Eclipse-specific ignores (e.g., `.classpath`, `.project`, `.settings/`).
## 4. Update plugin.yml
- [ ] Ensure `plugin.yml` is present in `src/main/resources`.
- [ ] Update API version and commands for PaperMC compatibility.
- [ ] Add/verify all required fields (name, main, version, api-version, commands, etc.).
## 5. Refactor Deprecated API Usage
- [ ] Replace all usages of `Player` as a HashMap key with `UUID`.
- [ ] Update logger usage to `getLogger()` from `JavaPlugin`.
- [ ] Update event listeners to use `@EventHandler` and `registerEvents`.
- [ ] Update player lookup logic to use `getPlayerExact` or handle case sensitivity.
- [ ] Review and update any other deprecated or removed Bukkit/Spigot API calls.
## 6. Test on Modern Paper Server
- [ ] Build the plugin with Gradle (`./gradlew build`).
- [ ] Use the provided bash scripts in `tools/bash/` to start/stop a local Paper server for testing.
- [ ] Set `MINECRAFT_SERVER_PATH` and `MINECRAFT_SERVER_JAR` environment variables as needed.
- [ ] Deploy the built plugin and check for errors/warnings.
## 7. Fix Bugs and Incompatibilities
- [ ] Address any issues found during testing on a modern server.
- [ ] Ensure all features work as intended.
## 8. Update Documentation
- [ ] Update `README.md` with new build and usage instructions.
- [ ] Document any new features, changes, or migration notes.
- [ ] Update or create `CONTRIBUTING.md` with setup and development instructions.
## 9. Optional Improvements
- [ ] Consider adding new features or quality-of-life improvements.
- [ ] Add automated tests or CI configuration if desired.
---
### Summary Table
| Step | Description |
|-----------------------------|------------------------------------------------|
| Analyze Codebase | Review for deprecated/legacy code |
| Migrate to Gradle | Init Gradle, migrate metadata/deps, remove Maven|
| Update .gitignore | Add Gradle ignores, remove Maven/Eclipse |
| Update plugin.yml | Ensure modern, complete config |
| Refactor Deprecated APIs | Update code for modern PaperMC |
| Test on Paper | Build, deploy, and test on modern server |
| Fix Bugs | Address issues found during testing |
| Update Docs | Refresh README, CONTRIBUTING, etc. |
| Optional Improvements | Add features, tests, CI, etc. |
---
## Appendix: Gradle vs. Maven
### Maven
**Pros:**
- Stability & Maturity: Very stable, predictable builds.
- Convention over Configuration: Standard structure and lifecycle.
- Dependency Management: Handles dependencies well, large central repository.
- Documentation: Extensive documentation and community support.
- IDE Support: Excellent integration with Java IDEs.
- Widely Used: Many Minecraft plugins and tutorials use Maven.
**Cons:**
- Verbose Configuration: `pom.xml` can become large and hard to read.
- Less Flexible: Custom build logic is harder to implement.
- Slower for Large Projects: Can be slower than Gradle for complex builds.
### Gradle
**Pros:**
- Performance: Generally faster builds, supports incremental builds and caching.
- Flexibility: Build scripts in Groovy/Kotlin allow complex logic.
- Concise Configuration: `build.gradle` files are usually shorter and easier to read.
- Modern Tooling: Better support for modern build features.
- Growing Popularity: Increasingly popular in the Java ecosystem.
**Cons:**
- Learning Curve: More complex for beginners, especially for custom logic.
- Less Convention: More freedom can lead to less consistency.
- Slightly Less Documentation: Not as much Minecraft-specific documentation as Maven.
### Which is Most Common for Minecraft Plugins?
- **Maven** is still the most common for Bukkit, Spigot, and Paper plugins, with most guides and examples using it.
- **Gradle** is gaining popularity, especially for newer projects or those needing more flexibility and speed.
**Summary:**
- For maximum compatibility with community resources, Maven is the safest choice.
- For a modern, flexible, and fast build system, Gradle is a great option if you're comfortable with it.
---
## Appendix: Choosing a Plugin API
### Bukkit
**Description:**
The original plugin API for Minecraft servers, now largely unmaintained. Most modern APIs are built on or forked from Bukkit.
**Pros:**
- Huge legacy plugin library.
- Simple, well-documented API.
- Good for very basic plugins.
**Cons:**
- No longer actively maintained.
- Lacks support for modern Minecraft features.
- Not recommended for new projects.
### Spigot
**Description:**
A high-performance fork of Bukkit, Spigot is the most widely used server software for plugins. It adds performance improvements and bug fixes.
**Pros:**
- Actively maintained and widely used.
- Large plugin ecosystem.
- Good documentation and community support.
- Compatible with most Bukkit plugins.
**Cons:**
- Lags behind the latest Minecraft features compared to Paper.
- Fewer advanced features than Paper.
### Paper
**Description:**
A fork of Spigot with additional performance optimizations, bug fixes, and new API features. Paper is now the de facto standard for modern plugin development.
**Pros:**
- Actively maintained and very popular.
- Superior performance and stability.
- Adds many new API features not in Spigot/Bukkit.
- Backwards compatible with most Spigot/Bukkit plugins.
- Large, active community.
**Cons:**
- Some Paper-specific APIs may not work on Spigot (if you ever want to support both).
- Slightly faster update cycle may require more frequent plugin updates.
### Purpur
**Description:**
A fork of Paper with even more features, configuration options, and experimental changes. Aimed at server owners who want maximum customization.
**Pros:**
- All benefits of Paper, plus more features and config options.
- Great for highly customized servers.
**Cons:**
- Some features are experimental and may be unstable.
- Smaller community than Paper/Spigot.
- Plugins using Purpur-specific features may not work elsewhere.
### Sponge
**Description:**
A completely separate API and server implementation, not based on Bukkit/Spigot/Paper. Aimed at modded servers (Forge) but also works standalone.
**Pros:**
- Designed for both plugins and mods (Forge integration).
- Modern, flexible API.
- Good for modded servers.
**Cons:**
- Much smaller plugin ecosystem for vanilla servers.
- Not compatible with Bukkit/Spigot/Paper plugins.
- Less relevant for standard server-only plugins.
### Summary & Recommendation
- **Paper** is the best choice for most modern server-only plugins: it’s fast, stable, actively maintained, and has the richest API.
- **Spigot** is a safe fallback if you want maximum compatibility, but Paper is almost always preferred now.
- **Purpur** is great for highly customized servers, but not necessary unless you want its extra features.
- **Sponge** is only recommended if you want to support modded servers or need its unique API.
**For your use case (server-only, modern, not needing experimental features):**
**Paper** is the best option. It gives you the most features, best performance, and widest compatibility for new plugin development.
---
## Appendix: Development Setup
### Minecraft Launchers (Java Edition)
**Official Minecraft Launcher**
- Fully supported by Mojang/Microsoft.
- Works on Windows, macOS, and Linux (including WSL with GUI support).
- Easiest for vanilla play and account management.
**Prism Launcher** (formerly PolyMC)
- Open source, cross-platform (Windows, macOS, Linux).
- Great for managing multiple Minecraft instances, modpacks, and versions.
- Works well in Linux environments.
**MultiMC**
- Similar to Prism Launcher, but older and less actively maintained.
- Good for managing multiple instances.
**Recommendation:**
- Use the Official Minecraft Launcher for playing and account management.
- Use Prism Launcher for advanced instance/modpack management, especially on Linux/macOS.
### Server Software for Plugin Development
**Paper**
- Most popular for plugin development.
- Fast, stable, and actively maintained.
- Easy to run in headless/automated environments (Linux containers, CI).
- [Download Paper](https://papermc.io/downloads)
**Spigot**
- Still widely used, but less feature-rich than Paper.
- Requires building with BuildTools ([spigotmc.org/wiki/buildtools](https://www.spigotmc.org/wiki/buildtools/))
**Purpur**
- Fork of Paper with more options.
- [Download Purpur](https://purpurmc.org/downloads)
**Recommendation:**
- Use Paper for your main development and testing server.
- Download the latest Paper jar and run it directly in your Linux environment or containers.
### Automated Testing & Linux Containers
- Paper runs perfectly in headless Linux environments (including WSL, Docker, CI/CD).
- You can script server startup, plugin deployment, and automated plugin tests using bash scripts.
- For CI/CD, use GitHub Actions, GitLab CI, or any Linux-based runner.
### Summary Table
| Use Case | Recommended Launcher | Recommended Server |
|-------------------------|-----------------------------|-------------------|
| Playing Minecraft | Official Launcher / Prism | N/A |
| Plugin Development | N/A | Paper |
| Automated Testing/CI | N/A | Paper |
| Multi-instance/modpacks | Prism Launcher | Paper |
### Next Steps
- Download the Official Minecraft Launcher for playing.
- Download Prism Launcher if you want advanced management.
- Download the latest Paper server jar for plugin development and testing.
#### Server Management Scripts and Environment Variables
- Use the `tools/bash/start-server.sh` and `tools/bash/stop-server.sh` scripts to start and stop your Paper server for development and testing.
- Set the following environment variables in your shell:
- `MINECRAFT_SERVER_PATH`: The root path of your Paper server directory.
- `MINECRAFT_SERVER_JAR`: The path to your Paper server jar (relative to `MINECRAFT_SERVER_PATH` or absolute).
- See `CONTRIBUTING.md` for detailed setup instructions.
---
## Appendix: Migrating from Maven to Gradle
Switching from Maven to Gradle involves several steps to ensure a smooth transition and a working build system for your plugin.
### Migration Steps
- **Initialize Gradle in the Project**
- Use `gradle init` or manually create a `build.gradle` file.
- **Migrate Project Metadata**
- Set `group`, `version`, and `description` in `build.gradle`.
- **Migrate Dependencies**
- Copy dependencies from `pom.xml` to the `dependencies` block in `build.gradle`.
- Add the PaperMC (or Spigot) repository.
- **Configure Java Version**
- Set the Java toolchain or source/target compatibility in `build.gradle`.
- **Migrate Resource Handling**
- Ensure `plugin.yml` and any other resources are in `src/main/resources`.
- **Migrate Build Plugins/Tasks**
- If you used Maven plugins (e.g., for shading), add equivalent Gradle plugins (e.g., Shadow plugin).
- **Update .gitignore**
- Add Gradle-specific files (`.gradle/`, `build/`) and remove Maven-specific ones (`target/`).
- **Remove Maven Files**
- Remove `pom.xml` and any Maven wrapper files if not needed.
- **Update Documentation and Scripts**
- Update README, CONTRIBUTING, and any scripts to use Gradle commands (`./gradlew build`, etc.).
- **Test the Build**
- Run `./gradlew build` and verify the output jar works as expected.
### Task List for Migration
- [ ] Initialize Gradle build system
- [ ] Set project metadata in `build.gradle`
- [ ] Add repositories and dependencies
- [ ] Configure Java version
- [ ] Ensure resource handling for `plugin.yml`
- [ ] Add Gradle plugins as needed (e.g., Shadow)
- [ ] Update `.gitignore` for Gradle
- [ ] Remove Maven files
- [ ] Update documentation and scripts
- [ ] Test the Gradle build
#### Summary Table
| Step | Description |
|-----------------------------|------------------------------------------------|
| Initialize Gradle | Create `build.gradle` or use `gradle init` |
| Project Metadata | Set group, version, description |
| Dependencies | Add PaperMC repo and dependencies |
| Java Version | Set Java toolchain/source compatibility |
| Resource Handling | Ensure `plugin.yml` in resources |
| Build Plugins | Add Shadow or other plugins as needed |
| .gitignore | Add Gradle files, remove Maven files |
| Remove Maven Files | Delete `pom.xml`, Maven wrapper |
| Documentation/Scripts | Update to use Gradle |
| Test Build | Run and verify `./gradlew build` |
**Do not make any code or config changes until this plan is complete and reviewed.**
## Appendix: Codebase Analysis and Migration Notes
### Deprecated or Removed API Usage
- **Logger usage:**
- Uses `Logger.getLogger("Minecraft")`. Should use `getLogger()` from `JavaPlugin` for modern plugins.
- **Old event registration:**
- Uses deprecated Bukkit event registration (`pm.registerEvent(...)` with `Event.Type` and `Event.Priority`). Should use the modern event system (`@EventHandler` and `registerEvents`).
- **Listener classes:**
- Uses `EntityListener` and `PlayerListener` base classes, which are deprecated. Should use `Listener` interface and annotate handler methods with `@EventHandler`.
- **Configuration API:**
- Uses `org.bukkit.util.config.Configuration`, which is removed in modern Bukkit/Spigot/Paper. Should use `JavaPlugin#getConfig()` and the modern configuration API.
- **Entity/Player mapping:**
- Uses `HashMap<Entity, Player>` for claimed mobs. This is generally fine, but if player scores are stored, use `UUID` as the key for reliability across sessions.
- **Direct CraftBukkit class names:**
- Score table uses class names like `org.bukkit.craftbukkit.entity.CraftZombie`. Should use Bukkit API types or entity type enums for compatibility.
### Hardcoded Bukkit References and Legacy Patterns
- Imports are from `org.bukkit.*`, which is compatible with Paper. No hardcoded Bukkit-only features found, but all event and config usage must be updated for Paper.
- No use of Bukkit’s old event system in active code, but event registration and listener patterns are outdated.
### Custom Scripts and Resources
- **Bash scripts in `tools/bash/`:**
- `deploy-plugin.sh`: Deploys the built plugin jar to the server's plugins directory, using `MINECRAFT_SERVER_PATH`.
- `build-plugin.sh`: Runs `./gradlew build` from the project root.
- These scripts are compatible with a Gradle-based workflow and do not require migration, but should be updated if the build or deployment process changes.
### Recommendations for Paper Migration
- Switch all logger usage to `getLogger()` from `JavaPlugin`.
- Refactor all event listeners to use the modern event system (`Listener` interface, `@EventHandler`, and `registerEvents`).
- Replace use of `org.bukkit.util.config.Configuration` with the modern configuration API (`getConfig()`, `saveConfig()`, etc.).
- Update score table to use Bukkit entity types or enums instead of CraftBukkit class names.
- If storing player scores, use `UUID` as the key.
- Review and update all event and configuration usage for compatibility with modern PaperMC.
- Ensure all commands are properly defined in `plugin.yml`.
#### Summary Table
| Issue/Pattern | Status / Recommendation |
|------------------------------|----------------------------------------|
| Logger | ❌ Use getLogger() |
| Old event registration | ❌ Use @EventHandler, Listener, registerEvents |
| Listener base classes | ❌ Use Listener interface, @EventHandler|
| Configuration API | ❌ Use getConfig(), saveConfig() |
| Entity/Player mapping | ⚠️ Use UUID for player scores if needed|
| CraftBukkit class names | ⚠️ Use Bukkit API/entity types |
| Command registration | ✅ Valid, check plugin.yml |
| Hardcoded Bukkit features | ✅ None found, but update all event/config usage |
| Custom scripts | ✅ Compatible, update if build/deploy changes |