318 lines
14 KiB
Markdown
318 lines
14 KiB
Markdown
# Modernize ScoreKeeper Minecraft Plugin
|
||
|
||
This checklist will guide the process of updating the ScoreKeeper plugin for compatibility with modern Minecraft Java servers (e.g., PaperMC, Spigot, or Bukkit 1.19+).
|
||
|
||
## Modernization Plan
|
||
|
||
- [x] **Analyze current codebase**
|
||
- Review all source files and dependencies
|
||
- Identify deprecated or removed APIs
|
||
- [ ] **Update build system**
|
||
- Update `pom.xml` to use a modern Bukkit/Spigot/PaperMC API version (e.g., 1.19+)
|
||
- Remove or update old repositories
|
||
- Ensure Java version compatibility (Java 17+ for latest servers)
|
||
- [ ] **Update plugin.yml**
|
||
- Ensure all required fields are present and up to date
|
||
- Update API version and commands
|
||
- [ ] **Refactor deprecated API usage**
|
||
- Replace removed or changed Bukkit/Spigot API calls
|
||
- Update event listeners and command registration
|
||
- [ ] **Test on a modern server**
|
||
- Build the plugin
|
||
- Run on a local PaperMC/Spigot server (latest LTS)
|
||
- Use the provided scripts (`tools/bash/start-server.sh` and `tools/bash/stop-server.sh`) to manage the server, and set the `MINECRAFT_SERVER_PATH` and `MINECRAFT_SERVER_JAR` environment variables as described in CONTRIBUTING.md.
|
||
- Check for errors and warnings
|
||
- [ ] **Fix bugs and incompatibilities**
|
||
- Address any issues found during testing
|
||
- [ ] **Add/update documentation**
|
||
- Update README with new usage instructions
|
||
- Document any new features or changes
|
||
- [ ] **Optional: Add new features or improvements**
|
||
- Consider adding quality-of-life improvements or new features
|
||
|
||
---
|
||
|
||
Check off each step as you complete it to track your progress!
|
||
|
||
---
|
||
|
||
## 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: Codebase Analysis and Migration Notes
|
||
|
||
### Deprecated or Removed API Usage
|
||
- **Player as HashMap key:**
|
||
- Uses `HashMap<Player, Integer>`. This is not reliable; use `UUID` as the key instead.
|
||
- **Logger usage:**
|
||
- Uses `Logger.getLogger("Minecraft")`. Use `getLogger()` from `JavaPlugin` for modern plugins.
|
||
- **Old event registration (commented out):**
|
||
- Uses deprecated Bukkit event registration. Modernize with `@EventHandler` and `registerEvents` if needed.
|
||
- **Player lookup:**
|
||
- Uses `getServer().getPlayer(name)`. This is case-sensitive and only matches exact names in modern Paper/Spigot. Consider using `getPlayerExact` or handling case-insensitivity.
|
||
|
||
### Hardcoded Bukkit References
|
||
- All imports are from `org.bukkit.*`, which is compatible with Paper. No hardcoded Bukkit-only features found.
|
||
- No use of Bukkit’s old event system in active code (just commented out).
|
||
|
||
### Recommendations for Paper Migration
|
||
- Switch all player score storage to use `UUID` instead of `Player` as the key.
|
||
- Use `getLogger()` from `JavaPlugin` for logging.
|
||
- If you add event listeners, use the modern event system (`@EventHandler`, `registerEvents`).
|
||
- Review and update player lookup logic for case sensitivity and exact matching.
|
||
- Ensure all commands are properly defined in `plugin.yml`.
|
||
|
||
#### Summary Table
|
||
| Issue/Pattern | Status / Recommendation |
|
||
|------------------------------|----------------------------------------|
|
||
| Player as HashMap key | ❌ Use UUID instead |
|
||
| Logger | ❌ Use getLogger() |
|
||
| Old event registration | ❌ Use @EventHandler, registerEvents |
|
||
| Command registration | ✅ Valid, check plugin.yml |
|
||
| Player lookup | ⚠️ Use getPlayerExact for safety |
|
||
| Hardcoded Bukkit features | ✅ None found |
|
||
|
||
---
|
||
|
||
## 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` |
|