TablistMod

---

TabListMod — Permission-Driven Animated Tablist with Sprites, Gradients, Inline Animations & Per-Dimension Layouts

Built as a companion to Chat Mod. Shares ChatMod's sprite atlas and sprites.yml directly — every sprite alias you define in ChatMod works in your tablist headers, footers, prefixes and suffixes without any duplication. All ChatMod colour, gradient and sprite syntax is fully supported in every format string.

---

What It Does

TabListMod gives server administrators complete control over how the tablist header, footer and player name rows look — based on each player's permissions. Admins see a different layout than VIPs, who see a different one than regular members. Each format can be animated, per-dimension, and contain live placeholders — all defined in simple YAML with no restarts needed.

On top of that, every player gets a formatted name row with their prefix, coloured display name and suffix built from a configurable format string. Prefixes and suffixes each have their own priority system, permission node and optional conditions.

---

Features

🎨 Per-Permission Tablist Formats

Define any number of tablist formats in tablist_formats.yml. The first format whose permission node a player holds is applied. A format with no permission node acts as the catch-all fallback that matches everyone.

formats:
  admin:
    priority: 100
    permission_node: 'TabListMod.admin'
    animated: true
    seconds: 2.0
    frames:
      1:
        header:
          - ''
          - '<#FF5555>⚡ Admin ⚡<#FF0000>'
          - '&7Players: &f%online_players%&7/&f%max_players%   &7Balance: &a%balance%'
          - ''
        footer:
          - ''
          - '&7%datetime%'
          - ''

  default:
    priority: 0
    animated: true
    seconds: 2.0
    frames:
      1:
        header:
          - ''
          - '%animation:running_man%'
          - '<#55FF55>✦ Welcome to the Server ✦'
          - '&7Players: &f%online_players%   &7Ping: &f%ping%ms'
          - '&7Balance: &a%balance%'
          - ''
        footer:
          - ''
          - '&7%date%   &f%time%'
          - ''

Every format string supports colour codes, flat hex (&#RRGGBB), gradients (<#RRGGBB>text<#RRGGBB>), sprite tokens ([#alias], [item], [player]), and all internal and PlaceholderAPI placeholders.

---

🎬 Frame-Based Animation with Fallback

Animated formats use a numbered frame map instead of a flat list. Frame 1 is the canonical frame — it must define both header and footer. Any later frame only needs to declare what actually changes. Lines omitted in frame 2, 3 or beyond automatically fall back to frame 1's value, so you never repeat static lines across frames.

frames:
  1:
    header:
      - ''
      - '<#55FF55>✦ Welcome ✦'
      - '&7Players: &f%online_players%'
      - ''
    footer:              # ← defined once, inherited by all other frames
      - ''
      - '&7%date%   &f%time%'
      - ''
  2:
    header:              # only the header changes — footer omitted → uses frame 1's
      - ''
      - '<#FFAA00>✦ Welcome ✦'
      - '&7Players: &f%online_players%'
      - ''

---

✨ Inline Animations %animation:name%

Define reusable text animations in tablist_animations.yml. Each animation has its own independent frame rate and cycles through a list of text values. Drop %animation:name% into any header, footer, prefix, suffix, or player name format string and it animates at its own speed — completely independent of the surrounding format's animation speed.

animations:
  running_man:
    seconds: 0.20
    frames:
      - '&f[#run]&7·····················'
      - '&f·[#walk]&7····················'
      # ...

Animations work in fully static formats too — if any line contains %animation:x%, the format is automatically sent every tick so no frames are skipped.

---

🌍 Per-Dimension Layouts

Every format can define dimension-specific overrides that activate when a player enters that world. Overrides can be static or independently animated with their own frame rate.

dimensions:
  'minecraft:the_nether':
    animated: false
    header:
      - ''
      - '&4&l[ Nether ] &b&lModerator'
      - '&cWorld: [#netherrack] &4The Nether'
      - ''
    footer:
      - ''
      - '&c%datetime%'
      - ''

---

🏷️ Prefixes, Suffixes & Player Name Format

Define prefix and suffix tiers in tablist_prefixes.yml. Each entry has its own priority, permission node, and optional conditions. The player's name row in the tablist is fully configurable via tablist_name_format in tablistmod.yml:

tablist_name_format: '%custom_rank%%displayname%'

Token	Value
%custom_rank%	Active prefix format string (colour codes included)
%displayname%	Player's in-game display name
%player%	Raw Minecraft username
%balance%	EcoBal balance (requires EcoBal mod)
%ping%	Current latency in ms

Sprites, hex colours and gradients all work in the name format too.

---

🖼️ Sprite Support via ChatMod

TabListMod bridges directly into ChatMod's AtlasSpriteHelper and SpritesManager. Every sprite alias you define in ChatMod's sprites.yml is available in TabListMod with the same token syntax — no separate sprite config needed.

[#grass_block]    → sprite alias from sprites.yml
[#netherrack]     → sprite alias
[item]            → item the player is holding
[item:1]          → item in hotbar slot 1
[player]          → player's skin head (16×16)
[player:Name]     → specific player's head

If ChatMod is not installed, sprite tokens resolve to empty — the rest of the tablist continues to work normally.

---

💰 EcoBal Economy Integration

If EcoBal is present, %balance% resolves to the player's formatted balance with a configurable currency symbol and decimal places. If EcoBal is absent, %balance% shows N/A. No configuration needed — detection is fully automatic.

ecobal:
  enabled: true
  decimal_places: 2
  currency_symbol: "$"

---

📋 Placeholders

Placeholder	Value
%player%	Raw Minecraft username
%displayname%	In-game display name
%custom_rank%	Active prefix (with colour codes)
%ping%	Latency in ms
%online_players%	Current player count
%max_players%	Server player slot limit
%balance%	EcoBal balance
%date%	Current date (yyyy-MM-dd)
%time%	Current time (HH:mm:ss)
%datetime%	Full date, time and timezone
%dimension%	Dimension display name
%dimension_id%	Raw dimension key, e.g. minecraft:the_nether
%dimension_sprite%	Sprite token for current dimension
%playtime%	Total playtime, e.g. 3d 2h 15m
%animation:name%	Current frame of a named inline animation

All Fabric PlaceholderAPI placeholders are also resolved automatically.

---

🎮 Per-Line Animation Mode

For fine-grained control, individual header lines can each have their own animation speed. A line with speed 0 stays completely static while the lines around it animate independently.

per_line_seconds:
  - 0      # line 1 — static forever
  - 1.25   # line 2 — cycles every 1.25 s
  - 1.0    # line 3 — cycles every 1.0 s
  - 0      # line 4 — static forever
header_lines:
  - frames: ['']
  - frames: ['<#FF5555>⚡ Admin ⚡', '<#FF0000>⚡ Admin ⚡']
  - frames: ['&7Players: &f%online_players%']
  - frames: ['']

---

👻 Spectator Handling

Configure how spectator players appear in the tablist.

Mode	Behaviour
KEEP_POSITION	Spectators stay in their normal sorted position
SINK_TO_BOTTOM	Spectators sink below all survival players
HIDE_EFFECT	Spectator gamemode packet cancelled; appear as normal players

---

🔧 Admin Commands

Command	Description	Permission
/tablist reload	Hot-reload all TabListMod configs	tablistmod.reload
/tablist debug [player]	Show active format, prefix and suffix	tablistmod.debug
/tablist list formats	List all loaded formats	tablistmod.list
/tablist list prefixes	List all loaded prefixes	tablistmod.list
/tablist player <name> refresh	Force-refresh a player's tablist	tablistmod.player.refresh

No server restart required for any config change — /tablist reload picks everything up instantly.

---

Configuration Files

All files live under config/tablistmod/. Use /tablist reload after any edit.

File	Contains
tablistmod.yml	Global settings, name format, timezone, spectator mode, EcoBal, dimension maps
tablist_formats.yml	Per-permission header/footer format definitions
tablist_prefixes.yml	Prefix and suffix definitions
tablist_animations.yml	Reusable inline animation definitions

---

Dependencies

Mod	Required?
Fabric API	✅ Required
LuckPerms	✅ Required for per-permission formats
ChatMod	⭐ Strongly recommended — enables sprites and shared atlas
EcoBal	🔶 Optional — enables %balance% placeholder
Placeholder API	🔶 Optional — enables PAPI placeholders

TabListMod has no hard compile-time dependency on ChatMod — it runs standalone and degrades gracefully (sprites resolve to empty) if ChatMod is not installed. The two mods are designed as a pair and work best together.

---

Modpack Policy

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