Two factions' territory, claimed in game with Medieval Factions 7.0.0 on a local Paper 1.21.11 test server (seed 8675309), then exported from the world folder and Medieval Factions' JSON storage with Minecraft-USD-Exporter and rendered in Blender. Below it, the real /f map output for the same claims, drawn as Minecraft-style chat (it was received by a scripted bot client).
Medieval Factions is a system of mechanics that allows for the simulation of sovereign nations in Minecraft. Players can create nations, claim territory, engage in warfare or politics, write laws or hold dueling tournaments, and generally are able to attempt to recreate society somewhat.
A list of features can be found here.
The development of the fifth major version of MF was led by alyphen (creator of RPKit). Huge thanks to her!
- You can download the plugin from this page.
- Once downloaded, place the jar in the plugins folder of your server files.
- Restart your server.
- (Optional) Configure your preferred storage backend in
config.yml(database or JSON).
Medieval Factions is supported on the Minecraft versions listed in minecraft-versions.json: currently 1.19.4, 1.21.11, 26.2 and 26.3 (Spigot and its forks). Every stable release is booted on a real server of each of these versions before it is published, and every build checks that the plugin only uses Bukkit API that exists on all of them (API-compatibility check). Other versions from 1.19.4 onwards are expected to work but are not tested. To support another version, add it to the file: both checks pick it up.
If you run 5.8.x, please upgrade. Medieval Factions 5.8.x does not close its embedded H2 database cleanly when the server stops. Each restart can leave medieval_factions_db.mv.db a little more damaged, until the plugin no longer loads with MVStoreException: Unable to read the page (#1975). Servers that restart often, such as hosts that stop empty servers, hit this sooner. From 6.0.0 onward, Medieval Factions closes the database explicitly on shutdown.
- Stop the server and back up
plugins/MedievalFactions/(in particularmedieval_factions_db.mv.db). - Replace the jar with the latest release and start the server.
Before each release, the release gates checked that it loads data written by the previous one: 6.0.0 loads 5.8.1 data, 6.1.0 loads 6.0.0 data, and 7.0.0 loads 6.1.0 data, on both the H2 and JSON backends. A direct jump from 5.8.1 to 7.0.0 has not been gated, which is one more reason to keep the backup. If the plugin already fails with the error above, keep a copy of the damaged file before removing anything. It can sometimes be recovered; ask in #1975 or on Discord.
Medieval Factions 5.0 was a full rewrite, and 4.x servers are still out there. Version 4.x sends no bStats data, so they don't show up in usage numbers. The current release still includes the 4.x data migrator. On first start it finds the 4.x data, copies it to plugins/MedievalFactions/mf4_backup/, writes the new config and stops the server. Configure the database if you use one (MariaDB and MySQL take a jdbc:mariadb:// URL; see CONFIG.md), then start again and the 4.x factions, claims, power, locks and gates are imported. The steps are also on the wiki.
Try it on a copy first. The release gates check upgrades between 5.x and later versions, not from 4.x, so this path is not tested before each release. Back up the whole server, run the upgrade on a copy, check /f list, /f info and a few claims, and only then upgrade the live server. Please report problems in a GitHub issue.
Medieval Factions supports two data storage backends:
- Database Storage (default) - Uses embedded H2, or a MariaDB/MySQL server
- JSON Storage - Stores data in JSON files for simpler setups
See Configuration Guide for details on choosing and configuring your storage backend.
- Dynmap: built in. Install Dynmap and claimed land appears on its map.
- BlueMap: install BlueMap together with the Bluemap_MedievalFactions add-on, and faction claims are drawn as overlays on the BlueMap web map.
Each of these add-ons requires Medieval Factions and adds something to it. The current stable release of every one was enabled against Medieval Factions 7.0.0 by the dependents gate before 7.0.0 was published.
| Expansion | What it adds | Verified with MF 7.0.0 |
|---|---|---|
| Currencies (SpigotMC) | Factions mint their own currencies, for local economies | v3.0.0 |
| Fiefs (SpigotMC) | Sub-factions (fiefs) inside a faction | v0.12.1 |
| Democracy (SpigotMC) | Elections for faction leadership | v0.3.0 |
| Bluemap_MedievalFactions | Faction claims on a BlueMap web map | v1.0 |
Currencies 2.x does not enable on Medieval Factions 5.8 or newer. Use Currencies 3.0.0 or later.
In game, operators can run /mf addons to see which of these, and of the plugins below, are installed, and whether each installed version is the verified one. See COMMANDS.md.
- Medieval Roleplay Engine (SpigotMC): character cards, local chat, emotes and messenger birds. It is a companion plugin for faction roleplay and runs alongside Medieval Factions.
- Mailboxes (SpigotMC): persistent messages. When it is installed, Medieval Factions delivers faction notifications through it.
- Medieval Economy (SpigotMC): a coinpurse and a physical currency item.
Every plugin is listed on dansplugins.com, and Dan's Plugin Manager can install them in game with /dpm get <plugin>.
- User Guide - Getting started and common scenarios
- FAQ - Answers to frequently asked questions
- Who can do what - What each kind of player can do in faction territory, observed by bots on every release
- Commands Reference - Complete list of all commands
- Configuration Guide - Detailed config options
- Faction Flags - Faction flag reference
- Database Querying Guide - How to query the database directly
- REST API Usage Guide - The opt-in HTTP API for integrating other plugins and tools
You can find the support discord server here.
Please fill out a bug report here.
To run the unit tests, you can use the following command:
Linux:
./gradlew clean testWindows:
.\gradlew.bat clean testIf you see BUILD SUCCESSFUL, then the tests have passed.
I recommend using FactionsBridge by Retrix_Solutions. It would make your add-on plugin usable across a number of factions implementations.
To build directly on Medieval Factions, the expansions above are working examples. Their source shows how each one hooks into Medieval Factions' services, events and permissions. A clearer API for expansion permissions is tracked in #1683.
For development purposes, a Docker-based test server is available with integrated plugin hot-reloading capabilities using ServerUtils (a modern Plugman alternative).
- Copy
sample.envto.envand configure as needed - Build the plugin:
./gradlew build - Start the test server:
./up.sh
After making changes to the plugin code, you can quickly reload it without restarting the server:
Option 1: Using the reload script (recommended)
./reload-plugin.shOption 2: Manual reload
- Build the plugin:
./gradlew build - Copy the new jar to the running container
- Use ServerUtils commands in-game or console:
/serverutils reload MedievalFactions- Reload the plugin/serverutils unload MedievalFactions- Unload the plugin/serverutils load MedievalFactions- Load the plugin/serverutils list- List all plugins
This significantly speeds up the development cycle by eliminating the need for full server restarts during testing.
./down.sh| Name | Main Contributions |
|---|---|
| Daniel Stephenson | Original creator |
| Ren Binden | Created Medieval Faction 5 |
| Pasarus | Overhauled the Storage Manager to use UUIDs and JSON and made other improvements to the plugin |
| Caibinus | Implemented Duels, Gates and Dynmap Integration |
| Callum | Created event classes, overhauled the Command System, implemented PlaceholderAPI integration and made many other improvements to the plugin |
| Richardhyy | Fixed some encoding issues |
| Mitras2 | Implemented ActionBar territory alerts |
| Kaonami | Fixed a typo in the README |
| GoodLucky777 | Fixed a bug and a few typos in the code |
| Elafir | Made it possible to control gates with redstone |
| Deej | Added checks to several commands |
| VoChiDanh | Refactored parts the PersistentData class in an attempt to resolve java compatibility issues |
| Kyrenic | Implemented contiguous claims config option |
| Tems | Fixed claim protection issues |
| MestreWilll | Contributed Brazilian Portueguese translation |
| Name | Language(s) |
|---|---|
| Khanter | Spanish |
| Neh | Spanish |
| Johnny | Spanish |
| lilhamoood | Spanish |
| 1barab1 | Russian |
| 2kManfridi | Russian |
| Kaonami | Portuguese Brazilian |
| graffity_X | German |
| JustGllenn | Dutch |
| TDL | Dutch |
| n0virus | Dutch |
| MestreWilll | Brazilian Portuguese |
I created this plugin because I wanted to use the original Factions plugin for an upcoming server of mine, but it wasn't updated for the version of minecraft I was going to be using. I decided to take inspiration from the concept of factions - groups of players that can claim land - and create my own factions plugin.
The first release version, v1.7, was released on SpigotMC in June 2020 and looked much different than the plugin does today.
I am extremely grateful to those that have donated their time improving the project, one way or another. The plugin wouldn't be where it is today without the contributions of others.
This project is licensed under the GNU General Public License v3.0 (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 file for the full text of the GPL-3.0 license.
This project is in active development.
You can view the bStats page for the plugin here.
Usage reporting is on by default: when the plugin is enabled, and each time one of its commands is used, it sends its name, version and the command's name (startup and command events; aliases such as /mf report under the command's declared name) to https://trace.danielstephenson.dev so it is known which plugins are actually in use. Nothing about players, worlds or IPs is sent, and nothing typed after a command. The plugin says on every startup whether reporting is on. Each event also carries a random server ID (the server-id line in plugins/trace/config.yml) so
servers can be counted rather than events. It identifies no person, account or IP address; delete
the line to get a new one.
To turn it off:
usage-reporting.enabled: falsein this plugin'sconfig.yml- for every plugin on the server that reports to trace:
enabled: falseinplugins/trace/config.yml(written by the first such plugin to start) - the environment variable
TRACE_USAGE_REPORTING=offorDO_NOT_TRACK=1
Details: https://danielstephenson.dev/usage-reporting
Once per startup, off the main thread, the plugin asks GitHub for the latest published Medieval Factions release: one unauthenticated GET https://api.github.com/repos/Dans-Plugins/Medieval-Factions/releases/latest, which returns the release's tag and link. If that release is newer than the version the server runs, one line goes to the console, and players with the mf.updatenotice permission (ops by default) see it when they join. The line names the new version, links the release, and gives a reason: a server on a version before 6.0.0 is told that the release fixes database corruption on shutdown (H2); otherwise it points at the release notes. Development builds such as 7.0.1-SNAPSHOT are never told to "upgrade" to an older release, and pre-releases are never offered.
Nothing about the server or its players is sent (the request carries only a User-Agent naming the plugin and its version, which GitHub requires), and nothing is downloaded or installed. A failed check (offline, timeout, rate limit) is silent and never delays startup.
The check is on by default. To turn it off:
update-check.enabled: falsein this plugin'sconfig.yml- the environment variable
TRACE_USAGE_REPORTING=offorDO_NOT_TRACK=1, the same switches that turn off usage reporting