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

Adds Windows specific info and powershell scripts to CONTRIBUTING.md.

Browse Source
This commit is contained in:
Tom Hicks
2025-08-06 20:39:24 -07:00
parent e769ba7088
commit 0c60e4bd0c
1 changed files with 136 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

162
CONTRIBUTING.md
View File

@@ -3,44 +3,154 @@
Thank you for your interest in contributing to the ScoreKeeper plugin! This guide will help you set up your development environment and follow best practices for working with the project.
## Development Environment Setup
# Getting Started
Pick a folder to hold your minecraft server and this project I'm going to use `$HOME/Projects`. My Minecraft server will be in `$HOME/Projects/MCServer` and this project will be in `$HOME/Projects/ScoreKeeper`.
To develop and test the ScoreKeeper plugin, you will need:
- A Paper Minecraft server (for plugin deployment and testing)
- The official Minecraft Java Edition client (for connecting to your test server)
Setup our project folder.
### 1. Setting up the Paper Server (macOS/Linux/WSL)
1. Download the latest Paper server jar from [https://papermc.io/downloads](https://papermc.io/downloads).
2. Create a directory for your test server and place the Paper jar inside.
3. Set the following environment variables in your shell profile (e.g., `.bashrc`, `.zshrc`, or manually in your terminal):
```bash
export MINECRAFT_SERVER_PATH=/path/to/your/server
export MINECRAFT_SERVER_JAR=paper-<version>.jar # Can be relative to MINECRAFT_SERVER_PATH or absolute
```
4. Use the provided scripts to manage your server:
- To start (or restart) the server: `tools/bash/start-server.sh`
- To stop the server: `tools/bash/stop-server.sh`
These scripts use the environment variables above to locate and manage your server.
5. On first run, accept the EULA by editing `eula.txt` and setting `eula=true` in your server directory.
6. Place your built plugin jar in the `plugins/` directory.
7. Use the start script again to restart the server and load the plugin.
**Linux, macOS, and WSL**
```bash
PROJECTS_DIR="$HOME/Projects"
MINECRAFT_SERVER_PATH="$PROJECTS_DIR/MCServer"
# Set this to the latest download url on the Paper downloads page [https://papermc.io/downloads](https://papermc.io/downloads) and update the jar name.
MINECRAFT_SERVER_DOWNLOAD_URI="https://fill-data.papermc.io/v1/objects/fb73c7e310215016955617ab957022d9e1d47aeba206df3a98c5ecb43756527c/paper-1.21.8-25.jar"
MINECRAFT_SERVER_JAR="paper-1.21.8-25.jar"
mkdir -p "$MINECRAFT_SERVER_PATH"
# Keep this shell open we will use these variables later.
```
### 2. Setting up the Minecraft Client
- **macOS/Linux:**
**Windows**
```powershell
$projectsDir="$HOME\Projects"
$minecraftServerDir="$projectsDir\MCServer"
# Set this to the latest download url on the Paper downloads page [https://papermc.io/downloads](https://papermc.io/downloads) and update the jar name.
$minecraftServerDownloadUri="https://fill-data.papermc.io/v1/objects/fb73c7e310215016955617ab957022d9e1d47aeba206df3a98c5ecb43756527c/paper-1.21.8-25.jar"
$minecraftServerJar="paper-1.21.8-25.jar"
New-Item -Type Directory $projectsDir
New-Item -Type Directory $minecraftServerDir
# Keep this shell open we will use these variables later.
```
## Install the JDK
**Linux / WSL**
```bash
apt install openjdk-21-jdk
```
**macOS**
```zsh
brew install --cask microsoft-openjdk@21
```
**Windows**
From Powershell
```powershell
winget install --id Microsoft.OpenJDK.21 --source winget
```
## Setup a PaperMC Server
**Linux, macOS, and WSL**
```bash
# You're probably still here, but if not go to the server dir.
cd "$MINECRAFT_SERVER_PATH"
curl -O "$MINECRAFT_SERVER_DOWNLOAD_URI"
java -jar "$MINECRAFT_SERVER_JAR"
nano eula.txt # Change eula=false to eula=true, then save and exit.
java -jar "$MINECRAFT_SERVER_JAR"
```
**Windows**
```powershell
# You're probably still here, but if not go to the server dir.
Set-Location $minecraftServerDir
Invoke-WebRequest -Uri $minecraftServerDownloadUri -OutFile (Split-Path $minecraftServerDownloadUri -Leaf)
java -jar $minecraftServerJar
notepad eula.txt
# Change eula=false to eula=true, then save and close the file.
java -jar $minecraftServerJar
```
If you get windows security popups about java with the little java dude allow them. It's because the server is listening on the network. Now you should have the server running and be dropped at a prompt like `> `. Type `stop` and hit enter to kill the server. You can also try CTRL + C.
## Get the Code
**Linux, macOS, and WSL**
```bash
cd "$PROJECTS_DIR"
git clone https://github.com/headhunter45/ScoreKeeper.git
code ScoreKeeper
```
```powershell
Set-Location $projectsDir
git clone https://github.com/headhunter45/ScoreKeeper.git
# Then to open VSCode
code ScoreKeeper
```
## Building the Plugin
This should download the preferred version of our build tool (gradle) and use it to build the project. Among other intermediate files it will create `build/libs/ScoreKeeper-${Version}.jar`. This is the plugin jar that you copy to the minecraft server to install the plugin. From now on you will use the utility scripts in `tools\powershell\*.ps1` or `tools/bash/*.sh` to build and deploy the plugin to our test server.
**Linux, macOS, and WSL**
```bash
./gradlew build
```
**Windows**
```powershell
.\gradlew.bat build
```
## Using the Utility Scripts
Our scripts depend on two environment variables. You can set them each time you open a shell or set them once for every shell your user opens. The variables are `MINECRAFT_SERVER_PATH` and `MINECRAFT_SERVER_JAR`. They are used by the scripts to know where the server is so they can control it and deploy the plugin.
**Linux, macOS, and WSL**
To set them for the current session run these commands. To set for every new session add these commands to your `.bashrc` or `.zshrc` file.
```bash
MINECRAFT_SERVER_PATH="$HOME/Projects/MCServer"
MINECRAFT_SERVER_JAR="paper-1.21.8-25.jar"
```
**Windows**
To set them for a single session run these commands.
```powershell
$env:MINECRAFT_SERVER_PATH = "$HOME\Projects\MCServer"
$env:MINECRAFT_SERVER_JAR = "paper-1.21.8-25.jar"
```
If you want them available in all of your powershell sessions you can set them permanently like this.
```powershell
[Environment]::SetEnvironmentVariable("MINECRAFT_SERVER_PATH", "$HOME\Projects\MCServer", "User")
[Environment]::SetEnvironmentVariable("MINECRAFT_SERVER_JAR", "paper-1.21.8-25.jar", "User")
```
### Start-Server.ps1 and start-server.sh
Run `tools\powershell\Start-Server.ps1` or `tools/bash/start-server.sh` to start the server and open a GUI to manage it.
### Stop-Server.ps1 and stop-server.sh
Run `tools\powershell\Stop-Server.ps1` or `tools/bash/stop-server.sh` to stop the server. You can also safely close the GUI.
### Build-Plugin.ps1 and build-plugin.sh
Run `tools\powershell\Build-Plugin.ps1` or `tools/bash/build-plugin.sh` to build the plugin. This builds the plugin in `build/libs` as a jar named `ScoreKeeper-${VERSION}.jar`. To install the plugin manually you can copy this to `$env:MINECRAFT_SERVER_PATH\plugins` or `$MINECRAFT_SERVER_PATH/plugins` and restart the server.
### Deploy-Plugin.ps1 and deploy-plugin.sh
Run `tools\powershell\Deploy-Plugin.ps1` or `tools/bash/deploy-plugin.sh` to copy the plugin to the server plugins directory. This checks if the built plugin is up to date with the source code. If it is, then the script copies the plugin to the plugins directory to install it. To use the new plugin restart the server.
# Setting up the Minecraft Client
- **macOS / Linux:**
- Download and install the official Minecraft Launcher from [minecraft.net](https://www.minecraft.net/en-us/download).
- Log in with your Mojang/Microsoft account and launch the Java Edition client.
- **WSL (Windows Subsystem for Linux):**
- **Windows / WSL (Windows Subsystem for Linux):**
- For best performance, run the Minecraft client directly under Windows, not inside WSL.
- Download and install the official Minecraft Launcher for Windows from [minecraft.net](https://www.minecraft.net/en-us/download).
- Use WSL for server and plugin development, and connect to your test server from the Windows client.
### 3. Connecting the Client to Your Server
# Connecting the Client to Your Server
- Start your Paper server (see above).
- In the Minecraft client, add a new server with the address:
- `localhost` (if running both client and server on the same machine)
- Or use your machine's IP address if connecting across devices.
### 4. Notes
- You can automate server startup and plugin deployment with bash scripts for faster testing.
- For automated testing or CI, run the Paper server in a headless Linux environment (including WSL, Docker, or CI runners).
# Notes
- Always use the provided scripts and environment variables for consistent server management.