HuskChat

https://github.com/wiiiiam278/huskchat
Admin
HuskChat is a customizable chat system for Minecraft networks that supports cross-server...
Tokens:11,402
Snippets:103
Trust Score:-
License:Apache-2.0
Update:6 months ago
Show doc for...
Tokens:
Raw
### HuskChat Permissions and LuckPerms Setup

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

A reference list of permission nodes for HuskChat features and example commands for configuring them via LuckPerms.

```yaml
# Command permissions
huskchat.command.channel        # Use /channel command
huskchat.command.huskchat       # Use /huskchat admin command
huskchat.command.msg            # Use /msg command
huskchat.command.msg.reply      # Use /reply command
huskchat.command.socialspy      # Toggle social spy
huskchat.command.socialspy.bypass  # Bypass social spy monitoring
huskchat.command.localspy       # Toggle local spy (proxy only)
huskchat.command.broadcast      # Use /broadcast command
huskchat.command.optoutmsg      # Use /optoutmsg command

# Channel permissions (replace <channel> with channel ID)
huskchat.channel.<channel>.send     # Send to channel
huskchat.channel.<channel>.receive  # Receive from channel

# Filter bypass permissions
huskchat.bypass_filters             # Bypass all filters
huskchat.ignore_filters.advertising # Bypass advertising filter
huskchat.ignore_filters.caps        # Bypass caps filter
huskchat.ignore_filters.spam        # Bypass spam filter
huskchat.ignore_filters.profanity   # Bypass profanity filter
huskchat.ignore_filters.repeat      # Bypass repeat filter
huskchat.ignore_filters.ascii       # Bypass ASCII filter
huskchat.ignore_filters.regex       # Bypass regex filter
huskchat.ignore_filters.emoji_replacer  # Disable emoji replacement

# Formatting permission
huskchat.formatted_chat  # Allow MineDown formatting in messages

# Join/quit permissions
huskchat.silent_join  # Silent join (no message)
huskchat.silent_quit  # Silent quit (no message)
huskchat.join_message.<format>  # Custom join message format
huskchat.quit_message.<format>  # Custom quit message format

# LuckPerms setup example
lp group default permission set huskchat.command.channel true
lp group default permission set huskchat.command.msg true
lp group default permission set huskchat.command.msg.reply true
lp group moderator permission set huskchat.command.socialspy true
lp group moderator permission set huskchat.channel.staff.send true
lp group moderator permission set huskchat.channel.staff.receive true
lp group admin permission set huskchat.command.broadcast true
lp group admin permission set huskchat.bypass_filters true
```

--------------------------------

### Install HuskChat on Single Server

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Commands to download the Bukkit plugin jar, generate configuration files, and open them for editing.

```bash
# Download and install
cd ~/server/plugins
wget https://github.com/WiIIiam278/HuskChat/releases/latest/download/HuskChat-Bukkit.jar

# Start server to generate configs
java -jar ../server.jar

# Edit configuration
nano plugins/HuskChat/config.yml
nano plugins/HuskChat/channels.yml
```

--------------------------------

### Configure Chat Channels

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Example configuration for defining custom chat channels, including formatting, scopes, and permissions.

```yaml
# channels.yml - Define custom chat channels
default_channel: global
server_default_channels:
  survival: global
  creative: local
  minigames: minigames

channel_log_format: '[CHAT] [%channel%] %sender%: '
channel_command_aliases:
  - channel
  - c

channels:
  # Global channel - messages broadcast to all servers
  - id: global
    format: '&#00fb9a&[G]&r&f %fullname%&r&f: '
    broadcast_scope: GLOBAL
    log_to_console: true
    restricted_servers: []
    filtered: true
    permissions: {}
    shortcut_commands:
      - /global
      - /g

  # Local channel - messages only to players on same server
  - id: local
    format: '%fullname%&r&f: '
    broadcast_scope: LOCAL
    log_to_console: true
    restricted_servers: []
    filtered: true
    permissions: {}
    shortcut_commands:
      - /local
      - /l

  # Staff channel - permission restricted
  - id: staff
    format: '&e[Staff] %name%: &7'
    broadcast_scope: GLOBAL
    log_to_console: true
    restricted_servers: []
    filtered: false
    permissions:
      send: huskchat.channel.staff.send
      receive: huskchat.channel.staff.receive
    shortcut_commands:
      - /staff
      - /sc

  # HelpOp channel - players can send, staff can receive
  - id: helpop
    format: '&#00fb9a&[HelpOp] %name%:&7'
    broadcast_scope: GLOBAL
    log_to_console: true
    restricted_servers: []
    filtered: false
    permissions:
      receive: huskchat.channel.helpop.receive
    shortcut_commands:
      - /helpop
      - /helpme
```

--------------------------------

### Install HuskChat on Proxy Server

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Commands to download the appropriate plugin jar for Velocity or BungeeCord/Waterfall proxy environments.

```bash
# Velocity installation
cd ~/proxy/plugins
wget https://github.com/WiIIiam278/HuskChat/releases/latest/download/HuskChat-Velocity.jar

# BungeeCord/Waterfall installation
wget https://github.com/WiIIiam278/HuskChat/releases/latest/download/HuskChat-Bungee.jar
```

--------------------------------

### Configure Channel Broadcast Scopes

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Configuration example demonstrating the use of PASSTHROUGH scope for backend plugin compatibility.

```yaml
# Proxy server scopes (Velocity/BungeeCord):
# GLOBAL - Broadcast to all connected servers
# LOCAL - Broadcast only to players on the same server
# PASSTHROUGH - Pass message to backend server (not handled by proxy)
# GLOBAL_PASSTHROUGH - Global broadcast + pass to backend
# LOCAL_PASSTHROUGH - Local broadcast + pass to backend

# Single server scopes (Spigot/Paper):
# GLOBAL - Broadcast to all players on server
# PASSTHROUGH - Delegate to vanilla/other chat handlers
# GLOBAL_PASSTHROUGH - Broadcast to all + pass to other handlers

channels:
  # Backend plugin compatibility channel
  - id: input
    format: ''
    broadcast_scope: PASSTHROUGH
    log_to_console: false
    filtered: false
    permissions: {}
    shortcut_commands:
      - /i
```

--------------------------------

### Configure Spicord Bot

Source: https://github.com/wiiiiam278/huskchat/blob/master/docs/Discord-Hook.md

Example configuration for the Spicord config.toml file to enable HuskChat integration.

```toml
  name = "Server Chat"
  enabled = true
  token = "[YOUR TOKEN]"
  command_support = true
  command_prefix = "-"
  addons = [
    "spicord::info",
    "spicord::plugins",
    "spicord::players",
    "huskchat"
  ]
```

--------------------------------

### MineDown Formatting Syntax

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Advanced text formatting examples including RGB colors, gradients, hover text, and click actions.

```yaml
# RGB hex colors
format: '&#FF5733&This is orange text'

# Gradients (requires MineDown)
format: '&[#00ff00&#ff0000]Gradient text'

# Hover text
format: '[Hover me](show_text=&7Secret message!)'

# Click actions
format: '[Click here](suggest_command=/help)'
format: '[Run command](run_command=/spawn)'
format: '[Visit](open_url=https://example.com)'

# Combined example for staff channel
channels:
  - id: staff
    format: '&e[&6Staff&e] [%name%](show_text=&7UUID: %uuid%
Ping: %ping%ms suggest_command=/msg %name% )&8: &7'
```

--------------------------------

### Define a Staff Channel in channels.yml

Source: https://github.com/wiiiiam278/huskchat/blob/master/docs/Channels.md

Example configuration for a staff channel, specifying format, scope, logging, permissions, and shortcut commands. Ensure the `id` matches the channel name used in commands.

```yaml
# Channel definitions
channels:
  # ...
  - id: staff
    format: '&e[Staff] %name%: &7'
    broadcast_scope: GLOBAL
    log_to_console: true
    restricted_servers: []
    filtered: false
    permissions:
      send: huskchat.channel.staff.send
      receive: huskchat.channel.staff.receive
    shortcut_commands:
      - /staff
      - /sc
  # ...
```

--------------------------------

### Build HuskChat

Source: https://github.com/wiiiiam278/huskchat/blob/master/README.md

Build the HuskChat plugin using Gradle. Ensure Python (>=v3.6) with 'jep' and 'alt-profanity-check' is installed for profanity filter tests.

```bash
./gradlew clean build
```

--------------------------------

### Configure Server-Specific Default Channels

Source: https://github.com/wiiiiam278/huskchat/blob/master/docs/Channels.md

Map server names to default channel IDs in `config.yml`. Players will automatically switch to the assigned channel when joining a server. This is ignored on single-server setups.

```yaml
server_default_channels:
  uhc: minigames
  bedwars: minigames
```

--------------------------------

### Configure Join and Quit Messages

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Customize connection messages and set up permission-based overrides via LuckPerms.

```yaml
# config.yml - join_and_quit_messages section
join_and_quit_messages:
  join:
    enabled: true
    format: '&8[&a+&8] &e%name% joined the network'
  quit:
    enabled: true
    format: '&8[&c-&8] &e%name% left the network'
  broadcast_scope: GLOBAL  # GLOBAL, LOCAL, or PASSTHROUGH

# Permission-based custom messages via LuckPerms:
lp group vip permission set huskchat.join_message.&6[VIP] &e%name% &7has arrived!
lp group admin permission set huskchat.join_message.&c[Admin] &e%name% &7is now online!

# Silent join/quit permissions:
# huskchat.silent_join - No join message shown
# huskchat.silent_quit - No quit message shown
```

--------------------------------

### Use Channel Commands

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Commands for switching active channels, sending messages to specific channels, and using shortcuts.

```text
# Switch to a channel (all future messages go to this channel)
/channel global
/c staff

# Send a single message to a channel without switching
/channel staff Hey team, I need help with a griefer!

# Use shortcut commands
/g Hello everyone!        # Send to global
/l Hi local players       # Send to local
/staff Admin meeting now  # Send to staff channel
/helpop I need assistance # Send help request
```

--------------------------------

### Channel Format Placeholders

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Configuration for channel message formatting using built-in placeholders.

```yaml
# Available placeholders for channel formats:
# %name% - Player username
# %fullname% - Prefix + username + suffix (from LuckPerms)
# %prefix% - Role prefix
# %suffix% - Role suffix
# %role% - Primary group name
# %role_display_name% - Primary group display name
# %ping% - Player ping
# %uuid% - Player UUID
# %server% - Current server name
# %local_players_online% - Players on current server

# Time placeholders:
# %timestamp% - yyyy/MM/dd HH:mm:ss
# %current_time% - HH:mm:ss
# %current_time_short% - HH:mm
# %current_date% - yyyy/MM/dd

# Example channel format with placeholders
channels:
  - id: global
    format: '&8[&a%server%&8] &7%prefix%%name%%suffix%&8: &f'
```

--------------------------------

### Configure Discord Webhooks

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Map in-game channels to specific Discord webhook URLs in config.yml.

```yaml
# config.yml - discord section
discord:
  enabled: true
  format_style: EMBEDDED  # or INLINE

  # Map channels to Discord webhook URLs
  channel_webhooks:
    global: 'https://discord.com/api/webhooks/1234567890/abcdefghijklmnop'
    staff: 'https://discord.com/api/webhooks/0987654321/qrstuvwxyz'
```

--------------------------------

### Configure Spicord Two-Way Integration

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Set up bidirectional communication between Minecraft and Discord using Spicord.

```yaml
# config.yml - discord spicord section
discord:
  enabled: true
  format_style: INLINE

  spicord:
    enabled: true
    # Format for Discord users shown in-game
    username_format: '@%discord_handle%'

    # Send in-game channel messages to Discord channel (by ID)
    receive_channel_map:
      global: '123456789012345678'
      staff: '234567890123456789'

    # Send Discord channel messages to in-game channel
    send_channel_map:
      '123456789012345678': global
      '234567890123456789': staff
```

```toml
# Spicord config.toml - add huskchat addon
[[bots]]
  name = "Server Chat"
  enabled = true
  token = "YOUR_BOT_TOKEN_HERE"
  command_support = true
  command_prefix = "-"
  addons = [
    "spicord::info",
    "spicord::plugins",
    "spicord::players",
    "huskchat"
  ]
```

--------------------------------

### Configure Join and Quit Messages

Source: https://github.com/wiiiiam278/huskchat/blob/master/docs/Join-and-Quit-Messages.md

Set `join_and_quit_messages.join.enabled` and `join_and_quit_messages.quit.enabled` to `true` to activate custom messages. Modify the `format` to change the message content, supporting placeholders like `%name%` and MineDown formatting. The `broadcast_scope` determines where messages are sent.

```yaml
# Options for customizing player join and quit messages
join_and_quit_messages:
  join:
    enabled: false
    # Use the huskchat.join_message.[text] permission to override this per-group if needed
    format: '&e%name% joined the network'
  quit:
    enabled: false
    # Use the huskchat.quit_message.[text] permission to override this per-group if needed
    format: '&e%name% left the network'
  broadcast_scope: GLOBAL # Note that on Velocity/Bungee, PASSTHROUGH modes won't cancel local join/quit messages
```

--------------------------------

### Configure Local Spy

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Enable monitoring of local chat channels across servers in proxy environments.

```yaml
# config.yml - local_spy section
local_spy:
  enabled: true
  format: '&e[Spy] &7[%server%] %sender_name%:%spy_color% '
  localspy_aliases:
    - /localspy
    - /ls
  excluded_local_channels:
    - input
    - passthrough

# Permission: huskchat.command.localspy
```

--------------------------------

### Add HuskChat API Dependencies

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Include the HuskChat API in your project using Maven or Gradle. Ensure the repository is defined to resolve the artifacts.

```xml
<!-- Maven pom.xml -->
<repositories>
    <repository>
        <id>william278-releases</id>
        <url>https://repo.william278.net/releases</url>
    </repository>
</repositories>

<dependencies>
    <!-- For Bukkit/Spigot plugins -->
    <dependency>
        <groupId>net.william278.huskchat</groupId>
        <artifactId>huskchat-bukkit</artifactId>
        <version>3.0.4</version>
        <scope>provided</scope>
    </dependency>

    <!-- For common API (platform-independent) -->
    <dependency>
        <groupId>net.william278.huskchat</groupId>
        <artifactId>huskchat-common</artifactId>
        <version>3.0.4</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
```

```groovy
// Gradle build.gradle
repositories {
    maven { url 'https://repo.william278.net/releases' }
}

dependencies {
    // For Bukkit/Spigot plugins
    compileOnly 'net.william278.huskchat:huskchat-bukkit:3.0.4'

    // For Velocity plugins
    compileOnly 'net.william278.huskchat:huskchat-velocity:3.0.4'

    // For BungeeCord plugins
    compileOnly 'net.william278.huskchat:huskchat-bungee:3.0.4'
}
```

--------------------------------

### HuskChatAPI Instance Access

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

How to retrieve the HuskChatAPI instance and send a chat message to a specific channel.

```APIDOC
## GET /api/huskchat/instance

### Description
Retrieves the singleton instance of the HuskChatAPI to perform plugin operations.

### Method
Java API Call

### Request Example
```java
HuskChatAPI huskChatAPI = HuskChatAPI.getInstance();
```

### Response
- **HuskChatAPI** (Object) - The main entry point for HuskChat API methods.

## POST /api/huskchat/send-message

### Description
Sends a chat message to a specified channel as a specific user.

### Method
Java API Call

### Parameters
- **channel** (String) - Required - The ID of the channel to send the message to.
- **user** (OnlineUser) - Required - The user object representing the sender.
- **message** (String) - Required - The content of the message.

### Request Example
```java
huskChatAPI.sendChatMessage("global", player, "Welcome to the server!");
```
```

--------------------------------

### HuskChat General Configuration

Source: https://github.com/wiiiiam278/huskchat/blob/master/docs/Config-Files.md

This snippet shows the main configuration options for HuskChat, including language, update checks, packet listening, placeholder settings, and message command configurations. It's used to control core plugin behavior and message handling.

```yaml
# ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
# ┃       HuskChat - Config      ┃
# ┃    Developed by William278   ┃
# ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
# ┣╸ Information: https://william278.net/project/huskchat/
# ┣╸ Config Help: https://william278.net/docs/huskchat/config-files/
# ┗╸ Documentation: https://william278.net/docs/huskchat/

# Locale of the default language file to use. Docs: https://william278.net/docs/huskclaims/translations
language: en-gb
# Whether to automatically check for plugin updates on startup
check_for_updates: true
# Whether to handle chat packets directly for better 1.19+ support (may cause rare compatibility issues)
use_packet_listening: true
# Placeholder settings
placeholder:
  # Use PlaceholderAPI. If you're on Bungee/Velocity, this requires PAPIProxyBridge installed
  use_papi: true
  # If using PAPIProxyBridge, how long to cache placeholders for (in milliseconds)
  cache_time: 3000
# Message comamnd settings
message_command:
  # Whether to enable the /msg command
  enabled: true
  # List of command aliases for /msg
  msg_aliases:
    - /msg
    - /m
    - /tell
    - /whisper
    - /w
    - /pm
  # List of command aliases for /reply
  reply_aliases:
    - /reply
    - /r
  # Whether to apply censorship filters on private messages
  censor: false
  # Whether to log private messages to the console
  log_to_console: true
  # Logging format for private messages
  log_format: '[MSG] [%sender% -> %receiver%]: '
  # Group private message settings
  group_messages:
    # Whether to enable group private messages (/msg Player1,Player2,...)
    enabled: true
    # Maximum amount of players in a group message
    max_size: 10
  # Formats for private messages (uses MineDown)
  format:
    inbound: '&e&l%name% &8→ &e&lYou&8: &f'
    outbound: '&e&lYou &8→ &e&l%name%&8: &f'
    group_inbound: '&e&l%name% &8→ &e&lYou[₍₊%group_amount_subscript%₎](gray show_text=&7%group_members%)&8:
      &f'
    group_outbound: '&e&lYou &8→ &e&l%name%[₍₊%group_amount_subscript%₎](gray show_text=&7%group_members%)&8:
      &f'
  # (Bungee/Velocity only) List of servers where private messages cannot be sent
  restricted_servers: []
# Social spy settings (see other users' private messages)
social_spy:
  enabled: true
  format: '&e[Spy] &7%name% &8→ &7%receiver_name%:%spy_color% '
  group_format: '&e[Spy] &7%name% &8→ &7%receiver_name% [₍₊%group_amount_subscript%₎](gray
    show_text=&7%group_members% suggest_command=/msg %group_members_comma_separated%
    ):%spy_color% '
  socialspy_aliases:
    - /socialspy
    - /ss
# (Bungee/Velocity only) Local spy settings (see local messages on other servers)
local_spy:
  enabled: true
  format: '&e[Spy] &7%name% &8→ &7%receiver_name%:%spy_color% '
  localspy_aliases:
    - /socialspy
    - /ss
  # List of channels to exclude from local spy
  excluded_local_channels: []
# Broadcast command settings
broadcast_command:
  enabled: true
  broadcast_aliases:
    - /broadcast
    - /alert
  format: '&6[Broadcast]&e '
  log_to_console: true
  log_format: '[BROADCAST]: '
# Join and quit message settings
join_and_quit_messages:
  # Use the "huskchat.join_message.[text]" permission to override this.
  # Use the "huskchat.silent_join" permission to silence for a user.
  join:
    enabled: true
    format: '&e%name% joined the network'
  # Use the "huskchat.quit_message.[text]" permission to override this.
  # Use the "huskchat.silent_quit" permission to silence for a user.
  quit:
    enabled: true
    format: '&e%name% left the network'
  # Note that on Velocity/Bungee, PASSTHROUGH modes won't cancel local join/quit messages
  broadcast_scope: GLOBAL

```

--------------------------------

### Administrative Commands

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Server operator commands for broadcasting, social spying, and plugin management.

```text
# Broadcast a server-wide announcement
/broadcast Server restart in 5 minutes!
/alert Maintenance scheduled for 3 PM UTC

# Toggle social spy (see others' private messages)
/socialspy
/socialspy red     # Set spy message color
/ss

# Toggle local spy (see local chat from other servers)
/localspy
/localspy blue
/ls

# Plugin management
/huskchat about    # View plugin info
/huskchat reload   # Reload configuration
```

--------------------------------

### Use Private Messaging Commands

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Commands for sending private messages to other players.

```text
# Send private message to one player
/msg PlayerName Hello there!
/tell PlayerName How are you?
/w PlayerName Whisper message
```

--------------------------------

### Listen to Private Messages with BukkitPrivateMessageEvent

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Implement this listener to intercept and modify private messages. You can log messages, alter their content, or perform other actions before they are sent to recipients.

```java
import net.william278.huskchat.event.BukkitPrivateMessageEvent;
import net.william278.huskchat.user.OnlineUser;
import java.util.List;
import java.util.stream.Collectors;

// Assuming getLogger() and LocalDateTime/DateTimeFormatter are available in the context
// For demonstration purposes, these are included as placeholders.
// import java.time.LocalDateTime;
// import java.time.format.DateTimeFormatter;
// import static org.bukkit.Bukkit.getLogger;

public class ChatListener implements Listener {

    // Listen to private messages
    @EventHandler
    public void onPrivateMessage(BukkitPrivateMessageEvent event) {
        OnlineUser sender = event.getSender();
        List<OnlineUser> recipients = event.getRecipients();
        String message = event.getMessage();

        // Log private messages (custom logging)
        // getLogger().info(String.format("[PM] %s -> %s: %s",
        //     sender.getUsername(),
        //     recipients.stream().map(OnlineUser::getUsername).collect(Collectors.joining(", ")),
        //     message));

        // Modify message content
        event.setMessage(message + " (sent via PM)");
    }
}
```

--------------------------------

### Configure Social Spy

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Enable and customize the social spy feature for monitoring private messages.

```yaml
# config.yml - social_spy section
social_spy:
  enabled: true
  format: '&e[Spy] &7%sender_name% &8-> &7%receiver_name%:%spy_color% '
  group_format: '&e[Spy] &7%sender_name% &8-> &7%receiver_name% [+%group_amount_subscript%](gray show_text=&7%group_members%):%spy_color% '
  socialspy_aliases:
    - /socialspy
    - /ss

# Permissions:
# huskchat.command.socialspy - Toggle social spy
# huskchat.command.socialspy.bypass - Messages not seen by spies
```

--------------------------------

### Configure Group Messages in config.yml

Source: https://github.com/wiiiiam278/huskchat/blob/master/docs/Group-Messages.md

Enable group messaging and set the maximum number of participants allowed in a single group message.

```yaml
  group_messages: # Whether to allow sending and replying to a message in a group (/msg User1,User2 <message>)
    enabled: true
    max_size: 10
```

--------------------------------

### Private Message Configuration

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Configuration settings for private message aliases, logging, and formatting in config.yml.

```yaml
# config.yml message_command section
message_command:
  enabled: true
  msg_aliases:
    - /msg
    - /m
    - /tell
    - /whisper
    - /w
    - /pm
  reply_aliases:
    - /reply
    - /r
  censor: false
  log_to_console: true
  log_format: '[MSG] [%sender% -> %receiver%]: '

  group_messages:
    enabled: true
    max_size: 10

  # Message formats using MineDown
  format:
    # Incoming private message format
    inbound: '&e&l%name% &8-> &e&lYou&8: &f'
    # Outgoing private message format
    outbound: '&e&lYou &8-> &e&l%name%&8: &f'
    # Group message formats with member count
    group_inbound: '&e&l%name% &8-> &e&lYou[+%group_amount_subscript%](gray show_text=&7%group_members%)&8: &f'
    group_outbound: '&e&lYou &8-> &e&l%name%[+%group_amount_subscript%](gray show_text=&7%group_members%)&8: &f'

  restricted_servers: []  # Servers where /msg is disabled
```

--------------------------------

### Manage Filter Bypass Permissions

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Grant bypass permissions using LuckPerms commands or reference the available permission nodes.

```yaml
# Permission nodes for filter bypass
# huskchat.bypass_filters - Bypass all filters
# huskchat.ignore_filters.advertising - Bypass advertising filter
# huskchat.ignore_filters.caps - Bypass caps filter
# huskchat.ignore_filters.spam - Bypass spam filter
# huskchat.ignore_filters.profanity - Bypass profanity filter
# huskchat.ignore_filters.repeat - Bypass repeat filter
# huskchat.ignore_filters.ascii - Bypass ASCII filter
# huskchat.ignore_filters.regex - Bypass regex filter
# huskchat.ignore_filters.emoji_replacer - Disable emoji replacement

# LuckPerms example
lp group admin permission set huskchat.bypass_filters true
lp group moderator permission set huskchat.ignore_filters.spam true
```

--------------------------------

### Chat Filter Configuration

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Settings for filters.yml to manage spam, advertising, profanity, and message repetition.

```yaml
# filters.yml
filters:
  # Prevent excessive caps
  CAPS:
    type: caps
    enabled: true
    channels:
      - global
      - local
    private_messages: true
    broadcast_messages: false
    max_caps_percentage: 0.4  # 40% max caps allowed

  # Block IP addresses and URLs
  ADVERTISING:
    type: filter
    enabled: true
    channels:
      - global
      - local
    private_messages: true
    broadcast_messages: false

  # Block non-ASCII characters
  ASCII:
    type: filter
    enabled: true
    channels:
      - global
      - local
    private_messages: true
    broadcast_messages: false

  # Rate limit messages (spam prevention)
  SPAM:
    type: spam
    enabled: true
    channels:
      - global
      - local
    private_messages: true
    broadcast_messages: false
    period_seconds: 4
    messages_per_period: 3

  # Prevent duplicate messages
  REPEAT:
    type: repeat
    enabled: true
    channels:
      - global
      - local
    private_messages: true
    broadcast_messages: false
    previous_messages_to_check: 5

  # Custom regex patterns
  REGEX:
    type: regex
    enabled: false
    channels:
      - global
      - local
    private_messages: true
    broadcast_messages: false
    patterns:
      - '(?i)badword\d*'
      - '(?i)inappropriate.*phrase'

  # Machine learning profanity detection
  PROFANITY:
    type: profanity
    enabled: false
    channels:
      - global
      - local
    private_messages: true
    broadcast_messages: false
    library_path: ''  # Path to Jep library
    mode: AUTOMATIC   # or TOLERANCE
    tolerance: 0.78   # Lower = more strict
```

--------------------------------

### Configure Emoji Replacer

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Define text-to-emoji mappings and scope settings within the filters.yml file.

```yaml
# filters.yml - replacers section
replacers:
  EMOJI:
    type: emoji
    enabled: true
    channels:
      - global
      - local
    private_messages: true
    broadcast_messages: false
    case_insensitive: false
    emoji:
      ':heart:': ❤
      ':smile:': ☺
      ':frown:': ☹
      ':star:': ⭐
      ':fire:': 🔥
      '<3': ❤
      ':)': ☺
      ':(': ☹
      ':-)': ☺
      ':-(': ☹
      ':thumbsup:': 👍
      ':wave:': 👋
```

--------------------------------

### Listen to Broadcast Messages with BukkitBroadcastMessageEvent

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Implement this listener to intercept and modify broadcast messages. You can add timestamps, alter content, or perform other actions before broadcasts are sent.

```java
import net.william278.huskchat.event.BukkitBroadcastMessageEvent;
import net.william278.huskchat.user.OnlineUser;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class ChatListener implements Listener {

    // Listen to broadcast messages
    @EventHandler
    public void onBroadcast(BukkitBroadcastMessageEvent event) {
        OnlineUser sender = event.getSender();
        String message = event.getMessage();

        // Add timestamp to broadcasts
        String timestamp = LocalDateTime.now().format(DateTimeFormatter.ofPattern("HH:mm"));
        event.setMessage("[" + timestamp + "] " + message);
    }
}
```

--------------------------------

### Listen to Chat Events with BukkitChatMessageEvent

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Implement this listener to intercept and modify channel chat messages. You can change message content, redirect messages to different channels, or cancel messages entirely.

```java
import net.william278.huskchat.event.BukkitChatMessageEvent;
import org.bukkit.event.EventHandler;
import org.bukkit.event.EventPriority;
import org.bukkit.event.Listener;

public class ChatListener implements Listener {

    // Listen to channel chat messages
    @EventHandler(priority = EventPriority.NORMAL)
    public void onChatMessage(BukkitChatMessageEvent event) {
        // Get message details
        String channelId = event.getChannelId();
        String message = event.getMessage();
        OnlineUser sender = event.getSender();

        // Modify the message
        if (message.contains("secret")) {
            event.setMessage(message.replace("secret", "******"));
        }

        // Redirect to different channel
        if (channelId.equals("global") && message.startsWith("!staff")) {
            event.setChannelId("staff");
            event.setMessage(message.substring(7));
        }

        // Cancel the event to prevent message from being sent
        if (message.contains("blocked")) {
            event.setCancelled(true);
        }
    }
}
```

--------------------------------

### Send Messages via HuskChat API

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Use this class to send chat, broadcast, and private messages programmatically. Ensure HuskChatAPI is initialized before use.

```java
import net.william278.huskchat.api.HuskChatAPI;
import net.william278.huskchat.user.OnlineUser;
import java.util.List;
import java.util.Optional;

public class ChatManager {

    private final HuskChatAPI api = HuskChatAPI.getInstance();

    // Send a message to a specific channel
    public void sendToChannel(OnlineUser sender, String channelId, String message) {
        try {
            api.sendChatMessage(channelId, sender, message);
        } catch (IllegalArgumentException e) {
            // Channel does not exist
            sender.sendMessage("Channel not found: " + channelId);
        }
    }

    // Send a broadcast message
    public void broadcast(OnlineUser sender, String message) {
        api.sendBroadcastMessage(sender, message);
    }

    // Send a private message to multiple players
    public void sendPrivateMessage(OnlineUser sender, List<String> recipients, String message) {
        api.sendPrivateMessage(sender, recipients, message);
    }

    // Get and set player channels
    public void managePlayerChannel(OnlineUser player) {
        // Get current channel
        Optional<String> currentChannel = api.getPlayerChannel(player);
        currentChannel.ifPresent(channel -> {
            player.sendMessage("You are in channel: " + channel);
        });

        // Set player to a different channel
        api.setPlayerChannel(player, "staff");
    }
}
```

--------------------------------

### Access HuskChat API

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Use the HuskChatAPI instance to programmatically send messages from your own plugin.

```java
import net.william278.huskchat.api.HuskChatAPI;
import net.william278.huskchat.user.OnlineUser;

public class MyPlugin extends JavaPlugin {

    private HuskChatAPI huskChatAPI;

    @Override
    public void onEnable() {
        // Get the API instance
        huskChatAPI = HuskChatAPI.getInstance();
    }

    public void sendWelcomeMessage(OnlineUser player) {
        // Send a chat message to a channel
        huskChatAPI.sendChatMessage("global", player, "Welcome to the server!");
    }
}
```

--------------------------------

### Private Message Commands

Source: https://context7.com/wiiiiam278/huskchat/llms.txt

Commands for sending private messages to individuals or groups and managing conversation replies.

```text
/msg Player1,Player2,Player3 Hey team, let's group up!

# Reply to last private message/group
/r Thanks for the info!
/reply I'll be there soon

# Opt out of a group message conversation
/optoutmsg
```
Tokens:
Raw