AgentSkillsCN

groups

ChatControl 权限分组：支持基于分组的设置覆盖，可通过 chatcontrol.group.{name} 定义各分组的权限，为每个分组设定消息延迟、相似度阈值、通道上限、MOTD 以及声音通知格式。当您需要配置分组覆盖规则，或排查分组权限相关问题时，可使用此功能。

SKILL.md
--- frontmatter
name: groups
description: 'ChatControl permission groups: group-based setting overrides, chatcontrol.group.{name} permissions, per-group message delays, similarity thresholds, channel limits, MOTD, sound notify format. Use when configuring group overrides or diagnosing group permission issues.'

Permission Groups

Overview

ChatControl groups override global settings per-player based on the chatcontrol.group.<name> permission. Groups are NOT Vault permission groups — they are ChatControl-specific permission-based overrides.

Important distinction: There are TWO unrelated "group" concepts:

  1. •PlayerGroup (this skill) — permission-based setting overrides in settings.yml → Groups
  2. •Rule Group — reusable operator sets in rules/groups.rs (see rules-engine skill)

Architecture

Key Classes

  • •PlayerGroup<T> (model/PlayerGroup.java) — generic class holding a setting type and default
  • •PlayerGroup.Type — enum of overridable settings

Resolution Logic

code
PlayerGroup.getFor(player)
  → Iterate Settings.Groups.LIST (order matters)
    → For each group: check if player has chatcontrol.group.<name>
      → First match wins → return group value
  → No match → return global default

Configuration (settings.yml → Groups)

Overridable Settings

SettingTypePlayerGroup.TypeDefault Source
Max_Read_ChannelsIntegerMAX_READ_CHANNELSChannels.Max_Read_Channels
Message_DelaySimpleTimeMESSAGE_DELAYAnti_Spam.Chat.Delay
Message_SimilarityDoubleMESSAGE_SIMILARITYAnti_Spam.Chat.Similarity
Command_DelaySimpleTimeCOMMAND_DELAYAnti_Spam.Commands.Delay
Command_SimilarityDoubleCOMMAND_SIMILARITYAnti_Spam.Commands.Similarity
Sound_Notify_FormatStringSOUND_NOTIFY_FORMATglobal format
MotdStringMOTDglobal MOTD

Example Configuration

yaml
Groups:
  vip:
    Max_Read_Channels: 5
    Message_Delay: 0.5 seconds
    Message_Similarity: 60
  admin:
    Max_Read_Channels: 10
    Message_Delay: 0 seconds
    Message_Similarity: 0
    Command_Similarity: 0

Permissions

  • •chatcontrol.group.<name> — assigns player to group
  • •First matching group wins if player has multiple group permissions
  • •Groups are checked in the order they appear in settings.yml

Common Issues & Solutions

"Group override not applying"

  1. •Verify permission: chatcontrol.group.<name> (not Vault group name)
  2. •Check group order in settings.yml — first match wins
  3. •Ensure the setting key is spelled correctly (case-sensitive)
  4. •Use /chc info <player> to check resolved values

"Vault groups vs ChatControl groups"

  • •ChatControl does NOT use Vault group names
  • •Assign chatcontrol.group.vip permission to your Vault VIP group
  • •This is a deliberate design: works with any permissions plugin

"Multiple groups conflicting"

  • •Player gets the FIRST matching group only
  • •Order groups from most specific (highest rank) to least
  • •Admin should be listed before VIP if admin has VIP permission too

"Group delay set to 0 but still delayed"

  • •Check channel-specific Message_Delay override (takes priority)
  • •Check chatcontrol.bypass.delay.chat permission instead

Key File Paths

  • •PlayerGroup class: chatcontrol-bukkit/src/main/java/org/mineacademy/chatcontrol/model/PlayerGroup.java
  • •Settings: chatcontrol-bukkit/src/main/resources/settings.yml (Groups section)
  • •Permissions: chatcontrol-core/src/main/java/org/mineacademy/chatcontrol/model/Permissions.java

Foundation Integration

  • •HookManager — uses Vault for offline permission checks (getForUUID())
  • •SimpleTime — parses delay durations