ChatFormatMod

---

ChatFormatMod — Per-Permission Chat Formatting, Nicknames, Tags & Player Profiles

Built as a companion to Chat Mod. Works alongside it seamlessly — ChatMod handles item display, sprites, hover events, broadcasts and MOTD; ChatFormatMod takes over chat line layout, nicknames, cosmetic tags, custom ranks, and player profiles. All ChatMod formatting syntax is fully supported in every format string.

---

What It Does

ChatFormatMod gives server administrators complete control over how each player's chat messages look, based on their permissions. Admins get a different chat style than VIPs, who get a different one than regular members — all defined in simple YAML with no restarts needed.

On top of that, players can set coloured nicknames, pick a cosmetic tag to show beside their name, fill in a personal profile, and have a custom rank prefix and suffix — all tied to a permission-driven system that integrates with LuckPerms out of the box.

---

Features

🎨 Per-Permission Chat Styles

Define any number of chat format styles in formats.yml. The first style whose permission node a player holds is applied. An empty permission acts as the fallback default that matches everyone.

styles:
  - id: admin
    permission: "chatmod.admin"
    format: "&c%custom_rank%&r &ö%displayname%&ö %tag% &7»&r %message%"

  - id: vip
    permission: "chatmod.vip"
    format: "&6[VIP]&r &ö%displayname%&ö %tag% &7»&r %message%"

  - id: default
    permission: ""
    format: "&ö%displayname%&ö %tag% &7»&r %message%"

Every format string supports the full ChatMod token set — colour codes, hex colours, {hover text}, <action:…> click events, [item], [#SpriteName], [@Name], &= newlines, &+ centering, and all ChatMod and PlaceholderAPI placeholders.

---

🏷️ Nicknames /nickname /nick

Players can set a coloured display nickname. Permissions control exactly what they are allowed.

Usage:

/nickname <nick>               — set your own nickname
/nickname reset                — remove your nickname
/nickname <nick> <player>      — set another player's nickname (requires .others)
/nickname reset <player>       — remove another player's nickname (requires .others)

Nicknames cannot be blank. If a player tries to set a nickname that consists only of colour codes with no visible text, it is rejected.

Duplicate protection: Two nicknames whose visible text is identical (case-insensitive, all codes stripped) are considered duplicates. &1Testing and &aTesting are both blocked if plain Testing is already taken — unless the player holds chatmod.nick.duplicate, which allows colour variants of an existing name to coexist.

| Permission | Grants |
|---|---|
| chatmod.nick | Use /nickname at all |
| chatmod.nick.color | Colour codes (&0–&f) in nickname |
| chatmod.nick.hexa | Hex colours (&#RRGGBB) in nickname |
| chatmod.nick.format | Formatting codes (&l, &o, &n …) in nickname |
| chatmod.nick.length.<n> | Max visible-character length — highest node wins |
| chatmod.nick.length.unlimited | No length restriction |
| chatmod.nick.others | Set or reset another player's nickname |
| chatmod.nick.bypass.taken | Bypass all nickname uniqueness checks |
| chatmod.nick.duplicate | Allow colour variants of an already-taken visible name |

---

🔖 Cosmetic Tags /tags

Players open a GUI and pick one cosmetic tag to display beside their name. Tags are defined in tags.yml and each has its own permission node. The active tag is inserted into the format string as %tag%.

tags:
  - id: pvp
    permission: "chatmod.tag.pvp"
    display: "&c[PvP]&r"
    description: "Ready to fight!"

---

🏅 Custom Ranks

Define rank tiers in custom_ranks.yml. The first rank whose permission a player holds is applied and exposed as three placeholders in format strings:

| Placeholder | Content |
|---|---|
| %custom_rank% | Prefix + suffix combined |
| %prefix% | Rank prefix only |
| %suffix% | Rank suffix only |

---

👤 Player Profiles /profile

Admins define any number of profile fields in profile_fields.yml — gender, pronouns, country, play style, or anything else. Players fill them in through a GUI. Profile values appear in chat via %profile:fieldId% placeholders, and are viewable by others when the chatmod.profile.view.others permission is granted.

Fields support both pre-defined option lists (cycle with left/right click) and free-text input (player types the value in chat).

---

🔗 Automatic Link Detection

URLs typed in chat are automatically converted into clickable, styled links. Fully configurable:

link_detection_enabled: true
link_shorten: true   # https://www.example.com/page → example.com/page
link_format: "&b&n%link%{Open links responsibly}"

The {…} hover syntax is the same one ChatMod uses everywhere — whatever is between the braces appears as hover text on the link.

---

🚪 Custom Join & Leave Messages

Replace vanilla join and leave messages with your own formatted versions. The vanilla messages are properly suppressed so players never see them twice.

joined_the_game: "&e%player% joined the game"
joined_for_first_time: true
joined_for_first_time_format: "&e%player% joined the game for the first time!"
joined_after_name_change: "&e%player% joined the game &7(name changed)"
left_the_game: "&e%player% left the game"

Fresh install note: When the mod is installed on an established server, it reads Minecraft's own usercache.json to identify every player who has ever joined before. Those players are all treated as returning players — no long-term player ever sees a "joined for the first time" message just because the mod's own data file didn't exist yet.

---

Chat Format Placeholders

These placeholders are available in formats.yml format strings, join/leave messages, and anywhere ChatFormatMod resolves text:

| Placeholder | Value |
|---|---|
| %displayname% | Nickname (if set) or real Minecraft username |
| %player% | Always the real Minecraft username |
| %tag% | Active cosmetic tag display, or empty |
| %custom_rank% | Rank prefix + suffix merged |
| %prefix% | Rank prefix only |
| %suffix% | Rank suffix only |
| %message% | The player's message (required in format strings) |
| %profile:fieldId% | Value of a profile field, e.g. %profile:gender% |

All ChatMod built-in placeholders (%online_players%, %date%, %time%, etc.) and PlaceholderAPI placeholders are also resolved automatically.

---

📋 Tablist & Other Mod Integration (PlaceholderAPI)

All ChatFormatMod data is exposed as PlaceholderAPI placeholders under the chatformatmod namespace. Any mod that supports PlaceholderAPI — tablist mods, scoreboard mods, nametag mods — can pull in nicknames, ranks, tags and profile fields directly.

| Placeholder | Value |
|---|---|
| %chatformatmod:nick% | Nickname with § colour codes, or real username |
| %chatformatmod:nick_plain% | Nickname with all colour codes stripped |
| %chatformatmod:displayname% | Alias for nick |
| %chatformatmod:prefix% | Rank prefix, e.g. §c§lAdmin §r |
| %chatformatmod:suffix% | Rank suffix |
| %chatformatmod:rank% | Prefix + suffix combined |
| %chatformatmod:prefix_nick% | Prefix + nickname |
| %chatformatmod:nick_suffix% | Nickname + suffix |
| %chatformatmod:prefix_nick_suffix% | Prefix + nickname + suffix all together |
| %chatformatmod:tag% | Active cosmetic tag display text, or empty |
| %chatformatmod:style% | Active format style ID, e.g. admin |
| %chatformatmod:profile:fieldId% | Value of any profile field by ID |
| %chatformatmod:profile_gender% | Shorthand for the gender profile field |
| %chatformatmod:profile_country% | Shorthand for the country profile field |

Example — player list name in a tablist mod:

%chatformatmod:prefix_nick_suffix%

Example — nametag mod (prefix above head / name / suffix below):

Above:  %chatformatmod:prefix%
Name:   %chatformatmod:nick%
Below:  %chatformatmod:suffix%  %chatformatmod:tag%

The colour codes in all placeholders are returned as §-prefixed legacy codes, which all tablist and nametag mods universally understand. No conversion needed on your side — just drop the placeholder into your config and it works.

Requires Placeholder API to be installed for these placeholders to resolve in other mods. They are registered automatically when PlaceholderAPI is present; if it is absent, ChatFormatMod continues to work normally for chat formatting.

---

Admin Commands

| Command | Description | Permission |
|---|---|---|
| /chatformat reload | Reload all ChatFormatMod configs | chatmod.admin.reload |
| /chatformat debug <player> | Show active style, nick, tag and rank | chatmod.admin.debug |
| /nickname <nick> | Set own nickname | chatmod.nick |
| /nickname reset | Reset own nickname | chatmod.nick |
| /nickname <nick> <player> | Set another player's nickname | chatmod.nick.others |
| /nickname reset <player> | Reset another player's nickname | chatmod.nick.others |
| /tags | Open the cosmetic tag selector GUI | chatmod.tags |
| /profile | Open your own profile GUI | chatmod.profile |
| /profile <player> | View another player's profile | chatmod.profile.view.others |

Aliases: /cf for /chatformat, /nick for /nickname.

---

Configuration Files

All files live under config/chatformatmod/. Use /chatformat reload after any edit — no server restart required.

| File | Contains |
|---|---|
| chatformatmod.yml | Global toggles, link detection, join/leave messages |
| formats.yml | Chat format styles per permission |
| custom_ranks.yml | Rank prefix/suffix definitions |
| tags.yml | Cosmetic tag definitions |
| profile_fields.yml | Player profile field definitions |
| messages.yml | All player-facing system strings |

Player data (nicknames, active tags, profile values) is stored per-world in <world>/chatformatmod_playerdata.json.

---

Dependencies

| Mod | Required? |
|---|---|
| Fabric API | ✅ Required |
| ChatMod | ⭐ Strongly recommended |
| LuckPerms | ✅ Required for per-permission styles |
| Fabric Permissions API | ✅ Required |
| Placeholder API | 🔶 Optional — enables PAPI placeholders and tablist integration |

ChatFormatMod has no hard compile-time dependency on ChatMod — it will run standalone and degrade gracefully (colour codes strip to plain text, no hover/click events) if ChatMod is not installed. However, the two mods are designed as a pair and work best together.

---

Modpack Policy

• ✅ You may include ChatFormatMod in any modpack.
• ❌ The modpack must not be sold.