FailureToLog Paper 插件
FailureToLog 是一款 Paper 服务器插件,可在服务器聊天中报告登录失败、错误断开连接以及兼容的 Fabric 客户端断开连接报告。
它帮助服务器管理人员了解玩家为何无法连接或已被断开连接,并通过游戏内命令检查存储在服务器端的错误报告。
功能说明
- 检测玩家登录尝试失败的情况。
- 检测服务器端踢出(kick)和错误断开连接。
- 将错误断开连接的提示消息替换为更清晰的 FailureToLog 消息。
- 保持正常的加入和退出行为不变。
- 存储最近的错误日志以便检查。
- 添加可点击的聊天按钮以查看错误详情。
- 接收来自可选的 FailureToLog API Fabric 模组的客户端侧断开屏幕报告。
- 提供用于启用/禁用插件、切换日志保存、查看错误代码以及打开存储日志的命令。
要求
- Paper
26.1.2
- Java
25 或更高版本
可选的客户端配套组件:
- Minecraft
26.1.2 的 FailureToLog API Fabric 模组
安装方法
- 停止服务器。
- 将插件 jar 文件放入服务器的
plugins 文件夹中。
- 启动服务器。
- 插件将自动创建其配置文件和日志文件。
插件 jar 包:
FailureToLog-Paper-1.0-SNAPSHOT.jar
典型的服务器文件夹结构:
plugins/FailureToLog
配置
配置文件:
plugins/FailureToLog/config.yml
默认配置:
enabled: true
save-logs: true
enabled
开启或关闭 FailureToLog 的行为。
enabled: true
save-logs
控制是否将错误日志保存到磁盘。
save-logs: true
启用后,日志将保存至:
plugins/FailureToLog/logs.yml
命令
主命令:
/failuretolog
别名:
/ftl
切换插件状态
/failuretolog toggle
开启或关闭 FailureToLog。
所需权限:
failuretolog.admin
切换日志保存
/failuretolog savelogs <on|off>
示例:
/failuretolog savelogs on
/failuretolog savelogs off
所需权限:
failuretolog.admin
查看错误代码
/failuretolog codes
显示完整的 FailureToLog 错误代码列表。
查看错误日志
/failuretolog log <id>
显示已存储的错误报告。
当检测到错误时,FailureToLog 会发布一条带有可点击 [View error] 按钮的聊天消息。点击该按钮会自动执行此命令。
权限
failuretolog.admin
默认授予对象:
op (管理员)
允许使用以下命令更改 FailureToLog 设置:
/failuretolog toggle
/failuretolog savelogs <on|off>
聊天消息格式
示例:
Due to an error, PlayerName failed to connect. Error code: 600 (Bad client data) [View error]
针对服务器端踢出的情况:
Due to an error, PlayerName lost connection. Error code: 500 (Server-side problem) [View error]
针对 Fabric 客户端报告的情况:
Due to an error, PlayerName reported a client-side disconnect. Error code: 1 (Unknown crash) [View error]
正常的加入和退出操作保持服务器的默认行为。
错误代码
FailureToLog 包含以下代码:
1: Unknown crash
6: Not whitelisted
7: Banned
9: Blacklisted
105: World chunk load failure
200: Server memory shortage
201: Client memory shortage
401: Authentication/session failure
408: Connection timeout
429: Connection throttled
500: Server-side problem
503: Server full
600: Bad client data
601: Unsupported client version
602: Resource pack failure
790: Mod or socket conflict
插件根据登录结果、踢出原因、服务器消息以及可选的 Fabric 客户端报告对错误进行分类。如果无法分类某个错误,则使用:
1: Unknown crash
Fabric 客户端集成
FailureToLog 可以接收来自可选的 FailureToLog API Fabric 模组的额外客户端侧断开信息。
插件使用以下 Minecraft 自定义负载通道(Custom Payload Channels):
failuretolog:hello
failuretolog:client_log
流程:
- 玩家加入服务器。
- 服务器发送
failuretolog:hello。
- 兼容的 Fabric 客户端检测到 FailureToLog 服务器。
- 如果客户端看到断开连接屏幕,Fabric 模组会存储该屏幕的标题和原因。
- 根据客户端的设置,模组会立即或在下次连接时将报告发送给服务器。
- 服务器存储该报告并发布一条可点击的聊天消息。
重要限制
服务器插件无法直接读取玩家的本地客户端日志或崩溃报告。
在没有 Fabric 客户端配套模组的情况下,FailureToLog 只能使用服务器可见的信息,例如:
- 登录拒绝原因
- 踢出原因
- 可用的服务器端异常描述
- 玩家名称
- UUID(如可用)
- 地址(如可用)
安装了 Fabric 模组后,FailureToLog 还可以接收客户端的断开连接屏幕标题和原因。
隐私说明
FailureToLog 存储服务器端的连接/错误详细信息。
Fabric 客户端报告可能包括:
- 断开连接屏幕标题
- 断开原因
- Minecraft 版本
- 玩家名称
- 服务器地址
- 时间戳
- FailureToLog 协议/插件版本
该系统不会有意收集完整的本地游戏日志或完整的崩溃报告。
推荐的平台描述
简短描述:
Paper 插件,用于在聊天中报告登录失败、错误断开连接以及可选的 Fabric 客户端断开连接报告。
详细描述:
FailureToLog 是一款 Paper 服务器插件,帮助服务器管理人员了解玩家为何无法连接或已被断开连接。
它检测失败的登录尝试和错误断开连接,分配错误代码,存储简短的服务器端报告,并发布一条可点击的聊天消息,使管理人员可以通过一个命令打开详细信息。
当与可选的 FailureToLog API Fabric 客户端模组搭配使用时,该插件还能接收客户端断开连接时的详细信息,为工作人员提供比服务器通常能自行看到的更多上下文。
建议标签
- Paper
- Server plugin
- Admin tools
- Logging
- Error reports
- Connection diagnostics
- Fabric integration
- Moderation tools
- Utility
构建输出
集成分发构建文件已复制到:
C:\Users\musek\IdeaProjects\dist
Paper 插件 jar 包:
FailureToLog-Paper-1.0-SNAPSHOT.jar
Fabric 客户端配套 jar 包:
FailureToLog-API-Fabric-1.0.0.jar
运行集成构建脚本:
C:\Users\musek\IdeaProjects\build-all-failure-to-log.bat
FailureToLog Paper Plugin
FailureToLog is a Paper server plugin that reports failed logins, error disconnects, and compatible Fabric client disconnect reports in server chat.
It helps server staff understand why a player failed to connect or was disconnected, then inspect a stored server-side error report through an in-game command.
What It Does
- Detects failed player login attempts.
- Detects server-side kicks and error disconnects.
- Changes error disconnect messages to a clearer FailureToLog message.
- Keeps normal join and normal quit behavior unchanged.
- Stores recent error logs for inspection.
- Adds clickable chat buttons for viewing error details.
- Receives client-side disconnect screen reports from the optional FailureToLog API Fabric mod.
- Provides commands for enabling/disabling the plugin, toggling log saving, viewing error codes, and opening stored logs.
Requirements
- Paper
26.1.2
- Java
25 or newer
Optional client companion:
- FailureToLog API Fabric mod for Minecraft
26.1.2
Installation
- Stop the server.
- Put the plugin jar into the server
plugins folder.
- Start the server.
- The plugin will create its config and log files automatically.
Plugin jar:
FailureToLog-Paper-1.0-SNAPSHOT.jar
Typical server folder:
plugins/FailureToLog
Configuration
Config file:
plugins/FailureToLog/config.yml
Default config:
enabled: true
save-logs: true
enabled
Turns FailureToLog behavior on or off.
enabled: true
save-logs
Controls whether error logs are saved to disk.
save-logs: true
When enabled, logs are saved to:
plugins/FailureToLog/logs.yml
Commands
Main command:
/failuretolog
Alias:
/ftl
Toggle Plugin
/failuretolog toggle
Turns FailureToLog on or off.
Requires:
failuretolog.admin
Toggle Log Saving
/failuretolog savelogs <on|off>
Examples:
/failuretolog savelogs on
/failuretolog savelogs off
Requires:
failuretolog.admin
View Error Codes
/failuretolog codes
Shows the full FailureToLog error code list.
View Error Log
/failuretolog log <id>
Shows a stored error report.
When an error is detected, FailureToLog posts a chat message with a clickable [View error] button. Clicking that button runs this command automatically.
Permissions
failuretolog.admin
Default:
op
Allows changing FailureToLog settings with:
/failuretolog toggle
/failuretolog savelogs <on|off>
Chat Message Format
Example:
Due to an error, PlayerName failed to connect. Error code: 600 (Bad client data) [View error]
For server-side kicks:
Due to an error, PlayerName lost connection. Error code: 500 (Server-side problem) [View error]
For Fabric client reports:
Due to an error, PlayerName reported a client-side disconnect. Error code: 1 (Unknown crash) [View error]
Normal joins and normal quits keep the server's default behavior.
Error Codes
FailureToLog includes these codes:
1: Unknown crash
6: Not whitelisted
7: Banned
9: Blacklisted
105: World chunk load failure
200: Server memory shortage
201: Client memory shortage
401: Authentication/session failure
408: Connection timeout
429: Connection throttled
500: Server-side problem
503: Server full
600: Bad client data
601: Unsupported client version
602: Resource pack failure
790: Mod or socket conflict
The plugin classifies errors from login results, kick reasons, server messages, and optional Fabric client reports. If an error cannot be classified, it uses:
1: Unknown crash
Fabric Client Integration
FailureToLog can receive extra client-side disconnect information from the optional FailureToLog API Fabric mod.
The plugin uses these Minecraft custom payload channels:
failuretolog:hello
failuretolog:client_log
Flow:
- Player joins the server.
- Server sends
failuretolog:hello.
- Compatible Fabric clients detect the FailureToLog server.
- If the client sees a disconnect screen, the Fabric mod stores the screen title and reason.
- The mod sends the report to the server immediately or on the next connection, depending on the client's setting.
- The server stores the report and posts a clickable chat message.
Important Limitations
A server plugin cannot directly read a player's local client logs or crash reports.
Without the Fabric client companion mod, FailureToLog can only use information visible to the server, such as:
- Login denial reason
- Kick reason
- Server-side exception wording, when available
- Player name
- UUID, when available
- Address, when available
With the Fabric mod installed, FailureToLog can also receive the client's disconnect screen title and reason.
Privacy Notes
FailureToLog stores server-side connection/error details.
Fabric client reports may include:
- Disconnect screen title
- Disconnect reason
- Minecraft version
- Player name
- Server address
- Timestamp
- FailureToLog protocol/plugin version
The system does not intentionally collect full local game logs or full crash reports.
Recommended Platform Description
Short description:
Paper plugin for reporting failed logins, error disconnects, and optional Fabric client disconnect reports in chat.
Long description:
FailureToLog is a Paper server plugin that helps staff understand why players failed to connect or were disconnected.
It detects failed login attempts and error disconnects, assigns an error code, stores a short server-side report, and posts a clickable chat message so staff can open the details with one command.
When paired with the optional FailureToLog API Fabric client mod, the plugin can also receive client-side disconnect screen details, giving staff more context than the server can normally see on its own.
Suggested Tags
- Paper
- Server plugin
- Admin tools
- Logging
- Error reports
- Connection diagnostics
- Fabric integration
- Moderation tools
- Utility
Build Output
Integrated distribution builds are copied to:
C:\Users\musek\IdeaProjects\dist
Paper plugin jar:
FailureToLog-Paper-1.0-SNAPSHOT.jar
Fabric client companion jar:
FailureToLog-API-Fabric-1.0.0.jar
Run the integrated build script:
C:\Users\musek\IdeaProjects\build-all-failure-to-log.bat
评论 0
登录后参与评分
还没有评论,来抢沙发吧