FlagWar for Towny Advanced

---

Important Notices

<details><summary><b>Transitioning from the Integrated FlagWar system.</b></summary>

FlagWar has its own methods for configuration and localization, independent of Towny. Please be advised that we currently only provide an English translation. There will likely be other teething issues, but we are here to help with them when required. See [Getting Support][get-support] if you have issues.

If you would like to help out with development, translations, or other efforts: please see the <a href="#developer-resources">Developer Resources</a> section.

</details> <details><summary><b>Metrics / Telemetry</b></summary>

FlagWar, makes use of the bStats metrics library. For an idea of what is collected, you can view the telemetry reports here. While we would appreciate it if you were to keep bStats reporting enabled, you can opt out of sending telemetry by modifying the bStats config found at yourServer/plugins/bStats/.

</details>

---

Summary

FlagWar is one of the first official war systems in the Towny Advanced ecosystem, dating back around 2011. FlagWar works similar to a strategy game, where players can capture regions of other Nations and Towns quickly and with pinpoint precision.

I started getting re-involved with Towny’s development, and got some inspiration from users about how to do warring Nations. I also took a gander at some of the mechanics of a similar plugin that did PvP stuff right, Factions. I coded up some threaded tasks that created a huge beacon in the sky overtop the area under attack. The game mechanic was to attack and hold the area. Towny’s war event is the same thing, but there’s nothing physical. So I created a focus for the defenders. Attacking would have the attacker place a flag, which the defenders would need to break / take down. I eventually merged this into the Towny plugin. — @Zren – [from his blog][zren-blog]

It has since then been adapted over time to retain its core functionality, while it continues to provide server communities with a simple, yet fast and effective, way to capture territory.

About mid-2020, an effort to split it back off from Towny began. FlagWar was finally fully split off in 2021, marking its 10th anniversary.

Sections

1. [Licensing 📜][licensing]
2. [Administrator Resources 👨‍💻][admin-resources]
   • [Supported Releases 📦][supported-releases]
   • [Staying up to Date 📨][staying-updated]
   • [Getting Support ⚕][get-support]
3. [Developer Resources 🧰][developer-resources]
   • [Contributing Code 💻][contrib-code]
   • [Contributing Documentation 🗒][contrib-docs] - WIP
   • [Localizing FlagWar 🗺][contrib-localize] - WIP
   • [Building FlagWar 🏗][building]
4. [Supporting the Project 🦸][supporting-flagwar]

Licensing

<img alt="OSI Approved License" style="float: right;" height="155" src="https://i0.wp.com/opensource.org/wp-content/uploads/2009/06/OSIApproved_100X125.png?resize=100%2C125&ssl=1">

FlagWar is licensed under the [Apache License, Version 2.0][apache-v2], a license approved by the [Open Source Initiative][osi] and is [GPL Compatible][gpl-apache]. Some portions, such as shaded libraries, may be alternatively licensed. See the [NOTICE][notice] for any alternative licensing or copyright limitations.

Documentation found on the [FlagWar Wiki][wiki] is licensed under [CC BY 4.0][cc by].

Additionally, please respect [Towny's license][cc by-nc-nd 3.0] when using FlagWar with Towny. Use of FlagWar does not constitute a way to bypass Towny's license restrictions. When in doubt, [ask for clarification][get-support].

Administrator Resources

Supported Releases

| FlagWar Release | 📅 Released On | Requirements | |:---------------:|:----------------:|:---------------------------------------------------------------------------------:| | v0.5.3 | October 20, 2022 | Towny (0.97.3.0+), Bukkit API-based* server (1.17.1, 1.18.2, 1.19.2) | | v0.5.2 | October 27, 2021 | Towny (0.97.3.0+), Bukkit API-based* server (1.16.5, 1.17.1) | | v0.5.1 | August 12, 2021 | Towny (0.97.2.0 - 0.97.2.14), Bukkit API-based* server (1.16.5, 1.17.1) | | Pre-History | 2011 - 2021 | Deprecated & Removed in Towny versions 0.97.0.0 and 0.97.1.0, respectively. |

FlagWar has adopted the use of Paper as an API provider. Spigot should however still be viable. Please submit a ticket if you experience any issues.

Staying up to Date

<img alt="Staying Up to Date: Github: click Watch, click Releases Only" style="float: right;" src="https://user-images.githubusercontent.com/879756/65964779-3a067200-e423-11e9-9928-938b976af2c2.gif" height="155">

All Release builds and most Development builds have been made available here on GitHub's [Releases][releases] page.
We encourage server admins to "watch" FlagWar on GitHub in order to receive update notifications.
Just click the watch button in the upper right and select "Releases Only".

Sometimes, releases can be incubating for extended periods of time.
You can build from main if you want to test on the bleeding edge.

Getting Support

The documentation found on the [FlagWar Wiki][wiki] will be updated semi-regularly, usually after a tagged release. If you find the documentation insufficient, please open an issue so that we can address it.

On the [Issue Tracker][issue-tracker] you can file [bug reports][bug], [feature requests][feature], or review / submit a [QA discussion][discuss-towny] on the Towny discussion board.

[![Average Issue Resolution Time][iim-time-badge]][iim-time] [![Percentage of Issues 'Open'][iim-percent-badge]][iim-percent]

If you still need help, come and join us on the [TownyAdvanced Discord server][discord]. There, you can also find support, get notified on the latest updates for Towny, chat with other admins, and have discussions over plugin development with developers from multiple projects.

Developer Resources

Contributing Code

If you would like to contribute to the FlagWar code, first please read the [Contributing Guidelines][contributing].

You will also want to ensure that your working environment is in order. You can check out [Environment Setup][env-setup] over on our wiki to help you get started.

Contributing Documentation

Documentation could also use a fair bit of work. Help in this department would be much appreciated.

We document both in plain-text (LICENSE, NOTICE) and in GitHub-Flavored Markdown (everywhere else).

If you are interested in writing for the [FlagWar Wiki][wiki], feel free to ask on the [Towny Discord][discord] (please use the #flagwar channel), or chime in on the [Towny Discussion Board][discuss-towny] to be given write access.

Localizing FlagWar

The localization files for FlagWar are built directly into the jar using ResourceBundles.

To localize FlagWar to your language, copy the Translation_en_US.properties file from the resources directory as Translation_{LOCALE}.properties.

If a locale already exists, please refrain from creating a duplicate. Some locales may be stubs that were added for debugging purposes (en_GB, en_US[-_]POSIX, es_MX.) Feel free to modify them, but ensure they have the same key values as the master file (en_US).

The LOCALE, or the locale id compatible with the Java Locale class, is a 1-to-3 segment string representing the language, the region, and the variant (if desired); delimited primarily by underscores, with variants optionally being hyphenated.

Examples: en, en_US, en_US-POSIX.

See the Java Locale documentation for well-formed naming.

* FlagWar's Locale IDs should stick to the lang(_REGION([_\-]VARIANT)) format.
PRs to Locale processing are welcome. It's pretty messy in there...

After translation is complete, save your changes. You will need to Build FlagWar to ensure that all strings are accounted for, and that they render properly for end users.

Building FlagWar

Assuming you've got your [environment properly set up][env-setup], building FlagWar is relatively straight forward.

Steps:

1. Clone FlagWar from GitHub.
   • See the [GitHub Docs][github-docs], if you are unfamiliar with cloning projects.
2. Navigate into the cloned FlagWar directory in your terminal.
3. Run mvn clean package to build FlagWar. This will generate files to the FlagWar/target/ directory.
   • We also supply several maven profiles for convenience. Append -P profileX,profileY,profileZ to use them, obviously replacing the ridiculous placeholder profiles listed here.
   • The checkstyle profile will ensure that code edits are in-line with the code style guidelines.
   • The javadocs profile will generate a FlagWar-version-javadoc.jar file, as well as the FlagWar/target/apidocs/ folder.

You can alternatively build FlagWar through your IDE, provided that it includes Maven, or that it can at least find it. Check your IDE's documentation regarding Maven support.

Supporting the Project

If you've found FlagWar to be of use and would like to support the project,