Ghost

将网络中其他服务器的玩家绘制为客户端幽灵，每位玩家可单独开关。

私有v0.1社交

依赖TypeWriter0.9.0-beta-177 (BTC build)MySQL (TypeWriter extension)Redis or ValkeyPacketEventsMiniPlaceholdersUiCore (TypeWriter extension)可选

专为 BornToCraft 服务器网络打造。此扩展仅作参考文档，不对外分发。

支持

概览

在由多台后端服务器组成的网络中，位于不同服务器上同一张地图里的两位玩家无法互相看到。Ghost 在视觉上解决了这个问题：每台服务器通过 Redis 发布其玩家的位置、朝向和皮肤，其他服务器则使用数据包将他们绘制为玩家形状的幽灵。世界中不会添加任何东西，幽灵也没有服务端实体，因此无法被击中、推动或锁定为目标。

每位玩家自行决定是否看到幽灵。该选择存储在一个 TypeWriter 事实中，因此在重启后依然有效，并会随玩家在服务器之间移动。幽灵只会出现在 MySQL 配置中 redis.group-id 相同的服务器之间，并且服务器从不会把自己的玩家绘制为幽灵。

功能

• 跨服务器幽灵 — 其他后端服务器的玩家会带着其皮肤、位置和朝向出现。
• 仅数据包渲染 — 基于 PacketEvents 构建，不会创建服务端实体。
• 兼容 Folia — 每次捕获和每次渲染都在相关玩家的调度器上运行。
• 可见性开关 — /ghost toggle、TypeWriter 动作或菜单按钮可按玩家开启和关闭幽灵。
• 持久化的选择 — 该偏好是一个可持久化的事实，在各服务器之间共享。
• 服务器标签 — 可配置的后缀（例如 [survival-2]）显示幽灵来自哪里。
• 限制 — 可视距离、每位观看者的最大幽灵数、更新频率和世界过滤将开销控制在一定范围内。
• 名牌 — 如果安装了 UiCore，幽灵头顶会有一个名牌。
• 占位符 — 可见性和幽灵数量，用于 MiniMessage 文本。

安装

1. 在每台服务器上安装 PacketEvents。
2. 在每台服务器上安装 MySQL 扩展并启用 Redis（或 Valkey）。为每台服务器设置唯一的 redis.server-name 和相同的 redis.group-id。Ghost 没有自己的 Redis 设置。
3. 将 Ghost 的 JAR 放入 plugins/Typewriter/extensions/ 并重启。文件 plugins/Typewriter/ghost_player/config.yml 会在首次启动时创建。
4. 将权限 typewriter.ghost.use 授予可以使用 /ghost 的玩家。没有权限插件时，只有管理员可以使用。
5. 可选：安装 UiCore，以便在幽灵上方绘制名牌。

快速上手

让玩家通过菜单或任务 NPC 切换幽灵：

1. 在 TypeWriter 网页面板中，打开一个页面，添加一个 Ghost Visibility Fact 事实条目。保留其默认的 id ghost_visibility_fact：扩展就是通过这个 id 读写该事实的。
2. 在序列或菜单物品上添加一个 Ghost Toggle Visibility 动作。在 showMessage 和 hideMessage 中填入 MiniMessage 文本，或留空以使用默认消息。
3. 可选：在 Ghost Visibility 事实上添加一个条件（值 1 表示可见，0 表示隐藏），以便在菜单中显示不同的图标。
4. 发布，并加入同一分组的两台服务器。每位玩家都会把对方看作带有服务器后缀的幽灵。

单台服务器上看不到幽灵

服务器会忽略它自己的广播。要进行测试，请启动两台 redis.group-id 相同、redis.server-name 不同的服务器，并站在允许匹配的世界中（见下文）。

工作原理

每台服务器会按配置的频率发布每位本地玩家的快照，外加一个心跳，让空闲的玩家保持存活。当幽灵的所有者离开，或在 timeout-millis 内没有收到更新时，幽灵就会消失。每条消息都带有会话 id 和序列号，因此迟到或重复的消息会被忽略。

当观看者启用了幽灵、世界兼容、幽灵在 view-distance 范围内，并且观看者的幽灵数少于 max-ghosts-per-viewer（最近的优先）时，才会为该观看者绘制幽灵。

配置

该文件为 plugins/Typewriter/ghost_player/config.yml。其 schema-version 必须为 1 或 2。

schema-version: 2

settings:
  update-rate: 4
  server-suffix: " <gray>[%server%]</gray>"
  team-prefix: "Ghosts"
  view-distance: 64.0
  max-ghosts-per-viewer: 128
  timeout-millis: 10000
  allowed-worlds:
    - "world"
    - "dungeon_"
    - "hub"

messages:
  no-permission: "<red>You do not have permission to use ghost visibility."
  players-only: "<red>This command can only be used by a player."
  enabled: "<green>Ghost visibility enabled."
  disabled: "<yellow>Ghost visibility disabled."
  usage: "<gray>Usage: <white>/ghost toggle"

command:
  permission: "typewriter.ghost.use"

键	含义
settings.update-rate	两次位置捕获之间的 tick 数。限制在 1 到 20。
settings.server-suffix	添加在幽灵名称之后的 MiniMessage 文本。%server% 会变成来源服务器的名称。
settings.team-prefix	为每个来源服务器显示的计分板队伍的前缀。
settings.view-distance	最大距离（格），范围 0 到 256。0 表示禁用距离限制。
settings.max-ghosts-per-viewer	每位观看者绘制的幽灵数，范围 0 到 2000。0 表示不显示。
settings.timeout-millis	在移除幽灵之前没有更新的延迟，范围 2000 到 120000。
settings.allowed-worlds	在各服务器之间被视为同一张地图的世界名称模式。最多 64 项。
messages.*	/ghost 使用的 MiniMessage 文本。
command.permission	/ghost 所需的权限。

世界。 当观看者和幽灵所在的世界名称相同，或者两个世界名称都包含 allowed-worlds 中的同一个模式（例如 dungeon_ 匹配 dungeon_1 和 dungeon_2）时，幽灵才可见。距离只能在同一个世界内测量，因此当 view-distance 大于 0 时，来自名称不同的世界的幽灵会被隐藏。如果你依赖模式匹配，请将 view-distance 设为 0。

Redis 连接、服务器名称和分组 id 都读取自 MySQL 配置。该文件只会在启动时读取一次：编辑后请重启服务器。

命令

命令	说明
/ghost toggle	为你自己开启或关闭幽灵可见性。

别名：/ghosts、/ghostplayer。仅限玩家使用。权限为 command.permission，默认是 typewriter.ghost.use。

权限

权限	授予
typewriter.ghost.use	/ghost toggle。名称可通过 command.permission 更改。该权限没有注册默认值，因此需要被授予。

Ghost Toggle Visibility 动作不会检查此权限。

占位符

用于 MiniMessage 文本的 MiniPlaceholders 标签。不支持 PlaceholderAPI。

占位符	返回
<ghost_visibility>	玩家能看到幽灵时为 true，否则为 false。
<ghost_visible>	玩家能看到幽灵时为 1，否则为 0。
<ghost_count>	此服务器当前已知的远程幽灵数量。

条目

2 个条目，由扩展源码生成。

动作1

• Ghost Toggle VisibilityToggle Ghost Visibility

事实1

• Ghost Visibility FactGhost Visibility

故障排查

没有出现任何幽灵。 请按以下顺序检查：两台服务器使用相同的非空 redis.group-id 和不同的 redis.server-name 值；Redis 已连接（否则日志会显示 "BTC RedisService is not connected; Ghost updates will remain inactive"）；观看者已启用幽灵；两位玩家位于兼容的世界中（世界名称相同，或共享某个 allowed-worlds 模式且 view-distance: 0）。

同一服务器的玩家永远不会显示为幽灵。 这是预期行为：服务器会忽略它自己发布的消息。

扩展启动失败，提示 "Unsupported Ghost custom config schema"。 ghost_player/config.yml 中的 schema-version 超出了 1..2 的范围。请将其设为 2。

扩展因服务器名称错误而失败。 MySQL 配置中的 redis.server-name 只能包含字母、数字、.、_ 或 -，最多 64 个字符。

/ghost 提示你没有权限。 该权限没有默认值。请使用你的权限插件授予 typewriter.ghost.use（或你在 command.permission 中设置的权限）。

幽灵在几秒钟后消失。 在 timeout-millis 内没有收到更新。请检查 Redis 延迟，以及来源服务器是否在以相同的 redis.group-id 运行 Ghost。

幽灵没有名牌。 名牌来自 UiCore。请在观看者所在的服务器上安装它。没有它时，只会显示名称中的服务器后缀。

相关扩展

• MySQL — 拥有 Ghost 所使用的 Redis 连接、服务器名称和分组 id。
• UiCore — 安装后会在幽灵上方绘制名牌。