upgrades.yml
Defines each upgrade branch, icon, label, max level, and per-level cost and value. The plugin uses the levels.<level>.value path as the real effect source.
Main Config: config.yml
This is the global server behavior file. It controls storage, PvP, economy, relations, scoreboard, RabbitMQ, and most faction gameplay modules.
| Path | Meaning | How To Use It |
|---|---|---|
language | Selects the active language bundle. | Use en or fr, or add your own file under lang/. |
mongodb.uri | Primary MongoDB connection string. | Use this when storage.type is MONGODB. URL-encode special password characters. |
mongodb.database | Mongo database name. | Keep all network servers on the same name if they should share the same faction database. |
mongodb.pool.* | Mongo connection pool settings. | Increase on larger networks, keep low on small servers. |
mongodb.socket.* | Connection and read timeout tuning. | Raise if the database is remote and slow, lower if you want faster failure detection. |
mongodb.host, port, username, password | Legacy fallback Mongo settings. | Only used if mongodb.uri is empty. |
storage.type | Selects SQLITE or MONGODB. | Use SQLite for single-server simplicity, MongoDB for external DB hosting or broader network persistence. |
storage.sqlite.file | SQLite database file path. | The clean default is data.db inside the plugin folder. |
pvp.member-pvp | Friendly fire within the same faction. | Set true only if your server wants internal sparring or no team protection. |
pvp.ally-pvp, truce-pvp, neutral-pvp, enemy-pvp | Relation-based PvP rules. | These define who can damage who based on current faction relation. |
pvp.peaceful-protection | Blocks PvP against peaceful factions. | Use on more casual or protection-heavy servers. |
pvp.check-grace | Blocks PvP while grace is active. | Leave on if grace should actually protect players instead of only being cosmetic. |
pvp.check-shield | Blocks PvP while shield is active. | Use with shield-protected factions for raid windows. |
claims.claim-cost | Money cost per chunk claim. | Requires Vault economy support. |
claims.refund-percentage | Money refunded on unclaim. | Set below 100 to discourage constant claim cycling. |
claims.must-be-connected | Requires claim chains to stay connected. | Use true for normal factions servers, false for looser administrative building. |
claims.allow-overclaim-negative-power | Allows taking land from raidable factions. | Keep true if you want standard overclaim-style raiding pressure. |
explosions.protect-claims | Global claim explosion protection. | Set false if TNT raiding should be possible. |
factions.min-tag-length to max-name-length | Faction tag and name length rules. | Use shorter tag limits for cleaner chat and map output. |
factions.creation-cost | Money cost to create a faction. | Requires Vault. |
factions.max-members | Base member cap before upgrades. | Upgrades can push the effective cap higher. |
factions.allow-peaceful | Whether peaceful factions exist at all. | Disable on full PvP networks. |
factions.peaceful-cost | Cost to become peaceful. | Useful if peaceful status is meant to be expensive and rare. |
factions.allow-rename | Whether renaming is allowed. | Disable if identity stability matters more than flexibility. |
factions.rename-cost | Vault cost to rename a faction. | Separate from tag-change point cost. |
factions.default-role | Role given to new members. | Usually keep as RECRUIT. |
factions.auto-disband-on-empty | Disbands a faction with no members. | Leave true unless you want ghost factions to persist. |
factions.tag-change-cost | Faction points required to change the faction tag. | Separate from money rename logic. |
factions.tag-change-cooldown | Cooldown in seconds between tag changes. | Use to stop abuse or impersonation churn. |
zones.enabled | Enable custom zone tagging inside claims. | Useful for safe zones, farms, storage areas, and war zones. |
zones.types | List of zone names. | Add your own logical labels if your server relies on chunk organization. |
zones.permissions.* | Behavior flags per zone type. | Define special behavior like disabling PvP or explosions inside a named zone. |
faction-chest.min-role | Minimum role allowed to open the faction chest. | Use RECRUIT if everyone can view, higher if chest is sensitive. |
faction-chest.write-role | Minimum role allowed to modify faction chest contents. | Prevents low-rank players from taking or moving shared items. |
faction-chest.upgrade-role | Minimum role allowed to upgrade chest size. | Usually COLEADER or LEADER. |
faction-chest.max-level | Maximum chest level. | Must match your slot and cost tables. |
faction-chest.slots-per-level.* | How many chest slots each level unlocks. | Keep increasing in multiples of 9 for clean inventory rows. |
faction-chest.upgrade-cost.* | Point cost per chest level. | These are faction point costs, not Vault money costs. |
grace.* | New-faction grace protection settings. | Controls grace duration, protection type, extension rules, and scoreboard visibility. |
shield.* | Shield system settings. | Controls cost, duration, cooldown, PvP/explosion blocking, and weekly limits. |
alt-system.* | Alt-account restrictions. | Control cap, power contribution, member counting, claim access, bank access, and required role to add alts. |
anti-spam.enabled | Master anti-spam switch. | Disable only if another plugin is doing all cooldown enforcement. |
anti-spam.max-commands-per-minute | General command-rate limiter. | Protects against command flooding. |
anti-spam.cooldown-message | Literal message shown on anti-spam rejection. | Change this if you want custom branding or simpler wording. |
anti-spam.cooldown.* | Per-command cooldown seconds. | Use higher values on expensive or spammy actions like stuck or fly. |
points.* | Faction point economy settings. | Controls starting points and how factions earn points from kills, claims, missions, daily logins, and top-faction bonuses. |
audit.enabled | Master audit switch. | Disable only if you do not want faction history at all. |
audit.max-entries | Maximum entries kept per faction. | Lower on small servers to save space, higher on serious competitive servers. |
audit.auto-cleanup | Whether old audit entries are removed automatically. | Normally keep true. |
audit.retention-days | Age cutoff for audit retention. | Use long retention if staff reviews history often. |
audit.log-types.* | Per-event audit toggles. | Lets you keep only the events your staff actually cares about. |
check-system.enabled | Master faction check scanner switch. | Disable if you do not want periodic defensive alerts. |
check-system.check-interval | How often checks run. | Lower values increase responsiveness but also processing frequency. |
check-system.check-radius | Chunk radius used for checks. | Increase for larger base warning coverage. |
check-system.alerts.* | Specific check categories. | Turn off noisy alerts individually. |
reserves.* | Name reservation system. | Controls whether reservations exist, how long they last, cost, and cleanup behavior. |
warps.max-warps | Base warp cap before upgrades. | Upgrades can extend the effective limit. |
warps.allow-passwords | Allow protected warps. | Useful for internal faction security. |
warps.warp-cooldown | Seconds before a player can warp again. | Use alongside combat lockouts. |
warps.cancel-on-damage, cancel-on-movement | Warmup cancellation rules. | Turn on for stricter raid travel risk. |
warps.warmup-time | Seconds before teleport fires. | Set to 0 for instant travel, or higher for vulnerable warmup windows. |
tnt-bank.* | TNT bank behavior. | Controls base capacity, dispenser withdrawal, and interest growth. |
relations.* | Diplomacy rules. | Controls caps, mutual requests, neutral availability, auto-enemy on attack, and chat-channel availability. |
fly.enabled | Master faction fly switch. | Disable here if you want no faction fly at all. |
fly.fly-...-territory | Fly eligibility by territory relation. | Defines whether own, ally, truce, wilderness, or enemy land allows faction fly. |
fly.disable-on-combat | Disables fly while tagged. | Keep true on PvP-heavy networks. |
fly.combat-tag-duration | Combat tag length. | Longer values punish unsafe disengage more. |
fly.disable-enemy-nearby | Blocks fly around hostile players. | Helps stop easy escape abuse. |
fly.enemy-detection-radius | Radius used for nearby enemy detection. | Balance this to your world scale. |
fly.auto-fly | Auto-enable faction fly on valid territory entry. | Useful for smoother movement on convenience-focused servers. |
fly.trails.* | Particle trail cosmetics. | Restrict the available list to particles that fit your server theme. |
economy.faction-bank | Master switch for faction bank usage. | Set false if your server only wants TNT/points and no money banking. |
economy.starting-balance | Faction starting money balance. | Usually kept low or zero on progression servers. |
economy.deposit-tax, withdrawal-tax | Bank transaction taxes. | Use these as economic sinks. |
economy.min-withdrawal, max-withdrawal | Withdrawal bounds. | Use to stop spam withdrawals or huge balance dumping. |
scoreboard.enabled | Master Modern Factions scoreboard switch. | If OreoEssentials scoreboard is active, Modern Factions can back off automatically at runtime. |
scoreboard.update-interval | Sidebar refresh interval in ticks. | Lower values feel more live but cost more updates. |
scoreboard.title | Sidebar title. | Supports color formatting. |
scoreboard.lines | Sidebar line template list. | Use faction and player placeholders, and keep enough uniqueness for scoreboard rendering. |
rabbitmq.enabled | Enables cross-server messaging. | Use true only when a working RabbitMQ broker is reachable. |
rabbitmq.server-id | Name of this backend server. | Must be unique across the network. Also used for cross-server travel targeting. |
rabbitmq.exchange | Fanout exchange name used by Modern Factions. | All Modern Factions servers in the same network must share this exact exchange. |
rabbitmq.rabbitmq.uri | AMQP connection URI. | Use amqp:// or amqps://. URL-encode special characters in passwords. |
Cross-server public chat note: if OreoEssentials already owns public cross-server chat, Modern Factions should be used for faction-private channels only. The current Modern Factions build is already set up to avoid publishing public RabbitMQ chat while OreoEssentials is installed.
power.yml
This file controls raidability, claim presentation, and reinforced block behavior.
| Path | Meaning | How To Use It |
|---|---|---|
power.mode | Chooses POWER or DTR. | Use POWER for classic power-based factions, DTR for HCF-style raidability. |
power.starting-power | Starting player/faction power basis. | Use 0 if you want factions to build up strength over time. |
power.max-power, min-power | Power floor and ceiling. | Set more negative minimums if you want long raidable punishment windows. |
power.power-per-death | Power lost on death. | Higher values make combat outcomes matter more. |
power.power-per-kill | Power earned per kill. | Use modest values to avoid snowballing too hard. |
power.regen-rate | Power restored per regen cycle. | Lower is harsher, higher is more forgiving. |
power.regen-interval-seconds | Seconds between regen cycles. | Use longer intervals on competitive servers. |
power.regen-only-online | Only regen while members are online. | Good for preventing offline passive recovery abuse. |
power.power-per-member | Faction power granted per member. | Drives scaling with roster size. |
power.power-per-claim | Power pressure per claim. | Higher values make oversized landholding harder. |
power.dtr.enabled | Enables DTR handling under DTR mode. | Keep aligned with power.mode. |
power.dtr.dtr-per-member | DTR contribution per member. | Controls how big factions scale their max DTR. |
power.dtr.max-dtr | Global DTR ceiling. | Use to prevent very large factions from becoming too safe. |
power.dtr.freeze-time | Seconds before DTR regen resumes after death. | Classic HCF pressure setting. |
power.dtr.regen-rate | DTR regained per regen cycle. | Lower values keep raidable windows open longer. |
claims.show-territory-titles | Show titles on territory entry. | Disable for cleaner HUDs. |
claims.title-fade-in, title-stay, title-fade-out | Title animation timings. | Tune to reduce spammy feel on dense claim borders. |
claims.territory-title | Title shown for owned faction territory. | Uses {faction}. |
claims.territory-subtitle-default | Default subtitle for claimed land. | Use for atmosphere or server instructions. |
claims.wilderness-title, wilderness-subtitle | Wilderness entry text. | Useful for PvP or build warnings. |
claims.show-territory-actionbar | Show actionbar on territory enter. | Good alternative to titles on minimal HUDs. |
claims.wilderness-actionbar | Actionbar for wilderness. | Use as a rules reminder. |
claims.play-territory-sound | Play sounds on territory changes. | Disable if frequent movement makes this noisy. |
claims.territory-sound, wilderness-sound | Sound names. | Use valid Bukkit sound ids. |
claims.sound-volume, sound-pitch | Sound tuning. | Lower volume if territory borders are dense. |
claims.must-be-connected | Connected claim requirement at the power.yml layer. | Keep in sync with your broader claim philosophy. |
claims.max-claim-radius | Maximum chunk distance from nearby owned land. | Prevents far-out isolated strip claiming. |
claims.allow-claiming-from-enemies | Whether enemy-owned land can be directly claimed. | Disable for stricter overclaim policy. |
claims.claim-cost | Alternative claim cost defined in power.yml. | Used by the current claim implementation. |
claims.unclaim-refund-percentage | Refund percentage defined in power.yml. | Used by the current unclaim implementation. |
block-protection.enabled | Master reinforced-block switch. | Disable if you want pure vanilla block durability. |
block-protection.health-multiplier | Base extra health multiplier for protected materials. | Higher values make raiding walls slower. |
block-protection.regeneration-delay-seconds | How long after damage blocks wait before regenerating health. | Longer delays reward sustained pressure. |
block-protection.regeneration-rate | How quickly protection health restores. | Lower is harsher on defenders. |
block-protection.show-health-bar | Whether damage feedback is shown. | Useful for making the mechanic readable to players. |
block-protection.protected-materials | Material whitelist for reinforced behavior. | Only blocks in this list get the protection-health system. |
block-protection.protection-levels.* | Relation-based damage multipliers. | Lets own, ally, neutral, and enemy territory feel different when breaking blocks. |
block-protection.raidable.reduce-protection | Weakens reinforced blocks while a faction is raidable. | Use true if raidable state should materially weaken bases. |
block-protection.raidable.protection-multiplier | Raidable-state protection scaling. | Lower values make raidable bases easier to break. |
chat.yml
This file controls the Modern Factions chat system itself, separate from public-chat plugins like OreoEssentials.
| Path | Meaning | How To Use It |
|---|---|---|
chat.enabled | Master faction chat system switch. | Set false if you want Modern Factions to stop intercepting chat entirely. |
chat.faction-chat, ally-chat, truce-chat, role-chat | Per-channel enable flags. | Disable channels your server does not want to expose. |
chat.format.public | Modern Factions public chat format. | If OreoEssentials owns public chat, this is mainly a fallback format. |
chat.format.faction | Faction-only chat format. | Visible only to faction members and chat spies. |
chat.format.ally | Ally chat format. | Change this to alter the ally prefix or tag style. |
chat.format.truce | Truce chat format. | Change this to alter the truce prefix. |
chat.format.moderator | Moderator-channel format. | Used for the faction moderator private channel. |
chat.format.coleader | Coleader-channel format. | Used for the faction coleader private channel. |
chat.format.chatspy | Spy output format. | Shown to players with chat spy enabled. |
chat.format.enemy | Enemy-chat format. | Controls the enemy channel prefix and body layout. |
chat.colors.* | Relation colors used by placeholders. | Tune these to match your server branding and readability needs. |
chat.role-prefixes.* | Role badge strings. | Change these if you want different chat badges for leaders and staff. |
chat.tablist.enabled | Whether tablist formatting is used. | Disable if another tablist plugin already owns formatting. |
chat.tablist.format | Tablist line format. | Supports the relation and faction placeholders listed in the file. |
chat.block-enemy-chat | Blocks public chat visibility for enemies when enabled. | Use only if you want relation-based chat isolation. |
chat.min-message-length, max-message-length | Chat length limits. | Use to keep channels clean and prevent huge messages. |
chat.allow-colors, allow-formatting | Allow color/format codes in messages. | Often used with permission-gated donor chat formatting. |
chat.message-cooldown | Seconds between messages. | Use small values to reduce faction-chat spam. |
chat.faction-chat-commands, ally-chat-commands, truce-chat-commands | Command aliases that toggle channels. | Extend these if you want shorthand aliases. |
Other YAML Files
These files are important but more domain-specific than the three main behavior files above.
missions.yml
Defines mission templates, goals, difficulty, and rewards. This is the content file for faction mission progression.
factionshop.yml
Defines categories and purchasable point-shop entries. Items can be plain Bukkit items or linked custom items.
customitems.yml
Defines plugin-native custom items, third-party item visuals, action types, cooldowns, uses, and interaction triggers. The dedicated custom-items page goes much deeper.
discord.yml
Controls webhook event logging, embed settings, bot display, and faction Discord invite link behavior.
permissions.yml
Contains the server permission tree and default faction-role permission definitions used by the internal GUI permission layer.
guis.yml
Controls menu titles, sizes, border materials, and item placements for the SmartInvs GUI system.