Yamipa 是一款 Spigot 插件,允许玩家在 Minecraft 服务器的任何表面上放置图片(甚至动画图片!),而无需在本地客户端安装任何模组。
它的设计兼顾了性能与兼容性,因此即使是配置较低的服务端也能顺畅运行。
安装
下载最新版本的 JAR 文件,并将其复制到 Minecraft 服务器的 "plugins" 目录中,操作方式与其他插件相同。就这样!
要求
在安装 Yamipa 之前,请确保满足以下要求:
- Spigot/PaperMC/forks 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 或 max-image-dimension 值的更多信息,请参阅 玩家变量 部分。
允许的路径
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#" 将被解释为 ".+")。
bStats
该库使用 bStats 匿名报告安装数量。如果你不喜欢这样做,可以随时通过向 bStats 配置文件 添加 enabled: false 来禁用它(没关系,不会有任何芥蒂)。
用法
此插件添加了以下命令:
/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 对话框以放置大小为 wxh 方块的图片。
/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 "" "imagename.jpg"
- 向 "TestPlayer" 发放 10 个 "test.jpg" 图片物品(3x5 格)
/image give TestPlayer "test.jpg" 10 3 5
- 向 "TestPlayer" 发放 10 个 "test.jpg" 图片物品,移除时不会掉落图片物品
/image give TestPlayer "test.jpg" 10 3 5 -DROP
- 启动 UI 对话框以放置宽度为 3 格且高度自动的图片
/image place "imagename.jpg" 3
- 启动 UI 对话框以放置宽 3 格、高 2 格的图片
/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
- 清除下界中半径 100 格内由 "EvilPlayer" 放置的所有图片
/image clear 50 70 world_nether 100 EvilPlayer
- 清除所有旧版放置的图片(不含“由...放置”元数据)
/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 配合使用,虽然任何类似的插件也应该能正常工作。
玩家变量
一些权限插件(如 LuckPerms)允许服务器操作员将键值对分配给实体,就像分配权限一样。这对于向不同玩家或群组授予不同功能非常有用。
Yamipa 会查找以下变量,如果找到,它们将覆盖适用于所有玩家的默认配置值:
| 变量(键) |
覆盖 |
描述 |
yamipa-allowed-paths |
allowed-paths |
限制可访问的图片目录中哪些路径的正则表达式 |
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
保护区域
在大型服务器中,允许玩家随意放置和移除图片可能并不是最明智的做法。针对这种情况,Yamipa 兼容其他允许创建和管理世界区域的 Bukkit 插件。如果您安装了此类插件之一或多个,Yamipa 将自动相应地应用权限,仅允许玩家在他们可以放置或移除方块的地方放置或移除图片,无需额外配置。
支持的插件有:
标志(Flags)
本插件生成的图片具有一组称为“标志”的布尔属性,用于修改其行为。可能的取值如下:
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 都会在内存中缓存一份图像的副本,以防需要再次发送而不影响性能。因此,你的服务器需要预留一定的空闲内存来处理这一过程。
这里的经验法则是每张唯一加载的图片占用 100K(动画图片为 1MB)。所谓“唯一”是指,如果同一张相同尺寸的图片被多次放置,它仅计为一个实例。
许可证
Yamipa 在 MIT 许可证 下获得许可。
Yamipa is a Spigot plugin that allows players to place images (even animated!) on any surface in your Minecraft server without having to install any local client mod.
It is designed with performance and compatibility in mind, so even the most low-specs servers should be able to run it.
Installation
Download the JAR file for the latest release and copy it to the "plugins" directory of your Minecraft server as you'll do with any other plugin. That's it!
Requirements
Before installing Yamipa make sure you meet the following requirements:
- Spigot/PaperMC/forks 1.16 or higher or Folia
- ProtocolLib v5.3.0 or higher
Configuration
Yamipa is ready-to-go right out of the box. By default, it creates the following files and directories under the plugins/YamipaPlugin directory:
cache: A directory containing cached images to speed up the rendering process. You shouldn't modify its contents.
images: This is the directory where you put the image files you want to place in your Minecraft world.
images.dat: A file holding the list and properties (e.g. coordinates) of all placed images in your server. You shouldn't modify its contents.
You can change the path of these files by creating a config.yml file in the plugin configuration directory. Here are the default configuration values if you don't specify them:
verbose: false # Set to "true" to enable more verbose logging
animate-images: true # Set to "false" to disable GIF support
images-path: images # Path to images directory
cache-path: cache # Path to cache directory
data-path: images.dat # Path to placed images database file
allowed-paths: null # Set to a RegExp to limit accessible images to players
max-image-dimension: 30 # Maximum width or height in blocks allowed in images
For more information on how to set a different allowed-paths or max-image-dimension value per player, see the Player variables section.
Allowed paths
The variable allowed-paths is a regular expression that determines whether a player is allowed to see or download an image file. If the desired path relative to the images directory matches this expression, then the player is allowed to continue.
If allowed-paths is an empty string ("") or null, then the player can read any image file or download to any path inside the images directory.
This regular expression must follow the syntax used by Java. You can test your expression beforehand using an online tool like regex101. In addition, you can make use of the following special tokens:
#player#: Player name
#uuid#: Player UUID (with hyphens)
For example, if you want every player in your server to have their own subdirectory for storing files that only they can access, plus a shared public directory, you can use the following allowed-paths value:
^(private/#player#|public)/
That way, the player "john" can see the image file at "private/john/something.jpg", but "jane" cannot.
IMPORTANT!
Note that these restrictions also apply to other entities like NPCs, command blocks or the server console. However, special tokens will always match in non-player contexts (e.g., "#player#" will be interpreted as ".+").
bStats
This library uses bStats to anonymously report the number of installs. If you don't like this, feel free to disable it at any time by adding enabled: false to the bStats configuration file (it's ok, no hard feelings).
Usage
This plugin adds the following commands:
/image clear <x z world> <r> [<placed-by>]: Remove all placed images in a radius of r blocks around an origin.
/image describe: Show detailed information about a placed image.
/image download <url> <filename>: Download an image from a URL and place it in the images directory.
/image give <player> <filename> <amount> <w> [<h>] [<flags>]: Give image items that can be placed later to a player.
/image list [<page>]: List all available files in the images directory.
/image place <filename> <w> [<h>] [<flags>]: Start a UI dialog to place an image of size wxh blocks.
/image place-at <x y z world> <face> <filename> <w> [<h>] [<flags>]: Place an image at the given coordinates.
/image remove: Start UI dialog to remove a placed image from the world without deleting the image file.
/image remove-at <x y z world> <face>: Remove the image at the given coordinates.
/image top: List players with the most placed images.
Examples
- Show help
/image
- Download an image from a URL and save it with another name
/image download "" "imagename.jpg"
- Give 10 image items to "TestPlayer" for the "test.jpg" image (3x5 blocks)
/image give TestPlayer "test.jpg" 10 3 5
- Give 10 image items to "TestPlayer" that will not drop an image item when removed
/image give TestPlayer "test.jpg" 10 3 5 -DROP
- Start the UI dialog to place an image with a width of 3 blocks and auto height
/image place "imagename.jpg" 3
- Start the UI dialog to place a 3-blocks wide and 2-blocks high image
/image place "imagename.jpg" 3 2
- Start the UI dialog to place an image that glows in the dark
/image place "imagename.jpg" 3 2 +GLOW
- Place an image at a given block, facing north, without player interaction
/image place-at 100 200 300 world NORTH "imagename.jpg" 3
- Start the UI dialog to remove a placed image while keeping the original file
/image remove
- Remove a placed image at a given block, without player interaction
/image remove-at 100 200 300 world NORTH
- Remove all placed images in a radius of 5 blocks around the spawn
/image clear 0 0 world 5
- Remove all images placed by "EvilPlayer" in a radius of 100 blocks in the nether
/image clear 50 70 world_nether 100 EvilPlayer
- Remove all legacy placed images (without "placed by" metadata)
/image clear 0 0 world 9999999 00000000-0000-0000-0000-000000000000
Permissions
If you want more granular control over the players who can use a particular set of commands, permissions are the way to go!
Yamipa defines the following permissions:
| Command |
Default |
Description |
yamipa.command.clear |
OPs |
To use the /image clear command |
yamipa.command.describe |
OPs |
To use the /image describe command |
yamipa.command.download |
OPs |
To use the /image download command |
yamipa.command.give |
OPs |
To use the /image give download |
yamipa.command.list |
OPs |
To use the /image list command |
yamipa.command.place |
OPs |
To use the /image place command |
yamipa.command.remove |
OPs |
To use the /image remove command |
yamipa.command.remove.own |
OPs |
Same as previous, but only for images placed by the same player |
yamipa.command.top |
OPs |
To use the /image top command |
yamipa.item.place |
All players |
To place image items |
yamipa.item.remove |
All players |
To remove image items (that have the REMO flag) |
yamipa.item.remove.own |
All players |
Same as previous, but only for images placed by the same player |
Note that permissions work as a tree. This means that if you grant a permission, by default its children will also be granted. For instance, you can grant access to all commands with yamipa.command.*. Similarly, if you grant the yamipa.command.remove, the permission yamipa.command.remove.own will also be granted.
You can change which roles or players are granted these commands by using a permission plugin, such as LuckPerms or GroupManager. Both these plugins have been tested to work with Yamipa, although any similar one should work just fine.
Player variables
Some permission plugins like LuckPerms allow server operators to assign key-value pairs to entities as if they were permissions. This is useful for granting different capabilities to different players or groups.
Yamipa looks for the following variables which, if found, override the default configuration value that applies to all players:
| Variable (key) |
Overrides |
Description |
yamipa-allowed-paths |
allowed-paths |
Regular expression that limits which paths in the images directory are accessible |
yamipa-max-image-dimension |
max-image-dimension |
Maximum width or height of images and image items issued by this player or group |
For example, if you want to limit the image size to 5x5 blocks just for the "test" player, you can run this command:
# Using LuckPerms
/lp user test meta set yamipa-max-image-dimension 5
# Using GroupManager
/manuaddv test yamipa-max-image-dimension 5
Protecting areas
In large servers, letting your players place and remove images wherever they want might not be the most sensible idea. For those cases, Yamipa is compatible with other Bukkit plugins that allow creating and managing world areas. If you have one or more of such plugins, Yamipa will automatically apply permissions accordingly and only let players place or remove images where they can place or remove blocks, no additional configuration required.
The supported plugins are:
Flags
Images from this plugin have a set of boolean attributes called "flags" that modify its behavior. Possible values are:
ANIM (animatable): Whether an image should be animated or not, useful when you don't want a GIF image to play.
REMO (removable): Whether an image can be removed by any player by left-clicking it.
DROP (droppable): Whether an image drops an image item when is removed by any player.
GLOW (glowing): Whether an image glows in the dark (only works on Minecraft 1.17 and above).
By default, images placed with the "/image place" command only have the ANIM flag. Similarly, image items issued with the "/image give" command have ANIM, REMO and DROP flags.
Default flags can be modified through the "flags" argument. To add a flag to the default ones use "+{FLAG_NAME}" (e.g. +GLOW), and to remove it use "-{FLAG_NAME}" (e.g. -ANIM). You can modify multiple flags separating them with commas (e.g. +GLOW,-ANIM).
How does it work?
As you may have already guessed, Minecraft does not support the placing of image files. Yamipa bypasses this limitation by using two built-in features (item frames and maps) to render custom images.
However, because item frames are entities (and these cause a lot of lag in a server), Yamipa does not actually create any entity in your world. Instead, it tricks your players' clients into thinking there's a placed item frame where there isn't by sending crafted network packets.
In the case of animated images (i.e. GIFs), Yamipa sends all animation frames to the player (which takes a decent amount of bandwidth) and then sends a tiny packet telling the client to switch to the next animation step (i.e. map) every few milliseconds.
IMPORTANT!
Because Yamipa stores a cached copy of an image in memory whenever a player is near it just in case it needs to send it again without compromising performance, your server needs to have a bit of spare RAM to handle this.
The rule of thumb here is 100K per unique loaded image (1MB for animated images). Unique means if the same image with same dimensions is placed multiple times it only counts as one instance.
License
Yamipa is licensed under the MIT License.
评论 0
登录后参与评分
还没有评论,来抢沙发吧