Full Configuration Reference
This page documents all shipped configuration keys with a description and a concrete example.
config.yml
factions.*
| Key | Description | Example |
|---|---|---|
factions.max-members | Maximum members per faction. | max-members: 50 |
factions.max-warps | Maximum warps allowed per faction. | max-warps: 10 |
factions.max-allies | Maximum ally relations per faction. | max-allies: 5 |
factions.max-truces | Maximum truce relations per faction. | max-truces: 5 |
factions.invites.ttl-hours | Invite expiration window (hours). | invites: { ttl-hours: 72 } |
factions.power.*
| Key | Description | Example |
|---|---|---|
factions.power.per-player-max | Maximum power a player can hold. | per-player-max: 10.0 |
factions.power.regen-per-second | Base power regen speed used by regen defaults. | regen-per-second: 0.1 |
factions.power.regen-online | Power gained each power tick while online. | regen-online: 6.0 |
factions.power.regen-offline | Power gained each power tick while offline. | regen-offline: 3.0 |
factions.power.loss-on-death | Power removed on death in relevant contexts. | loss-on-death: 4.0 |
factions.power.grace-period-seconds | Startup grace window before power-loss logic. | grace-period-seconds: 3600 |
factions.power.tick-interval-seconds | Interval for periodic power engine updates. | tick-interval-seconds: 60 |
factions.power.gain-on-kill.enabled | Whether killing an enemy player grants power to the killer. | enabled: true |
factions.power.gain-on-kill.amount | Power awarded to the killer per player kill. | amount: 2.0 |
factions.power.buy.enabled | Opt-in: allow players to purchase personal power via /f power buy. Requires Vault. | enabled: false |
factions.power.buy.cost-per-point | Money charged per 1 unit of power purchased. | cost-per-point: 100.0 |
factions.power.buy.max-per-purchase | Maximum power a player can buy in a single command. | max-per-purchase: 5.0 |
factions.power.sources.regen-online.enabled | Enable/disable online regen as a power source. | enabled: true |
factions.power.sources.regen-online.amount | Amount applied by online regen source each tick cycle. | amount: 6.0 |
factions.power.sources.regen-offline.enabled | Enable/disable offline regen as a power source. | enabled: true |
factions.power.sources.regen-offline.amount | Amount applied by offline regen source each tick cycle. | amount: 3.0 |
factions.power.sources.death-loss.enabled | Enable/disable death-loss source. | enabled: true |
factions.power.sources.death-loss.amount | Base amount removed by death-loss source. | amount: 4.0 |
factions.power.sources.kill-gain.enabled | Enable/disable kill-gain source. | enabled: true |
factions.power.sources.kill-gain.amount | Base amount added by kill-gain source. | amount: 2.0 |
factions.power.sources.buy.enabled | Enable/disable buy source (in addition to power.buy.enabled). | enabled: true |
factions.power.constraints.min-power | Hard lower bound for player power. | min-power: 0.0 |
factions.power.constraints.max-power | Hard upper bound for player power. | max-power: 10.0 |
factions.power.constraints.max-change-per-event | Clamp absolute power change per event (0 disables). | max-change-per-event: 0.0 |
factions.power.multipliers.worlds.<world> | World-specific multiplier for death/kill source adjustments. | worlds: { world_nether: 1.25 } |
factions.power.multipliers.zones.safezone | Safe zone multiplier for death/kill source adjustments. | safezone: 1.0 |
factions.power.multipliers.zones.warzone | War zone multiplier for death/kill source adjustments. | warzone: 1.0 |
factions.power.multipliers.zones.own_claimed | Own-claimed territory multiplier for death/kill source adjustments. | own_claimed: 1.0 |
factions.power.multipliers.zones.enemy_claimed | Enemy-claimed territory multiplier for death/kill source adjustments. | enemy_claimed: 1.0 |
factions.power.multipliers.zones.wilderness | Wilderness multiplier for death/kill source adjustments. | wilderness: 1.0 |
factions.power.freeze.blocks-automatic | Block non-admin automatic sources while player is frozen. | blocks-automatic: true |
factions.power.freeze.blocks-regen | Block regen sources while player is frozen. | blocks-regen: true |
factions.power.freeze.allow-admin-bypass | Allow admin power commands to bypass freeze. | allow-admin-bypass: true |
factions.power.notifications.actor | Send actor/target-facing power update messages. | actor: true |
factions.power.notifications.faction | Broadcast power updates to faction members. | faction: false |
factions.power.notifications.staff | Broadcast power updates to staff channel. | staff: false |
factions.land.*
| Key | Description | Example |
|---|---|---|
factions.land.buffer-zone | Enemy territory buffer in chunks (0 disables). | buffer-zone: 0 |
factions.land.max-per-command | Cap for multi-claim/unclaim modes (fill/square/circle). | max-per-command: 200 |
factions.land.per-power | Land-per-power ratio for claim capacity. | per-power: 1.0 |
factions.land.max | Absolute hard cap on faction land claims. | max: 500 |
factions.map.*
| Key | Description | Example |
|---|---|---|
factions.map.once-radius | Radius used by /f map once. | once-radius: 2 |
factions.list.* and factions.top.*
| Key | Description | Example |
|---|---|---|
factions.list.page-size | Entries per page for /f list. | list: { page-size: 8 } |
factions.top.page-size | Entries per page for /f top. | top: { page-size: 8 } |
factions.economy.*
| Key | Description | Example |
|---|---|---|
factions.economy.enabled | Master toggle for faction economy logic. | enabled: true |
factions.economy.cost-create | Cost to create a faction. | cost-create: 50.0 |
factions.economy.cost-claim | Cost per claimed chunk. | cost-claim: 100.0 |
factions.economy.tax.enabled | Enables periodic tax processing. | tax: { enabled: false } |
factions.economy.tax.rate | Fraction charged each tax cycle. | tax: { rate: 0.05 } |
factions.economy.tax.interval-hours | Hours between tax cycles. | tax: { interval-hours: 24 } |
factions.economy.tax.min-bank-balance | Skip tax below this bank balance. | tax: { min-bank-balance: 0.0 } |
factions.economy.tax.min-charge-amount | Skip tiny deductions below this amount. | tax: { min-charge-amount: 0.01 } |
factions.economy.tax.notify-members | Notify online members when tax is charged. | tax: { notify-members: true } |
factions.economy.bank.history.page-size | Entries per page for /f bank history. | bank: { history: { page-size: 8 } } |
factions.warp.*
| Key | Description | Example |
|---|---|---|
factions.warp.list.page-size | Entries per page for /f warp list. | warp: { list: { page-size: 8 } } |
factions.audit.*
| Key | Description | Example |
|---|---|---|
factions.audit.page-size | Entries per page for /f audit and /fa audit. | audit: { page-size: 10 } |
roles.yml (roles.*)
| Key | Description | Example |
|---|---|---|
roles.overrides.enabled (roles.yml) | Global toggle for per-faction role overrides. | roles: { overrides: { enabled: false } } |
roles.custom.enabled (roles.yml) | Enable custom role CRUD through /f role .... | roles: { custom: { enabled: true } } |
roles.custom.min-priority (roles.yml) | Minimum allowed priority for custom roles. | roles: { custom: { min-priority: 11 } } |
roles.custom.max-priority (roles.yml) | Maximum allowed priority for custom roles. | roles: { custom: { max-priority: 99 } } |
roles.custom.max-per-faction (roles.yml) | Maximum custom roles per faction (0 = unlimited). | roles: { custom: { max-per-faction: 8 } } |
roles.prefix.enabled (roles.yml) | Allow role prefix editing in /f role setprefix. | roles: { prefix: { enabled: true } } |
roles.prefix.max-length (roles.yml) | Maximum role prefix length (0 = unlimited). | roles: { prefix: { max-length: 32 } } |
roles.defaults.owner.prefix (roles.yml) | Default Owner prefix used when a faction is created. | roles: { defaults: { owner: { prefix: "<gold>[Owner]</gold>" } } } |
roles.defaults.officer.prefix (roles.yml) | Default Officer prefix used when a faction is created. | roles: { defaults: { officer: { prefix: "<yellow>[Officer]</yellow>" } } } |
roles.defaults.member.prefix (roles.yml) | Default Member prefix used when a faction is created. | roles: { defaults: { member: { prefix: "" } } } |
factions.fly.*
| Key | Description | Example |
|---|---|---|
factions.fly.enabled | Master toggle for faction fly feature. | enabled: true |
factions.fly.disable-on-threat | Disable fly when threat logic triggers. | disable-on-threat: true |
factions.fly.require-own-territory | Restrict fly to own territory. | require-own-territory: true |
factions.flags.*
Each built-in flag has two keys: default (boolean) and player-editable (boolean).
| Key | Description | Example |
|---|---|---|
factions.flags.pvp.default | Default value for the pvp flag (allow PvP in territory). | default: true |
factions.flags.pvp.player-editable | Whether officers may toggle the pvp flag in-game. | player-editable: true |
factions.flags.friendly-fire.default | Default for the friendly-fire flag. | default: false |
factions.flags.friendly-fire.player-editable | Whether officers may toggle friendly-fire. | player-editable: true |
factions.flags.explosions.default | Default for the explosions flag. | default: false |
factions.flags.explosions.player-editable | Whether officers may toggle explosions. | player-editable: true |
factions.flags.fire-spread.default | Default for the fire-spread flag. | default: false |
factions.flags.fire-spread.player-editable | Whether officers may toggle fire-spread. | player-editable: true |
factions.flags.open.default | Default for the open flag (open join without invite). | default: false |
factions.flags.open.player-editable | Whether officers may toggle open. | player-editable: true |
factions.chat.*
| Key | Description | Example |
|---|---|---|
factions.chat.show-tag | Show faction tag in chat formatting. | show-tag: true |
factions.chat.tag-format | MiniMessage format for faction chat tag. | tag-format: "<gray>[<gold>{faction_name}</gold>]</gray> " |
factions.metrics.*
| Key | Description | Example |
|---|---|---|
factions.metrics.bstats.enabled | Enable anonymous bStats metrics collection. | bstats: { enabled: true } |
factions.updates.*
| Key | Description | Example |
|---|---|---|
factions.updates.enabled | Check for new plugin versions on startup (opt-in, disabled by default). | enabled: false |
factions.updates.notify-ops-on-join | Notify online operators about available updates when they join. | notify-ops-on-join: false |
factions.language.*
| Key | Description | Example |
|---|---|---|
factions.language.default | Server-wide default locale code used when no player locale is set. Falls back to en if the specified locale bundle is absent. | default: en |
factions.merge.*
| Key | Description | Example |
|---|---|---|
factions.merge.enabled | Enable the /f merge send and /f merge accept commands. Off by default — turn on to allow factions to absorb one another. | enabled: false |
integrations.*
| Key | Description | Example |
|---|---|---|
integrations.vault | Enable Vault integration attempt. | vault: true |
integrations.worldguard | Enable WorldGuard integration attempt. | worldguard: true |
integrations.worldguard-sync-regions | Mirror faction claims as WG ProtectedCuboidRegions for native build protection (no per-event DB query for denied players). Requires WorldGuard. Restart required when toggling. | worldguard-sync-regions: false |
integrations.dynmap | Enable dynmap integration attempt. | dynmap: true |
integrations.placeholderapi | Enable PlaceholderAPI integration attempt. | placeholderapi: true |
integrations.essentialsx.enabled | Enable EssentialsX teleport routing for /f home and /f warp. Jailed players are blocked. Requires EssentialsX 2.19+. | essentialsx: { enabled: false } |
integrations.lwc.enabled | Master toggle for LWC/LWCX interop. | lwc: { enabled: true } |
integrations.lwc.require-build-rights-to-create | Block protection creation if builder lacks rights. | lwc: { require-build-rights-to-create: true } |
integrations.lwc.remove-if-no-build-rights | Remove stale protections when owner loses rights. | lwc: { remove-if-no-build-rights: true } |
integrations.lwc.remove-on-claim-change | Remove alien protections after claim changes. | lwc: { remove-on-claim-change: true } |
database.yml
| Key | Description | Example |
|---|---|---|
type | Backend type (h2 or mysql). | type: h2 |
h2.file | Relative file path for embedded H2 database. | h2: { file: data/factions } |
mysql.host | MySQL/MariaDB host. | mysql: { host: localhost } |
mysql.port | MySQL/MariaDB port. | mysql: { port: 3306 } |
mysql.database | Database/schema name. | mysql: { database: factions } |
mysql.username | Database username. | mysql: { username: root } |
mysql.password | Database password. | mysql: { password: "" } |
mysql.pool-size | Hikari pool size for mysql backend. | mysql: { pool-size: 10 } |
debug.jaloquent-logging | Enable SQL logging for debugging. | debug: { jaloquent-logging: false } |
gui.yml
Root keys
| Key | Description | Example |
|---|---|---|
gui.enabled | Master toggle for GUI system. | enabled: true |
gui.default-menu | Menu id opened by /f (no args). | default-menu: main |
gui.menus | Menu map container. | menus: { main: ... } |
Menu-level keys (gui.menus.<id>.*)
| Key | Description | Example |
|---|---|---|
title | Inventory title (MiniMessage). | title: "<gold><bold>Factions</bold></gold>" |
size | Inventory slot size (9..54, rounded by implementation). | size: 54 |
items | Item definitions map. | items: { info: ... } |
Item keys (gui.menus.<id>.items.<itemId>.*)
| Key | Description | Example |
|---|---|---|
slot | Inventory slot index. | slot: 10 |
material | Bukkit material name. | material: BOOK |
name | Display name (MiniMessage + placeholders). | name: "<gold>Your Faction</gold>" |
lore | Lore lines list. | lore: ["<gray>Faction: <white>{faction}</white>"] |
glow | Enables glint visual. | glow: true |
action | Click action type (RUN_COMMAND, SUGGEST_COMMAND, OPEN_MENU, REFRESH, CLOSE). | action: RUN_COMMAND |
command | Command used by RUN_COMMAND / SUGGEST_COMMAND. | command: "/f info" |
menu | Target menu id for OPEN_MENU. | menu: "main" |
messages.yml
messages.yml is fully key-based localization config.
How to treat message keys
- Every key path is a translatable text entry.
- Values support MiniMessage formatting.
- Placeholders like
{player},{faction},{amount},{usage}must be preserved.
Current top-level groups
| Group | Purpose | Example key |
|---|---|---|
prefix | Global plugin prefix line | prefix |
general | Generic errors/system text | general.no-permission |
help | Help screen copy | help.title |
faction | Faction lifecycle messages | faction.created |
member | Member/rank flow messages | member.kicked |
invite | Invite lifecycle and prompts | invite.summary |
claim | Claim/unclaim and territory text | claim.claimed |
bank | Bank operations and tax notices | bank.balance |
home | Home set/teleport messages | home.set, home.teleported, home.jailed |
warp | Warp flow messages | warp.set, warp.teleported, warp.jailed |
relation | Relation messages | relation.set |
power | Power model messages | power.too-low-raid, power.lost-on-death, power.kill-gained, power.buy-success |
fly | Fly state messages | fly.enabled |
lwc | LWC integration notices | lwc.stale-protection-removed |
info | Faction info formatting | info.header |
admin | Admin-facing messages | admin.reload |
Message key example
invite:
summary: "<gold>You have <white>{count}</white> pending faction invite(s):"
Description:
invite.summaryis sent during invite listing and login summary notifications.