Better IP Use (BIU)

报告问题及发布：https://github.com/my-txz/better_ip_use/issues

Reporting issues and publishing:https://github.com/my-txz/better_ip_use/issues

!Spigot 1.19–1.20.4
!Java 17 !Java 21

A lightweight, conflict-resistant Minecraft plugin that displays player geolocation and filters inappropriate chat using built-in integrations with Uapipro APIs. Features include smart location formatting, sensitive word detection, chat cooldowns, and a community-driven reporting system.

一款轻量级、抗冲突的 Minecraft 插件，通过内置 Uapipro API 集成实现玩家地域显示与聊天内容过滤。包含智能地域格式化、敏感词检测、发言冷却及社区举报系统。

🙏 Special thanks to Uapipro for providing reliable public APIs used in this plugin.
🙏 特别鸣谢 Uapipro 提供稳定可靠的公共 API 支持。

---

Tips:

Version download corresponds to:

1.X supports 1.19-1.20.6 | 2.X supports 1.20.6-1.21.11 | 3. X supports 1.13-1.18.2 (in development)

---

✨ Core Features

🌍 Smart Geolocation Display

Fetches region data via https://uapis.cn/api/v1/network/ipinfo?ip=%IP% and formats it consistently across three interfaces:

• Tab List: Appends as suffix → Steve [中国 北京]
• Chat Message: Rewrites format → Steve[中国 北京]: Hello!
• Nametag (Above Head): Uses prefix for visibility → [中国 北京] Steve

By default, regions are auto-trimmed to the first two space-separated parts (e.g., "中国 北京 海淀区" → "中国 北京"). Configurable via display.region_format: auto | full.

🚫 Sensitive Word Filtering

Uses https://uapis.cn/api/v1/sensitive-word/quick-check to detect violations. A message is flagged if:

• Response contains "status": "forbidden", or
• The forbidden_words array has ≥1 entry.

Punishment flow:

1. First offense → warning
2. Repeat offense → mute (default: 5 minutes)
3. Optional broadcast on mute

Bypass permission: better_ip_use.bypass.

⏳ Chat Cooldown System

Prevents spam by enforcing a configurable delay between messages (default: 5 seconds). Players see a countdown when violating.

📢 Community Reporting (/biu report <player>)

Players can report others for recent inappropriate speech:

• Checks up to 3 messages from the last 5 minutes
• Reporter cooldown: 5 minutes (configurable)
• If any message violates rules, target is automatically muted
• Fully asynchronous — no server lag

♻️ Resource Efficiency & Cleanup

• IP-to-region results are cached per player
• All player data (cache, history, mutes) is cleaned on quit
• Manual cache clearing via /biu clearcache
• Chat history automatically expires after 10 minutes to save memory

⚙️ Conflict-Aware Event Handling

• Display updates use EventPriority.MONITOR — runs after plugins like Essentials/CMI
• Chat formatting uses EventPriority.HIGH — reliably overrides most chat systems

---

⚠️ Requirements

• Minecraft: Spigot/Paper 1.19 to 1.20.4 (inclusive)
• Java: 17+
• Internet Access: Must reach uapis.cn

❗ This plugin currently only supports Java 17 and Minecraft 1.19–1.20.4.
❗ 本插件目前仅支持 Java 17 及 Minecraft 1.19–1.20.4。

🔧 We are currently adapting BIU for Bukkit. You may try it at your own risk.
🔧 我们正在对 Bukkit 进行适配，可以自行进行尝试。

---

🔧 Configuration Highlights (config.yml)

# 语言设置: zh / en
language: "zh"

# 功能开关
settings:
  # 启用聊天合规检查
  enable_chat_check: true
  # 启用预审核模式 (true = 发送后审核再显示, false = 实时审核拦截)
  # true: 玩家发送 -> 服务器审核 -> 通过则广播显示, 不通过则屏蔽
  # false: 玩家发送 -> 实时检测 -> 违规则拦截并取消事件
  pre_moderation: true
  # 启用 IP 显示 (Tab/头顶/聊天)
  enable_ip_display: true

# 聊天冷却设置
chat_cooldown:
  enabled: true
  # 冷却时间 (秒)
  seconds: 5

# 举报系统设置
report_system:
  enabled: true
  # 检查几分钟内的消息
  check_minutes_ago: 5
  # 举报冷却时间 (秒)
  reporter_cooldown_seconds: 300
  # 每次最多检查几条消息
  max_check_messages: 3

# API 配置
api:
  sensitive_word:
    # 正确的API端点 - 使用uapis.cn的敏感词检测接口
    url: "https://uapis.cn/api/v1/text/profanitycheck"
  ip_info:
    # IP信息查询接口模板
    url_template: "https://uapis.cn/api/v1/network/ipinfo?ip=%IP%"

显示设置

display: region_format: "auto" # auto (取前两级) 或 full (完整) color: "&3" unknown_text: "Unknown"

Tab 列表后缀

tab_suffix_enabled: true

聊天后缀

chat_suffix_enabled: true

头顶前缀

nametag_prefix_enabled: true

处罚设置

punishment: warn_first: true mute_minutes: 5 broadcast_on_mute: true

消息多语言配置

messages: zh: prefix: "&3[&bBIU&3] &r" warn: "&c您的发言包含不合规内容，请注意文明用语。" cooldown: "&c请勿频繁发言，还需等待 &e%time% &c秒。" mute: "&c你因多次违规已被禁言 %mute_minutes% 分钟。" mute_admin: "&c你已被管理员禁言。" mute_active: "&c你当前处于禁言状态，无法发言。" mute_broadcast: "&c玩家 &e%player% &c因多次违规已被禁言 %mute_minutes% 分钟。" unmuted: "&a你已被解除禁言，可以正常发言了。" unmuted_auto: "&a你的禁言时间已到，已自动解除禁言。" reload: "&a配置已重载。" cache_cleared: "&aIP地址缓存已清除，所有玩家显示已重置。" no_permission: "&c你没有权限执行此操作。" help: | &a/biu help &7- 显示帮助 &a/biu reload &7- 重载配置 &a/biu clearcache &7- 清除IP缓存 &a/biu report <玩家> &7- 举报玩家近期违规发言 &a/biu mute <玩家> &7- 手动禁言玩家 &a/biu unmute <玩家> &7- 解除玩家禁言 &a/biu check <文本> &7- 检测文本是否违规 report_usage: "&c用法: /biu report <玩家名>" report_disabled: "&c举报系统当前已禁用。" report_cooldown: "&c举报功能冷却中，还需等待 &e%time% &c秒。" report_self: "&c不能举报自己。" report_target_no_history: "&c该玩家近期无可举报的发言记录。" report_checking: "&a正在检查玩家 &e%player% &a的近期发言..." report_success_compliant: "&a举报检查结果：玩家 &e%player% &a近期发言合规。" report_success_forbidden: "&c举报检查结果：玩家 &e%player% &c存在违规发言，已自动禁言。" report_broadcast: "&c玩家 &e%player% &c因被举报违规发言，已被系统禁言。举报者: &e%reporter%" mute_cmd_usage: "&c用法: /biu mute <玩家名>" unmute_cmd_usage: "&c用法: /biu unmute <玩家名>" player_muted: "&c已手动禁言玩家 &e%player%&c。" player_unmuted: "&a已解禁玩家 &e%player%&a。" player_not_found: "&c未找到玩家: &e%player%&c。"

en: prefix: "&3[&bBIU&3] &r" warn: "&cYour message contains non-compliant content. Please be civil." cooldown: "&cPlease do not spam. Wait &e%time% &cseconds." mute: "&cYou have been muted for %mute_minutes% minutes due to repeated violations." mute_admin: "&cYou have been muted by an administrator." mute_active: "&cYou are currently muted and cannot chat." mute_broadcast: "&cPlayer &e%player% &chas been muted for %mute_minutes% minutes." unmuted: "&aYou have been unmuted. You can chat normally now." unmuted_auto: "&aYour mute time has expired. You can chat normally now." reload: "&aConfiguration reloaded." cache_cleared: "&aIP address cache cleared." no_permission: "&cYou do not have permission." help: | &a/biu help &7- Show help &a/biu reload &7- Reload config &a/biu clearcache &7- Clear IP cache &a/biu report &7- Report a player for recent bad chat &a/biu mute &7- Manually mute a player &a/biu unmute &7- Unmute a player &a/biu check &7- Check if text violates rules report_usage: "&cUsage: /biu report " report_disabled: "&cReport system is currently disabled." report_cooldown: "&cReport function is on cooldown. Wait &e%time% &cseconds." report_self: "&cYou cannot report yourself." report_target_no_history: "&cTarget player has no recent chat history to report." report_checking: "&aChecking recent messages from &e%player%&a..." report_success_compliant: "&aReport Result: Player &e%player% &ais compliant." report_success_forbidden: "&cReport Result: Player &e%player% &cviolated rules. Auto-muted." report_broadcast: "&cPlayer &e%player% &cwas muted due to report. Reporter: &e%reporter%" mute_cmd_usage: "&cUsage: /biu mute " unmute_cmd_usage: "&cUsage: /biu unmute " player_muted: "&cPlayer &e%player%&c has been manually muted." player_unmuted: "&aPlayer &e%player%&c has been unmuted." player_not_found: "&cPlayer not found: &e%player%&c."

All display elements share the same color and fallback text.

---

## 📜 Commands & Permissions

| Command | Permission | Description |
|--------|------------|-------------|
| `/biu help` | `better_ip_use.use` | Show help |
| `/biu reload` | `better_ip_use.reload` | Reload config |
| `/biu clearcache` | `better_ip_use.reload` | Clear IP cache |
| `/biu report <player>` | `better_ip_use.use` | Report player’s recent chat |
| `/biu mute <player>` | `better_ip_use.admin` | Manually mute player |
| `/biu unmute <player>` | `better_ip_use.admin` | Unmute player |

Default permissions: ops only. Tab completion supported.

---

## 📦 Deployment

1. Place `BetterIPUse.jar` in `plugins/`
2. Start server to generate `config.yml`
3. Adjust settings if needed (defaults work out-of-box with Uapipro)
4. Use `/biu reload` after changes

No extra dependencies — uses Spigot’s built-in Gson.

---

>  No telemetry, no ads, no hidden features.  
> 无遥测、无广告、无隐藏功能。  
>  
> **Complies with Modrinth Community Guidelines.**  
> **遵守 Modrinth 社区规范。**