Yamipa - 图片放置插件

Yet Another Minecraft Image Placing Addon (Yamipa)

Yamipa 是一款 Spigot 插件，允许玩家在 Minecraft 服务器的任何表面上放置图片（甚至是动态的！），而无需安装任何本地客户端模组。它专为性能和兼容性设计，即使配置最低的服务器也能流畅运行。

💡安装

• 下载最新版本的 JAR 文件。
• 将其复制到 Minecraft 服务器的 plugins 目录中，就像安装其他插件一样。安装完成！

💡要求

在安装 Yamipa 前，请确保满足以下要求

• 服务端: Spigot / PaperMC / 其分支版本 1.16 或更高，或 Folia。
• 依赖: ProtocolLib v5.3.0 或更高版本。

🎮配置

Yamipa 开箱即用。默认情况下，它会在 plugins/YamipaPlugin 目录下创建以下文件和目录：

• cache: 包含缓存图像的目录，用于加速渲染过程。请勿修改其内容。
• images: 这是您存放想要放置在 Minecraft 世界中的图像文件的目录。
• images.dat: 存储服务器中所有已放置图像的列表和属性（例如坐标）的文件。请勿修改其内容。

您可以通过在插件配置目录中创建 config.yml 文件来更改这些文件的路径。如果不指定，以下是默认配置值：

verbose: false # 设置为 "true" 以启用更详细的日志记录
animate-images: true # 设置为 "false" 以禁用 GIF 支持
images-path: images # 图像目录的路径
cache-path: cache # 缓存目录的路径
data-path: images.dat # 已放置图像数据库文件的路径
allowed-paths: null # 设置为正则表达式以限制玩家可访问的图像
max-image-dimension: 30 # 图像允许的最大宽度或高度（以方块为单位）

允许的路径

变量 allowed-paths 是一个正则表达式，用于确定玩家是否被允许查看或下载图像文件。如果相对于 images 目录的期望路径与此表达式匹配，则允许玩家继续操作。

• 如果 allowed-paths 是空字符串 ("") 或 null，则玩家可以读取任何图像文件或下载到 images 目录内的任何路径。
• 此正则表达式必须遵循 Java 使用的语法。您可以使用在线工具（如 regex101）提前测试您的表达式。
• 您可以使用以下特殊令牌：

- `#player#`: 玩家名称

- `#uuid#`: 玩家 UUID（带连字符）

例如，如果您希望服务器中的每个玩家都有自己的子目录来存储只有他们自己能访问的文件，外加一个共享的公共目录，可以使用以下 allowed-paths 值：

^(private/#player#|public)/

这样，玩家 "john" 可以查看位于 private/john/something.jpg 的图像文件，但 "jane" 则不能。

重要提示：这些限制也适用于 NPC、命令方块或服务器控制台等其他实体。但是，在非玩家上下文中，特殊令牌将始终匹配（例如，#player# 将被解释为 .+）。

玩家变量

某些权限插件（如 LuckPerms）允许服务器管理员为实体分配键值对，就像分配权限一样。这对于为不同玩家或组授予不同能力非常有用。

Yamipa 会查找以下变量，如果找到，它们将覆盖适用于所有玩家的默认配置值：

| 变量 (键) | 覆盖项 | 描述 |

| :--- | :--- | :--- |

| yamipa-allowed-paths | allowed-paths | 限制可访问 images 目录中哪些路径的正则表达式 |

| yamipa-max-image-dimension | max-image-dimension | 此玩家或组可使用的图像和图像物品的最大宽度或高度 |

例如，如果您想仅为 "test" 玩家限制图像大小为 5x5 方块，可以运行以下命令：

# 使用 LuckPerms
/lp user test meta set yamipa-max-image-dimension 5
# 使用 GroupManager
/manuaddv test yamipa-max-image-dimension 5

🔧使用

此插件添加了以下命令

• /image clear <x z world> <r> [<placed-by>]: 移除原点半径 r 方块内的所有已放置图像。
• /image describe: 显示已放置图像的详细信息。
• /image download <url> <filename>: 从 URL 下载图像并放入 images 目录。
• /image give <player> <filename> <amount> <w> [<h>] [<flags>]: 给予玩家可以稍后放置的图像物品。
• /image list [<page>]: 列出 images 目录中所有可用的文件。
• /image place <filename> <w> [<h>] [<flags>]: 启动 UI 对话框以放置一个宽 w 高 h 方块的图像。
• /image place-at <x y z world> <face> <filename> <w> [<h>] [<flags>]: 在给定坐标处放置图像。
• /image remove: 启动 UI 对话框以从世界中移除已放置的图像（不删除图像文件）。
• /image remove-at <x y z world> <face>: 移除给定坐标处的图像。
• /image top: 列出放置图像最多的玩家。

示例

• 显示帮助：/image
• 从 URL 下载图像并以另一个名称保存：/image download "https://www.example.com/a/b/c/1234.jpg" "imagename.jpg"
• 给予 "TestPlayer" 10 个 "test.jpg" 图像的图像物品（3x5 方块）：/image give TestPlayer "test.jpg" 10 3 5
• 给予 "TestPlayer" 10 个移除时不会掉落图像物品的图像物品：/image give TestPlayer "test.jpg" 10 3 5 -DROP
• 启动 UI 对话框放置一个宽度为 3 方块、高度自动的图像：/image place "imagename.jpg" 3
• 启动 UI 对话框放置一个 3x2 方块的图像：/image place "imagename.jpg" 3 2
• 启动 UI 对话框放置一个在黑暗中发光的图像：/image place "imagename.jpg" 3 2 +GLOW
• 在指定方块处朝北放置图像，无需玩家交互：/image place-at 100 200 300 world NORTH "imagename.jpg" 3
• 启动 UI 对话框移除一个已放置的图像，同时保留原始文件：/image remove
• 移除指定方块处的图像，无需玩家交互：/image remove-at 100 200 300 world NORTH
• 移除出生点周围 5 方块半径内的所有已放置图像：/image clear 0 0 world 5
• 移除下界中 "EvilPlayer" 在半径 100 方块内放置的所有图像：/image clear 50 70 world_nether 100 EvilPlayer
• 移除所有遗留的已放置图像（没有 "placed by" 元数据）：/image clear 0 0 world 9999999 00000000-0000-0000-0000-000000000000

⭐权限

如果您希望对可以使用特定命令集的玩家进行更精细的控制，权限是您的不二之选！

Yamipa 定义了以下权限

| 命令 | 默认 | 描述 |

| :--- | :--- | :--- |

| yamipa.command.clear | OPs | 使用 /image clear 命令 |

| yamipa.command.describe | OPs | 使用 /image describe 命令 |

| yamipa.command.download | OPs | 使用 /image download 命令 |

| yamipa.command.give | OPs | 使用 /image give 命令 |

| yamipa.command.list | OPs | 使用 /image list 命令 |

| yamipa.command.place | OPs | 使用 /image place 命令 |

| yamipa.command.remove | OPs | 使用 /image remove 命令 |

| yamipa.command.remove.own | OPs | 同上，但仅限同一玩家放置的图像 |

| yamipa.command.top | OPs | 使用 /image top 命令 |

| yamipa.item.place | 所有玩家 | 放置图像物品 |

| yamipa.item.remove | 所有玩家 | 移除图像物品（具有 REMO 标志的） |

| yamipa.item.remove.own | 所有玩家 | 同上，但仅限同一玩家放置的图像 |

请注意，权限以树状结构工作。这意味着如果您授予一个权限，默认情况下其子权限也会被授予。例如，您可以使用 yamipa.command.* 授予所有命令的访问权限。同样，如果您授予 yamipa.command.remove，权限 yamipa.command.remove.own 也会被授予。

您可以使用权限插件（如 LuckPerms 或 GroupManager）来更改授予这些命令的角色或玩家。这两个插件都经过测试可以与 Yamipa 配合使用，尽管任何类似的插件都应该可以正常工作。

区域保护

在大型服务器中，让玩家随意放置和移除图像可能不是最明智的做法。对于这些情况，Yamipa 与其他允许创建和管理世界区域的 Bukkit 插件兼容。如果您有一个或多个此类插件，Yamipa 将自动相应地应用权限，只允许玩家在他们可以放置或移除方块的地方放置或移除图像，无需额外配置。

支持的插件包括

• WorldGuard
• GriefPrevention

✨标志

此插件的图像具有一组称为“标志”的布尔属性，用于修改其行为。可能的值包括：

• ANIM (可动画): 图像是否应动画化，当您不希望 GIF 图像播放时很有用。
• REMO (可移除): 图像是否可以被任何玩家通过左键单击移除。
• DROP (可掉落): 图像被任何玩家移除时是否会掉落一个图像物品。
• GLOW (发光): 图像是否在黑暗中发光（仅在 Minecraft 1.17 及以上版本有效）。

默认情况下，使用 /image place 命令放置的图像只有 ANIM 标志。同样，使用 /image give 命令颁发的图像物品具有 ANIM、REMO 和 DROP 标志。

可以通过 "flags" 参数修改默认标志。要添加标志到默认集合中，请使用 +{FLAG_NAME}（例如 +GLOW）；要移除标志，请使用 -{FLAG_NAME}（例如 -ANIM）。您可以通过逗号分隔来修改多个标志（例如 +GLOW,-ANIM）。

❓工作原理

您可能已经猜到，Minecraft 本身不支持放置图像文件。Yamipa 通过使用两个内置功能（物品展示框和地图）来渲染自定义图像，从而绕过此限制。

然而，由于物品展示框是实体（并且这些实体会在服务器中造成大量卡顿），Yamipa 实际上并不会在您的世界中创建任何实体。相反，它通过发送精心制作的网络数据包来“欺骗”玩家的客户端，让他们认为那里有一个放置的物品展示框，而实际上并没有。

对于动态图像（即 GIF），Yamipa 将所有动画帧发送给玩家（这会占用相当大的带宽），然后每隔几毫秒发送一个微小的数据包，告诉客户端切换到下一个动画步骤（即地图）。

重要提示：由于 Yamipa 会在玩家靠近图像时在内存中存储图像的缓存副本，以防需要在不影响性能的情况下再次发送它，因此您的服务器需要有一些备用 RAM 来处理此问题。经验法则是每个唯一加载的图像占用 100KB（动态图像为 1MB）。“唯一”意味着如果相同尺寸的同一图像被放置多次，它只算作一个实例。

🔧其他信息

bStats

此插件使用 bStats 匿名报告安装数量。如果您不喜欢这样，可以随时通过在 bStats 配置文件中添加 enabled: false 来禁用它（没关系，我们理解）。

许可证

Yamipa 根据 MIT 许可证授权。