Yet Another Minecraft Image Placing Addon

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

Here are the Minecraft distributions where Yamipa should be able to run: | Minecraft version | Spigot | PaperMC | Purpur | Folia | |------------------:|:------:|:-------:|:------:|:-----:| | 1.16.x | ✅ | ✅ | ✅ | | | 1.17 & 1.17.1 | ✅ | ✅ | ✅ | | | 1.18 & 1.18.x | ✅ | ✅ | ✅ | | | 1.19 & 1.19.x | ✅ | ✅ | ✅ | | | 1.20 & 1.20.x | ✅ | ✅ | ✅ | ✅ | | 1.21 & 1.21.x | ✅ | ✅ | ✅ | ✅ |

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:

command-name: yamipa              # Name of the root command
command-aliases: [image, images]  # Aliases for the root command, can be an empty list
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 "https://www.example.com/a/b/c/1234.jpg" "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 features exposed to players, permissions are the way to go!

Yamipa defines the following permissions:

| Permission | 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 command | | yamipa.command.list | OPs | To use the /image list command | | yamipa.command.place | OPs | To use the /image place command | | yamipa.command.place-at | OPs | To use the /image place-at 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.remove-at | OPs | To use the /image remove-at command | | 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.

Yamipa

Install / Use

README