Document MobScores setup and development

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+## Requirements
+
+- Java 25. The Gradle toolchain can download it automatically; `tools/build-plugin.sh` also provisions Temurin 25 under the project Gradle user home.
+- A recent Paper server for runtime testing.
+- The ScoreKeeper plugin, which is a required runtime dependency.
+
+## Build and Test
+
+From the project root:
+
+```sh
+./gradlew test
+./gradlew build
+```
+
+The distributable plugin JAR is written to `build/libs/`. To use the repository helper, run:
+
+```sh
+tools/build-plugin.sh
+```
+
+## Local Paper Testing
+
+Set `PAPER_VERSION` and `MINECRAFT_SERVER_PATH` in a local `.env` file at the MobScores project root, or export them in your shell. Set `MINECRAFT_ENV_FILE` if the helper scripts should load a shared environment file instead. Build ScoreKeeper and install it into the server first, then build and deploy MobScores:
+
+```sh
+tools/build-plugin.sh
+tools/deploy-plugin.sh
+```
+
+Start the server with `tools/start-server.sh`. The script downloads a stable Paper build when one is not already present. Review the server log for dependency and plugin-load errors, then test score-table configuration and mob-kill scoring in game. Back up the server before testing against a world with data you care about.
+
+## Configuration
+
+The default resource is `src/main/resources/config.yml`; Paper copies it to `plugins/MobScores/config.yml` on first startup. `ScoreTable` maps Bukkit `EntityType` names to integer point values. To change values on a test server, edit the generated config and restart the server.
+
+## Helper Scripts
+
+- `tools/build-plugin.sh` builds with Java 25.
+- `tools/deploy-plugin.sh` copies the latest non-`-all` JAR into `$MINECRAFT_SERVER_PATH/plugins/`.
+- `tools/start-server.sh` downloads/resolves and launches Paper using `.env` settings.
+- `tools/backup-server.sh` and `tools/restore-server.sh` manage server backups.
+- `tools/publish-local.sh` publishes the artifact to Maven Local for dependent plugin builds.

README.md

@@ -1,6 +1,31 @@
-This mod is copyright (c) 2011 Tom Hicks and released under the AGPL v3.  See the file agpl-3.0.txt for the specifics of the license.
+# MobScores
 
-No Commands
+MobScores awards ScoreKeeper points for configured mob kills. It is a Paper plugin and requires the ScoreKeeper plugin to be installed and enabled first.
 
-Edit plugins/MobScores/config.yml to set scores per mob.
+## Requirements
+
+- Paper 1.21.7 or a compatible newer server.
+- Java 25 to build the plugin.
+- ScoreKeeper 0.2.2 or the version declared by `build.gradle`.
+
+Install both plugin JARs in the server's `plugins` directory. MobScores declares ScoreKeeper as a hard dependency, so it will not enable without it.
+
+## Score Table
+
+On first startup, MobScores creates `plugins/MobScores/config.yml` with default scores for supported entity types. Edit the `ScoreTable` mapping to change points; keys are Bukkit `EntityType` names and values are integer points:
+
+```yaml
+ScoreTable:
+  ZOMBIE: 25
+  CREEPER: 50
+  SILVERFISH: 0
+```
+
+Restart the server after editing the configuration. A configured value of `0` suppresses that entity from the score table shown to players when they join.
+
+MobScores has no commands of its own. Current killer attribution is recorded for zombie entities directly damaged by a player; projectile and other mob attribution are not currently handled. Points are awarded through ScoreKeeper's existing player API and follow the player's UUID-backed score.
+
+## Build
+
+Run `./gradlew test` and `./gradlew build` from the project root. See [CONTRIBUTING.md](CONTRIBUTING.md) for toolchain, local server, and helper-script details.
 

TODO.md

@@ -16,7 +16,7 @@
 | MS-12 |   Done   | If storing player scores, refactor to use UUID as the key instead of Player or String.
 | MS-13 |   Done   | Build the plugin with Gradle (./gradlew build) and test on a modern Paper server using the provided bash scripts.
 | MS-14 |   Done   | Address any bugs or incompatibilities found during testing on a modern server.
-| MS-15 |   Ready  | Update README.md and CONTRIBUTING.md with new build, usage, and development instructions. _(Depends on: bugfixes)_
+| MS-15 |   Done   | Update README.md and CONTRIBUTING.md with new build, usage, and development instructions. _(Depends on: bugfixes)_
 | MS-16 |   Ready  | (Optional) Add new features, quality-of-life improvements, automated tests, or CI configuration. _(Depends on: docs update)_
 | MS-17 |   Done   | Update MobScores to depend on the latest version of the ScoreKeeper plugin (update dependency in build.gradle and plugin.yml as needed).
 | MS-18 |   Ready  | Test MobScores with the latest ScoreKeeper to ensure score tracking, awarding, and all integration points work as expected (including with players who have changed names).