From bbc512a04474bedb3a53d072026a75a57db533d4 Mon Sep 17 00:00:00 2001 From: Tom Hicks Date: Mon, 14 Jul 2025 05:54:58 -0700 Subject: [PATCH] Addsd modernization plan and tasks for implementation. --- .cursor/plans/Modernize.md | 378 +++++++++++++++++++++++++++++++++++++ .cursor/rules.md | 10 + TODO.md | 18 ++ 3 files changed, 406 insertions(+) create mode 100644 .cursor/plans/Modernize.md create mode 100644 .cursor/rules.md diff --git a/.cursor/plans/Modernize.md b/.cursor/plans/Modernize.md new file mode 100644 index 0000000..b2020ed --- /dev/null +++ b/.cursor/plans/Modernize.md @@ -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` 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 | \ No newline at end of file diff --git a/.cursor/rules.md b/.cursor/rules.md new file mode 100644 index 0000000..f73ea9a --- /dev/null +++ b/.cursor/rules.md @@ -0,0 +1,10 @@ +# Cursor Rules for Modernizing ScoreKeeper + +- All plans should be created in `.cursor/plans`. +- All plans should use checkboxes to track the completion state of action items or implementation steps. +- Do not add checkboxes to items that are informational, such as notes or descriptions. +- Use `bash` or `zsh` as the shell for development tasks. +- Any tool scripts should use `bash` as their shell. +- By default, the user will manually run build or test commands and provide the output. However, if the user requests, commands may be run directly—always show the command and ask for output unless instructed otherwise. +- When creating or updating plans, do not make changes to the project code or files (other than the plan files themselves). Only update plan files to reflect progress or changes. +- Create and track tasks in `TODO.md` with checkboxes to track implementation. diff --git a/TODO.md b/TODO.md index e69de29..7662a18 100644 --- a/TODO.md +++ b/TODO.md @@ -0,0 +1,18 @@ +# Modernize MobScores Plugin: Implementation Tasks + +- [ ] Analyze all Java source files for deprecated or removed Bukkit API usage, including logger, event registration, listener classes, configuration API, and entity/player mapping. +- [ ] Identify and document any hardcoded Bukkit references or legacy patterns (e.g., Player as HashMap key, old event registration, CraftBukkit class names). _(Depends on: code analysis)_ +- [ ] Review and list any custom scripts or resources (e.g., bash scripts in tools/bash/) that may need migration or updates. _(Depends on: code analysis)_ +- [ ] Initialize Gradle in the project root and create a build.gradle file with project metadata, PaperMC API dependency, JUnit, Java toolchain, repository, resource handling, and plugins as needed. _(Depends on: code analysis)_ +- [ ] Remove Maven-specific files (pom.xml, .mvn/ directory, Maven wrapper scripts) and Eclipse-specific files (.classpath, .project, .settings/) if present. _(Depends on: Gradle init)_ +- [ ] Update .gitignore to add Gradle-specific ignores and remove Maven/Eclipse-specific ignores. _(Depends on: Gradle init)_ +- [ ] Ensure plugin.yml is present in src/main/resources and update for PaperMC compatibility (api-version, commands, required fields). _(Depends on: Gradle init)_ +- [ ] Refactor all logger usage to use getLogger() from JavaPlugin. _(Depends on: code analysis)_ +- [ ] Refactor all event listeners to use the modern event system (Listener interface, @EventHandler, registerEvents). _(Depends on: code analysis)_ +- [ ] Replace use of org.bukkit.util.config.Configuration with the modern configuration API (getConfig(), saveConfig(), etc.). _(Depends on: code analysis)_ +- [ ] Update score table to use Bukkit entity types or enums instead of CraftBukkit class names. _(Depends on: code analysis)_ +- [ ] If storing player scores, refactor to use UUID as the key instead of Player or String. _(Depends on: code analysis)_ +- [ ] Build the plugin with Gradle (./gradlew build) and test on a modern Paper server using the provided bash scripts. _(Depends on: all refactors and plugin.yml update)_ +- [ ] Address any bugs or incompatibilities found during testing on a modern server. _(Depends on: build and test)_ +- [ ] Update README.md and CONTRIBUTING.md with new build, usage, and development instructions. _(Depends on: bugfixes)_ +- [ ] (Optional) Add new features, quality-of-life improvements, automated tests, or CI configuration. _(Depends on: docs update)_