Factions Documentation

Overview

• One jar for Paper and Folia. It only uses the region, entity, global and async schedulers and never the old Bukkit scheduler.
• Every option editable in-game — through a GUI, or from the console with tab completion and validation.
• Four databases, with a built-in SQLite → MySQL/PostgreSQL migration and a FactionsUUID / SaberFactions importer.
• Cross-server sync over Redis for factions, members, claims, banks, chat and alerts.
• Small jar (~380 KB). Paper downloads the database drivers, HikariCP and Jedis from Maven Central on first start.

Requirements

• Paper 26.3 (the plugin declares api-version: '26.3' and folia-supported: true)
• Java 25
• Optional: Vault (economy), PlaceholderAPI, WorldGuard
• For cross-server sync: a shared MySQL, MariaDB or PostgreSQL database and a Redis server

Installation

1. Put Factions-1.0.0.jar in the plugins/ folder.
2. Start the server. On first start Paper downloads the libraries the plugin needs, so the server needs access to Maven Central (through Paper's mirror).
3. The default storage is SQLite (plugins/Factions/factions.db) — nothing to set up. To use a server database, see Databases.
4. Open /f admin config in-game to go through the settings.

How It Is Built

• Memory first. Faction, member and claim data lives in memory in thread-safe collections. Protection checks never touch the database.
• No race conditions on Folia. Any change to claims, membership, names or relations is checked a second time and applied under a single lock. A chunk can't end up with two owners, a player can't join two factions, and claims can't exceed power, even when region threads act at the same time.
• Delayed batched saves. Changes are written in one transaction every general.save-interval-seconds. A failed save is retried at the next interval. Shutdown saves everything before stopping.
• Banks can't be duplicated. The money and TNT banks update balances in the database with a single conditional statement. Two withdrawals at the same moment, even from different servers, can't overdraw a bank. Items or money are taken from the player first and given back if the deposit fails.
• Teleports are async. Homes and warps use teleportAsync.

Tested behaviour

The test suite runs the real services on a temporary SQLite database and covers:

• claim limits and overclaiming
• many threads claiming one chunk
• many members claiming past their power at once
• many players creating the same faction name at once
• ranks and attempts to grant yourself extra permissions
• relations and ally limits
• data surviving a restart
• concurrent bank withdrawals
• config validation
• SQL for each database type

Features

In-game Configuration

• /f admin config opens a GUI with every option grouped by category. Left/right/shift-click changes numbers, toggles and choices. Text and list options are typed in chat. Press Q to reset an option to its default.
• /f admin config set <path> <value> sets an option from the console, with tab completion and validation.
• /f admin lang <key> <minimessage> changes a message and shows a preview.

Changes take effect immediately. Options marked requires restart (database, Redis, command aliases) take effect after a restart.

Configuration

The most important keys and their defaults. Every key can be changed with /f admin config; the full list is in the GUI.

General

Factions and relations

Power and claims

Raiding

Teleport and fly

Economy (Vault)

All costs (economy.cost.create, claim, home, sethome, warp, setwarp, rename, join) default to 0. economy.refund.unclaim sets the refund per unclaimed chunk. The faction bank is on by default (economy.bank.enabled) and is paid to the leader on disband.

Databases

Set storage.type to SQLITE (the default), MYSQL, MARIADB or POSTGRESQL, then fill in storage.host, port, database, username and password. All tables use storage.table-prefix (default factions_). SQLite is backed up every 60 minutes and the last 24 backups are kept.

Moving from SQLite to a server database

1. Change storage.* in the config and restart.
2. Run /f admin migrate sqlite factions.db.

Importing from FactionsUUID or SaberFactions

Put their data/*.json files into plugins/Factions/data/ and run /f admin import factionsuuid confirm. This replaces all current faction data.

Cross-server Sync (Redis)

1. Use the same MySQL/MariaDB/PostgreSQL database on every server.
2. Set sync.enabled: true and sync.redis-uri (default redis://localhost:6379).
3. Give each server a unique general.server-name.
4. World names must be unique across servers, because claims are stored by world name.

Factions, members, claims, banks, chat and alerts are synced. Faction names are reserved in Redis so two servers can't create the same name. If two servers edit the same faction at the same moment, the newer version wins.

Commands

The base command is /f (aliases: /faction, /fac, configurable).

Player commands

help, create, disband, rename, desc, motd, open, show, list, top, power, near, map, seechunk, gui, invite, deinvite, join, leave, kick, promote, demote, setrank, leader, rank, claim, unclaim, autoclaim, ally, truce, neutral, enemy, relations, home, sethome, delhome, warp, setwarp, delwarp, chat, fly, perms, logs, shield, tnt, bank, strikes

Admin commands

/f admin <bypass|chatspy|reload|save|config|lang|disband|join|kick|setleader|setpower|boost|strike|safezone|warzone|unclaim|inspect|value|import|migrate|logs>

Permissions

PlaceholderAPI

Player placeholders, used as %factions_<name>%:

name, name_colored, description, motd, leader, rank, power, maxpower, player_power, player_maxpower, land, land_max, members, online, bank, tnt, value, top_rank, strikes, strikes_max, raidable, shield, open, allies, enemies, truces, has_faction, chat_mode, territory, territory_colored

Relational placeholders: %rel_factions_relation%, %rel_factions_relation_color%, %rel_factions_name%.

Developer API

The factions-api module holds the public interfaces. Get the instance with FactionsApi.get().

Events: create, disband, rename, join, leave, claim, unclaim, relation change, power loss.

Getting a Build

Factions is not released. Ask for a build in the Discord server, and tell us your server software, version and Java version. See Projects for the other plugins on the bench.