diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..7a7f230 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,37 @@ +# Copilot Instructions + +This repository follows the DPC (Dans Plugins Community) conventions defined at +https://github.com/Dans-Plugins/dpc-conventions. Read those conventions before +making any changes. + +## Technology Stack + +- Language: Java +- Build tool: Maven +- Target platform: Spigot / Paper (Minecraft plugin, API version 1.13+) +- Test framework: Not yet configured (add JUnit via Maven Surefire in pom.xml when introducing tests) + +## Project Structure + +- `src/main/java/dansplugins/spawnsystem/` – Plugin source code + - `commands/` – Command executor classes + - `listeners/` – Bukkit event listener classes + - `services/` – Business-logic services (command dispatch, storage) + - `utils/` – Utility helpers (block checking, UUID lookup, event registration) + - `data/` – Persistent data model + - `bstats/` – bStats metrics integration +- `src/main/resources/` – `plugin.yml` and other resources +- `src/test/java/` – Unit tests (if/when a test suite is added) + +## Coding Conventions + +- Follow the existing package structure (`dansplugins.spawnsystem.*`) when adding new classes. +- All user-facing messages are currently hard-coded strings; prefer extracting them to a lang file in `src/main/resources/lang/` for new contributions. +- Annotate every command executor and event listener with `@Override` where applicable. +- The plugin uses the Maven Shade plugin to produce a shaded JAR in `target/`. + +## Contribution Workflow + +- Branch from `develop` for all changes. +- Open a pull request against `develop`, not `main`. +- Reference the related GitHub issue in every pull request description. diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..4830bd4 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,26 @@ +name: Build + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main, develop ] + +permissions: + contents: read + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Set up JDK 8 + uses: actions/setup-java@v4 + with: + java-version: '8' + distribution: 'temurin' + + - name: Build with Maven + run: mvn clean package diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..a95a865 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,31 @@ +name: Release + +on: + release: + types: [ created ] + +permissions: + contents: write + +jobs: + build-and-attach: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - name: Set up JDK 8 + uses: actions/setup-java@v4 + with: + java-version: '8' + distribution: 'temurin' + + - name: Build with Maven + run: mvn clean package + + - name: Upload JAR to release + uses: softprops/action-gh-release@v2 + with: + files: | + target/*.jar + !target/original-*.jar diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c7a63b2 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,20 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). + +## [Unreleased] + +## [1.2] – (date unknown) + +### Changed +- Internal refactoring of spawn storage and event handling. + +## [1.0] – (date unknown) + +### Added +- Initial release. +- `[Spawn]` sign mechanic: right-clicking a sign sets the player's respawn point. +- `/resetspawn` command to clear a player's custom spawn. +- bStats metrics integration (plugin ID 12161). diff --git a/COMMANDS.md b/COMMANDS.md new file mode 100644 index 0000000..8222fd7 --- /dev/null +++ b/COMMANDS.md @@ -0,0 +1,12 @@ +# Commands Reference + +## Spawn Commands + +### /resetspawn [player] + +**Description:** Resets a player's custom spawn point, returning them to the world's default spawn on next death. +**Permission (no argument):** `spawnsystem.reset.self` or `spawnsystem.admin` +**Permission (with argument):** `spawnsystem.reset.others` or `spawnsystem.admin` +**Usage:** (in-game players only) `/resetspawn` or `/resetspawn ` +**Example:** `/resetspawn` — resets your own spawn +**Example:** `/resetspawn Steve` — resets Steve's spawn diff --git a/CONFIG.md b/CONFIG.md new file mode 100644 index 0000000..93b6ec5 --- /dev/null +++ b/CONFIG.md @@ -0,0 +1,17 @@ +# Configuration Guide + +Dans-Spawn-System does not currently use a `config.yml` file. All configuration is performed through in-game signs and permissions. + +## Permissions Configuration + +Permissions can be managed through any standard Bukkit permissions plugin (e.g. LuckPerms). + +| Permission Node | Default | Description | +|-----------------|---------|-------------| +| `spawnsystem.placeSpawnSign` | op | Allows placing `[Spawn]` signs | +| `spawnsystem.breakSpawnSign` | op | Allows breaking `[Spawn]` signs | +| `spawnsystem.reset.self` | op | Allows a player to reset their own spawn | +| `spawnsystem.reset.others` | op | Allows resetting another player's spawn | +| `spawnsystem.admin` | op | Grants all plugin permissions | + +By default, these permissions are granted to server operators (`op`) and can be overridden by your permissions plugin. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..96beecc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Contributing + +## Thank You + +Thank you for your interest in contributing to Dans-Spawn-System! This guide will help you get started. + +## Links + +- [Website](https://dansplugins.com) +- [Discord](https://discord.gg/xXtuAQ2) + +## Requirements + +- A GitHub account +- Git installed on your local machine +- A Java IDE or text editor +- A basic understanding of Java + +## Getting Started + +1. [Sign up for GitHub](https://github.com/signup) if you don't have an account. +2. Fork the repository by clicking **Fork** at the top right of the repo page. +3. Clone your fork: `git clone https://github.com//Dans-Spawn-System.git` +4. Open the project in your IDE. +5. Build the plugin: `mvn clean package` + If you encounter errors, please open an issue. + +## Identifying What to Work On + +### Issues + +Work items are tracked as [GitHub issues](https://github.com/Dans-Plugins/Dans-Spawn-System/issues). + +### Milestones + +Issues are grouped into [milestones](https://github.com/Dans-Plugins/Dans-Spawn-System/milestones) representing upcoming releases. + +## Making Changes + +1. Make sure an issue exists for the work. If not, create one. +2. Switch to `develop`: `git checkout develop` +3. Create a branch: `git checkout -b ` +4. Make your changes. +5. Test your changes. +6. Commit: `git commit -m "Description of changes"` +7. Push: `git push origin ` +8. Open a pull request against `develop`, link the related issue with `#`. +9. Address review feedback. + +## Testing + +There are currently no automated unit tests configured for this project. + +Please verify your changes manually by: + +- Building the plugin: `mvn clean package` +- Copying the built JAR from `target/` into your test server's `plugins/` folder +- Starting the server and ensuring the plugin loads without errors in the console +- Exercising relevant spawn-related functionality to confirm your changes behave as expected + +## Questions + +Ask in the [Discord server](https://discord.gg/xXtuAQ2). diff --git a/README.md b/README.md index d046576..f641f18 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,94 @@ # Dans-Spawn-System -An open source plugin that allows players to use signs to select a custom spawn in their world. + +## Description + +Dans-Spawn-System is a Minecraft plugin that allows players to use signs to select a custom spawn point in their world. Server operators place `[Spawn]` signs with coordinates, and players right-click those signs to set their personal respawn location. + +## Installation + +### First Time Installation + +1. Download the plugin from [SpigotMC](https://www.spigotmc.org/resources/dans-spawn-system.95997/). +2. Place the jar in the `plugins` folder of your server. +3. Restart your server. + +## Usage + +### Documentation + +- [User Guide](USER_GUIDE.md) – Getting started and common scenarios +- [Commands Reference](COMMANDS.md) – Complete list of all commands +- [Configuration Guide](CONFIG.md) – Detailed configuration options + +### Wiki & Additional Resources + +- [Wiki Guide](https://github.com/Dans-Plugins/Dans-Spawn-System/wiki) + +## Support + +You can find the support Discord server [here](https://discord.gg/xXtuAQ2). + +### Experiencing a bug? + +Please fill out a bug report [here](https://github.com/Dans-Plugins/Dans-Spawn-System/issues/new). + +- [Known Bugs](https://github.com/Dans-Plugins/Dans-Spawn-System/issues?q=is%3Aissue+is%3Aopen+label%3Abug) + +## Contributing + +- [CONTRIBUTING.md](CONTRIBUTING.md) +- [Notes for Developers](https://github.com/Dans-Plugins/Dans-Spawn-System/wiki) + +## Testing + +### Automated Tests + +This project does not currently include automated unit tests. + +To verify that the project builds successfully, run: + +Linux: + + mvn clean package + +Windows: + + mvn.cmd clean package + +If you see `BUILD SUCCESS`, the project compiled successfully. For validating functional changes, follow the steps in the **Development** section below to run the plugin on a test server. + +## Development + +### Manual Testing on a Server + +1. Build the plugin: `mvn clean package` +2. Copy the resulting jar from `target/` into your server's `plugins/` folder (exclude `original-*.jar`). +3. Start your test server and verify the plugin loads without errors. + +## Authors + +### Developers + +| Name | Main Contributions | +|------|--------------------| +| DanTheTechMan | Original author and lead developer | ## License This project is licensed under the [GNU General Public License v3.0](LICENSE) (GPL-3.0). You are free to use, modify, and distribute this software, provided that: + - Source code is made available under the same license when distributed. - Changes are documented and attributed. - No additional restrictions are applied. See the [LICENSE](LICENSE) file for the full text of the GPL-3.0 license. + +## Project Status + +This project is in active development. + +### bStats + +You can view the bStats page for the plugin [here](https://bstats.org/plugin/bukkit/DansSpawnSystem/12161). diff --git a/USER_GUIDE.md b/USER_GUIDE.md new file mode 100644 index 0000000..d873461 --- /dev/null +++ b/USER_GUIDE.md @@ -0,0 +1,55 @@ +# User Guide + +## Prerequisites + +- A Spigot or Paper Minecraft server (1.13 or later) +- The Dans-Spawn-System plugin installed in your `plugins/` folder + +## First Steps + +After installing the plugin and restarting your server, players can have their respawn location customised by interacting with spawn-selection signs placed by administrators. + +## Common Scenarios + +### Setting Up a Spawn Selection Sign (Admin) + +1. Place a sign in the world. +2. On the **first line** of the sign, type `[Spawn]`. +3. On the **second line**, enter the X coordinate of the target spawn location. +4. On the **third line**, enter the Y coordinate. +5. On the **fourth line**, enter the Z coordinate. +6. Confirm placement — you will see a green confirmation message if you have the required permission. + +**Example sign contents:** + +``` +[Spawn] +100 +64 +-200 +``` + +Players who right-click this sign will have their respawn point set to coordinates (100, 64, -200) in their current world. + +### Selecting a Spawn (Player) + +Simply **right-click** any `[Spawn]` sign to set your personal respawn location to the coordinates written on that sign. + +### Resetting a Player's Spawn (Admin) + +Use the `/resetspawn` command to clear a player's custom spawn: + +- Reset your own spawn: `/resetspawn` +- Reset another player's spawn: `/resetspawn ` + +See [COMMANDS.md](COMMANDS.md) for full command details. + +## Permissions + +| Permission Node | Default | Description | +|-----------------|---------|-------------| +| `spawnsystem.placeSpawnSign` | op | Allows placing `[Spawn]` signs | +| `spawnsystem.breakSpawnSign` | op | Allows breaking `[Spawn]` signs | +| `spawnsystem.reset.self` | op | Allows resetting your own spawn with `/resetspawn` | +| `spawnsystem.reset.others` | op | Allows resetting another player's spawn with `/resetspawn ` | +| `spawnsystem.admin` | op | Grants all plugin permissions | diff --git a/src/main/resources/plugin.yml b/src/main/resources/plugin.yml index 9d544d7..c8ed9dd 100644 --- a/src/main/resources/plugin.yml +++ b/src/main/resources/plugin.yml @@ -8,11 +8,13 @@ commands: resetspawn: permissions: - dansplugins.spawnsystem.reset.self: + spawnsystem.reset.self: default: op - dansplugins.spawnsystem.reset.others: + spawnsystem.reset.others: default: op - dansplugins.placeSpawnSign: + spawnsystem.placeSpawnSign: default: op - dansplugins.breakSpawnSign: + spawnsystem.breakSpawnSign: + default: op + spawnsystem.admin: default: op \ No newline at end of file