Modernize build tooling, dependencies, and documentation for Guilds

.gitattributes

@@ -0,0 +1,11 @@
+* text=auto
+
+*.sh text eol=lf
+gradlew text eol=lf
+*.bat text eol=crlf
+*.ps1 text eol=crlf
+
+*.jar binary
+*.png binary
+*.jpg binary
+*.gif binary

.github/workflows/gradle.yml

@@ -2,23 +2,44 @@ name: Java CI with Gradle
 
 on:
   push:
-    branches: [ "master" ]
+    branches:
+      - master
   pull_request:
-    branches: [ "master" ]
+    branches:
+      - master
+  workflow_dispatch:
 
 permissions:
   contents: read
+  checks: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
 
 jobs:
   build:
+    name: Build
     runs-on: ubuntu-latest
+    timeout-minutes: 20
+
     steps:
-    - uses: actions/checkout@v4
-    - uses: actions/setup-java@v4
-      with:
-        distribution: 'temurin'
-        java-version: '21'
-    - name: Setup Gradle
-      uses: gradle/gradle-build-action@v3
-    - name: Build with Gradle
-      run: ./gradlew build
+      - name: Checkout sources
+        uses: actions/checkout@v6
+
+      - name: Set up Java
+        uses: actions/setup-java@v5
+        with:
+          distribution: temurin
+          java-version: "21"
+
+      - name: Setup Gradle
+        uses: gradle/actions/setup-gradle@v6
+        with:
+          cache-provider: basic
+
+      - name: Make Gradle wrapper executable
+        run: chmod +x ./gradlew
+
+      - name: Build shaded plugin
+        run: ./gradlew clean shadowJar --no-daemon --stacktrace

.gitignore

@@ -14,6 +14,7 @@ build
 
 # IntelliJ
 .idea
+.kotlin
 
 out
 

HEADER.txt

@@ -0,0 +1,8 @@
+/*
+ * This file is part of Guilds.
+ *
+ * Guilds is free software: you can redistribute it and/or modify
+ * it under the terms of the MIT License.
+ *
+ * Copyright (c) GlareMasters
+ */

README.md

@@ -1,44 +1,167 @@
-[![Guilds](https://i.imgur.com/KE562QO.png)](https://github.com/guilds-plugin/Guilds)
+# Guilds
 
 [![Discord](https://discordapp.com/api/guilds/164280494874165248/widget.png?style=banner2)](https://helpch.at/discord)
-
 [![Crowdin](https://badges.crowdin.net/guilds/localized.svg)](https://crowdin.com/project/guilds)
-### What is Guilds?
-___
 
-The Guilds Project was created to offer a RPG type system to servers.
-It was inspired by players like you who enjoy creating a fun and exciting environment for your server.
-Guilds allows players to join interactive groups of other players, forge their own communities on your server, and compete with other guilds for dominance and control.
+Guilds adds RPG-style player communities to Minecraft servers. Players can create and join guilds, build shared identities, compete with other groups, manage claims and roles, and connect with common server plugins such as Vault, LuckPerms, EssentialsX, PlaceholderAPI, and WorldGuard.
+
+For user documentation, see the [Guilds wiki](https://wiki.helpch.at/).  
+For API documentation, see the [Javadocs](https://guilds-plugin.github.io/javadocs/).
+
+---
+
+## Requirements
+
+Guilds now requires **Java 11 or newer** at runtime.
+
+This applies even when running older Minecraft versions such as 1.8.8. The plugin may support legacy Minecraft server versions, but the JVM running the server must be Java 11+.
+
+Recommended Java versions for local testing:
+
+| Minecraft / Paper version | Recommended Java |
+| --- | ---: |
+| 1.8.8 | 11 |
+| 1.16.5 | 16 |
+| 1.18.2 | 17 |
+| 1.19.4 | 17 |
+| 1.20.6 | 21 |
+| 1.21.1 | 21 |
+| 1.21.4 | 21 |
+| 1.21.8 | 21 |
+| 26.1.2 | 25 |
+
+---
+
+## Runtime dependencies
+
+Guilds uses [Quark](https://github.com/BX-Team/Quark) to load the Kotlin runtime at plugin startup instead of shading Kotlin directly into the plugin jar. This keeps the distributed jar smaller while preserving a normal Bukkit/Spigot/Paper plugin workflow.
+
+The Quark loader is configured for the **Bukkit** platform so the same artifact can run on Spigot-compatible and Paper-compatible servers.
+
+Server admins should allow the server to download runtime dependencies from Maven Central on first startup. If outbound network access is blocked, preload or mirror the required runtime dependencies before deploying.
+
+---
+
+## Supported integrations
+
+Guilds is designed to work with common server plugins and APIs:
+
+| Integration | Purpose |
+| --- | --- |
+| Vault | Economy and permission bridge |
+| LuckPerms | Permission provider through Vault |
+| EssentialsX | Economy and chat-related compatibility |
+| PlaceholderAPI | Placeholder expansion support |
+| WorldGuard | Region and claim-related hooks |
+| bStats | Anonymous plugin metrics |
+
+Vault is required for normal operation. Economy and permission providers must be available through Vault.
+
+---
+
+## Building from source
+
+Use the Gradle wrapper:
+
+```bash
+./gradlew clean shadowJar --no-configuration-cache
+```
+
+The shaded plugin jar is written to:
 
-This plugin is for Minecraft Servers!
+```text
+build/libs/Guilds-<version>.jar
+```
 
-For more information, you can check out the [wiki](https://wiki.helpch.at/)!  
-Looking for the javadocs? You can see them [here](https://guilds-plugin.github.io/javadocs/)!
+Configuration cache is intentionally disabled for Quark-enabled builds because Quark's generated-file task is not currently configuration-cache compatible.
 
-### Support
-___
+To check dependency updates:
 
-Looking to get support for something? Join the Discord above to get help and discuss with others!
+```bash
+./gradlew dependencyUpdates --no-configuration-cache --no-parallel
+```
 
-### Contributing
-___
+---
 
-Do you want to help the project grow and achieve new goals? You can help us out in many ways!
+## Local test servers
 
-If you'd like to support our work and buy us a coffee, you could join our [Patreon](https://www.patreon.com/GlareMasters)! We totally understand if you can't do that so we have others ways you can help us out too:
+The build includes local Paper test-server tasks powered by `run-paper`.
 
-* Are you an active user of the plugin and want to help others with it? Check out the [issues](https://github.com/guilds-plugin/Guilds/issues) page to see if anyone has questions. You could also hop in our [Discord](https://glaremasters.me/discord) and help others out there too!
-* Are you a person who speaks more than one language? Check out our translations page [here](https://crowdin.com/project/guilds) and see if you can help with your language!
-* Are you a person who also likes to program? If so, you could look through the open [issues](https://github.com/guilds-plugin/Guilds/issues) and see if there's anything you'd ike to PR into the project.
+Examples:
 
-### Community Made Addons
-___
+```bash
+./gradlew runServer1_8_8 --no-configuration-cache
+./gradlew runServer1_16_5 --no-configuration-cache
+./gradlew runServer1_21_8 --no-configuration-cache
+./gradlew runServer26_1_2 --no-configuration-cache
+```
 
-* [GuildClaimAddons](https://github.com/Nerumir/GuildClaimsAddon) - An alternative addon for the claiming system in the plugin
+These tasks:
+
+- build and attach the current Guilds jar
+- create a local `eula.txt`
+- run the target server with the configured Java toolchain
+- preload common test plugins such as Vault, LuckPerms, and EssentialsX where compatible
+
+Run-server tasks are intended for local smoke testing. They are interactive and should not be used as normal CI checks.
+
+---
+
+## Development notes
+
+Current modernization decisions:
+
+- Java runtime baseline: **Java 11+**
+- Java bytecode target: **Java 11**
+- Kotlin runtime: loaded at startup through Quark
+- Kotlin stdlib: not shaded into the jar
+- Shadow: still used for the remaining implementation dependencies
+- ConfigMe: pinned to `1.3.0` for legacy Paper compatibility
+- Triumph GUI: pinned to `3.1.11` until GUI constructors are migrated
+- HikariCP: pinned to `4.0.3` for conservative compatibility
+
+Before opening a pull request, run:
+
+```bash
+./gradlew clean shadowJar --no-configuration-cache
+```
+
+Optional formatting/license checks:
+
+```bash
+./gradlew spotlessCheck --no-configuration-cache
+```
+
+---
+
+## Contributing
+
+Contributions are welcome.
+
+Good places to help:
+
+- bug reports and reproduction cases
+- compatibility testing across Minecraft versions
+- translations on [Crowdin](https://crowdin.com/project/guilds)
+- documentation improvements
+- pull requests for open [GitHub issues](https://github.com/guilds-plugin/Guilds/issues)
+
+For support or project discussion, join the Discord linked at the top of this README.
+
+---
+
+## Community add-ons
+
+- [GuildClaimsAddon](https://github.com/Nerumir/GuildClaimsAddon) — alternative addon for the claiming system
+
+---
+
+## Special thanks
 
-## Special Thanks
 ![YourKit](https://www.yourkit.com/images/yklogo.png)
 
-YourKit supports open source projects with innovative and intelligent tools  
-for monitoring and profiling Java and .NET applications.  
-YourKit is the creator of [YourKit Java Profiler](https://www.yourkit.com/java/profiler/), [YourKit .NET Profiler](https://www.yourkit.com/.net/profiler/), and [YourKit YouMonitor](https://www.yourkit.com/youmonitor/).
+YourKit supports open source projects with tools for monitoring and profiling Java and .NET applications.
+
+- [YourKit Java Profiler](https://www.yourkit.com/java/profiler/)
+- [YourKit .NET Profiler](https://www.yourkit.com/.net/profiler/)
+- [YourKit YouMonitor](https://www.yourkit.com/youmonitor/)