HyFactions Integration

HyperPerms automatically detects HyFactions and enables faction chat integration. No configuration required - just install both plugins and they'll work together.

Tip: This integration is automatic. If both plugins are installed, faction features are enabled immediately on server start.

Features

Automatic faction prefix in chat - Shows faction name before the player's group prefix
Optional rank display - Include the player's faction rank (Owner, Officer, Member)
Chat placeholders - Use faction data anywhere in your chat format
Customizable formats - Full control over how faction info is displayed

Chat Examples

Default (with faction prefix): [Warriors][Admin] Steve: Hello everyone!

[Warriors] - Faction (cyan)
[Admin] - Group (red)
Steve - Player (white)
: Hello everyone! - Message (gray)

With faction rank: [Warriors|Owner][Admin] Steve: Hello everyone!

[Warriors|Owner] - Faction + Rank (cyan)
[Admin] - Group (red)
Steve - Player (white)
: Hello everyone! - Message (gray)

No faction: [Admin] Steve: Hello everyone!

[Admin] - Group (red)
Steve - Player (white)
: Hello everyone! - Message (gray)

Configuration

The HyFactions integration is configured in the factions section of your config.json:

{
  "factions": {
    "enabled": true,
    "prefixEnabled": true,
    "prefixFormat": "&7[&b%s&7] ",
    "showRank": false,
    "prefixWithRankFormat": "&7[&b%s&7|&e%r&7] ",
    "noFactionDefault": ""
  }
}

Configuration Options

Option	Type	Default	Description
`enabled`	boolean	true	Enable or disable the entire HyFactions integration
`prefixEnabled`	boolean	true	Automatically add faction prefix to chat messages
`prefixFormat`	string	"&7[&b%s&7] "	Format for faction prefix. `%s` = faction name
`showRank`	boolean	false	Include the player's faction rank in the prefix
`prefixWithRankFormat`	string	"&7[&b%s&7\|&e%r&7] "	Format when showRank is true. `%s` = faction, `%r` = rank
`noFactionDefault`	string	""	Text shown when player has no faction (empty = nothing)

Placeholders

The HyFactions integration adds these placeholders for use in your chat format:

Placeholder	Description	Example Output
`%faction%`	The player's faction name	Warriors
`%faction_rank%`	Player's rank within their faction	Owner, Officer, Member
`%faction_tag%`	Short faction tag (typically 4 characters)	WARR

Using Placeholders in Chat Format

You can use these placeholders in your chat format configuration:

{
  "chat": {
    "format": "&7[&b%faction%&7] %prefix%%player%%suffix%&8: &f%message%"
  }
}

Info: If a player has no faction, %faction% placeholders will be empty unless you set a noFactionDefault value.

Format Examples

Simple Faction Tag

{
  "factions": {
    "enabled": true,
    "prefixEnabled": true,
    "prefixFormat": "&8[&a%s&8] ",
    "showRank": false
  }
}

// Result: [Warriors][Admin] Steve: Hello

Faction with Rank

{
  "factions": {
    "enabled": true,
    "prefixEnabled": true,
    "showRank": true,
    "prefixWithRankFormat": "&7[&b%s &8| &e%r&7] "
  }
}

// Result: [Warriors | Owner][Admin] Steve: Hello

Short Tag Only

{
  "factions": {
    "enabled": true,
    "prefixEnabled": true,
    "prefixFormat": "&8[&6%s&8]"
  }
}

// Then use %faction_tag% in chat format for short tags
// Result: [WARR][Admin] Steve: Hello

No Faction Indicator

{
  "factions": {
    "enabled": true,
    "prefixEnabled": true,
    "prefixFormat": "&7[&b%s&7] ",
    "noFactionDefault": "&7[&8No Faction&7] "
  }
}

// Players without a faction will show:
// [No Faction][Member] Alex: Hello

Advanced Chat Format

For complete control, disable the automatic prefix and use placeholders directly:

{
  "factions": {
    "enabled": true,
    "prefixEnabled": false
  },
  "chat": {
    "format": "&7[&b%faction%&7|&e%faction_rank%&7] %prefix%%player%%suffix%&8: &f%message%"
  }
}

Warning: When using placeholders directly with prefixEnabled: false, players without a faction will have empty placeholders. Make sure your format handles this gracefully.

Troubleshooting

Faction prefix not showing

Verify HyFactions is installed and enabled
Check that factions.enabled is true
Check that factions.prefixEnabled is true
Ensure the player is actually in a faction
Reload config with /hp reload

Integration not detected

Make sure HyFactions loads before HyperPerms
Check console for detection message at startup
Restart the server (not just reload)

Placeholders showing as literal text

Verify HyFactions integration is enabled
Check placeholder spelling (%faction% not %factions%)
Run /hp reload after config changes