Modern Factions Custom Items and Network

Custom Item Fields

Every item under customitems.yml is keyed by its item id. The id is what admin commands and internal systems use.

customitems.yml

Field	Meaning	How To Configure It
`TYPE`	Fallback Bukkit material.	Always set this, even when using Nexo or ItemsAdder, so the plugin has a fallback visual.
`NAME`	Display name.	Supports color codes. Use an empty string if you want to preserve the third-party base item's original name.
`LORE`	Lore lines.	Supports color codes. Use an empty list to keep external item lore untouched.
`MODELDATA`	Custom model data integer.	Use `-1` to disable model data handling.
`COOLDOWN`	Seconds before the item can be used again.	Use `-1` for no cooldown.
`USE`	Maximum uses before the item is consumed or exhausted.	Use `-1` for unlimited uses.
`INTERACTS`	Interaction types that trigger the item.	Examples include `RIGHT_CLICK_AIR`, `RIGHT_CLICK_BLOCK`, and shift-click variants. Leave empty for tools that are not click-triggered.
`NEXO_ID`	Nexo visual item id.	Optional. Requires Nexo to be installed. Modern Factions will stamp its own metadata onto the resolved item.
`ITEMSADDER_ID`	ItemsAdder namespaced item id.	Optional. Use the `namespace:item_name` format.
`IS_FURNITURE`	Whether the external base is a furniture-style entity item.	Mainly relevant for cave block style placement when the base item is not a normal block item.
`ACTION.TYPE`	Defines the runtime behavior.	Each action type has its own additional fields.

Supported Action Types

The shipped config comments and example items show the action types supported by the plugin's item system.

Item Actions

HEAL

Instant healing item. Usually used on right click.

JUMP

Applies a jump effect. Uses fields like DURATION and AMPLIFIER.

SPEED

Applies a speed effect with duration and amplifier tuning.

REGEN

Applies regeneration with duration and amplifier.

GOD

Applies a temporary god-mode style effect package.

TELEPORT

Teleports the player to a configured location using TELEPORT_LOCATION.

MONEY

Gives a fixed money amount using AMOUNT.

RANDOMMONEY

Gives a random money amount up to MAX_AMOUNT.

UNCLAIM

Runs an area scan or utility behavior using AREA and optional custom message fields.

CAVEBLOCK

Places a cave block utility item that interacts with the cave block system.

DYNAMITE

Creates a throwable explosive item. Uses fields such as FUSE_TICKS, EXPLOSION_POWER, BREAK_BLOCKS, and DAMAGE_ENTITIES.

PICKAXE

Custom mining tool behavior using fields like hold effect, radius, and custom durability.

COMMAND

Runs a command on use. Use COMMAND and optionally RUN_AS_CONSOLE.

When an action type needs extra fields, those fields live directly under ACTION. For example, a jump item uses ACTION.DURATION and ACTION.AMPLIFIER, while a teleport item uses ACTION.TELEPORT_LOCATION.

Shipped Example Items

The default config already demonstrates most of the item system.

Examples

Consumables and Buffs

heal_potion
jump_scroll
speed_stick
regen_gem
god_apple

Mobility and Economy

spawn_teleporter
money_bag
lucky_coin

Faction Utility

unclaim_finder
unclaim_finder_small
command_item

Advanced Systems

aoe_pickaxe
caveblock
dynamite

The commented Nexo and ItemsAdder examples in the file are not active by default. They are there as templates for your own network item packs.

How Cross-Server Support Works

Modern Factions uses RabbitMQ for messaging and proxy messaging for server transfer. These are related, but they are not the same thing.

RabbitMQ and Proxy Flow

Part	What It Does	What You Must Configure
RabbitMQ connection	Connects each backend server to a shared fanout exchange.	Set `rabbitmq.enabled`, `server-id`, `exchange`, and the AMQP `uri`.
Cross-server faction chat	Publishes Modern Factions private channels to other servers.	All servers must share the same exchange and be online at the same time.
Cross-server public chat	Can exist, but should not overlap with OreoEssentials public network chat.	If OreoEssentials owns public chat, let Modern Factions own only faction-private channels.
Pending teleport handoff	Stores a short-lived teleport payload for the destination server.	RabbitMQ must be running and connected on both source and destination servers.
Actual server switch	Sends the player through the proxy using the BungeeCord plugin messaging channel.	Your proxy must support that channel. On Velocity, enable `bungee-plugin-message-channel = true`.

What Is Cross-Server Right Now

Modern Factions can move faction-private chat channels across servers through RabbitMQ. It can also hand off pending home and warp teleports across servers.

What Still Needs A Proxy

RabbitMQ alone does not physically move a player to another backend server. The actual transfer still depends on the proxy message channel path.

How To Avoid Chat Dupes

If OreoEssentials is installed and handles public cross-server chat, Modern Factions should only own faction, ally, enemy, truce, moderator, and coleader channels. That is the intended split.

Server Id Rule

rabbitmq.server-id must be unique per backend and should match the server name you expect to route players to for cross-server home or warp travel.

rabbitmq:
  enabled: true
  server-id: "survival"
  exchange: "oreofactions_chat"
  rabbitmq:
    uri: "amqp://guest:guest@localhost:5672/"

Recommended network pattern: OreoEssentials owns global public chat and optional public network chat. Modern Factions owns private faction channels and faction home/warp handoff.