ImageFrame/README.md

ImageFrame

https://www.spigotmc.org/resources/106031/
https://modrinth.com/plugin/imageframe
https://hangar.papermc.io/LOOHP/ImageFrame

Put images on maps and walls!

More information (screenshots, commands, permissions) about the plugin can be found on the Spigot page linked above.

Creating Images In-Game

The main command is /imageframe (aliases: /iframe, /if, /frame). All creation commands are op-only by default. Sizes are measured in maps — one map fills one item frame block, so a 4 x 3 image needs a 4-wide by 3-tall grid of item frames.

Image URLs are not accepted — create, overlay and refresh reject any link. Images come from:

• The images folder — drop image files (png, jpg, gif, webp, …) into plugins/ImageFrame/images/ and pass the file name, e.g. /imageframe create poster poster.png selection. No restart needed; new files show up in tab completion straight away. File names can't contain spaces.
• The bundled maps (below).
• The upload service, when UploadService.Enabled is true in config.yml — pass upload instead of a file name, then open the link the plugin sends you to upload a file.

Quick way — create straight onto a wall

1. Place a grid of item frames on the wall (e.g. 4 wide × 3 tall).
2. Run /imageframe select, then left-click one corner frame and right-click the opposite corner frame to select the whole grid.
3. Run /imageframe create <name> <file> selection, where <file> is an image in plugins/ImageFrame/images/.

The image is sized to your selection and placed into the frames automatically.

Manual way — create, then place yourself

1. /imageframe create <name> <file> <width> <height> — creates the image map (width/height in maps).
2. Put it on frames one of two ways:
   • /imageframe get <name> — gives you the map item(s); place each on the item frames in order (left→right, top→bottom).
   • or select a frame grid (as above) and run /imageframe get <name> selection to auto-fill it.

Using bundled maps

Bundled maps are canonical maps shipped inside the plugin jar, under maps/. They are re-rendered from the jar on every startup and never touch the plugin data folder, so they survive data wipes — their map ids are kept so existing item frames in the world keep pointing at the right maps, the same way LaunchPads-OG preserves pad locations in its config.

Bundled maps are owned by Console. Anyone with access can see them with /imageframe list and use them by name:

• /imageframe get <name> selection, or reference them explicitly as Console:<name>.

Adding a bundled map

It works like the images folder: drop the file in and it becomes a map named after the file.

1. Optional, to try it out live first: put the image in plugins/ImageFrame/images/ and run imageframe create Console:<name> <file> <width> <height> from the console, using the file name without its extension as <name>. Refresh or recreate it until it looks right, and place it on frames if you like.
2. Copy the image into common/src/main/resources/maps/, rebuild the jar, deploy it and restart. No maps.yml entry is needed.

On first load the server sets the map up:

• If you did step 1, the bundled map takes over that map's size, dithering and map ids, and the copy in the data folder is removed. Frames you already placed keep working.
• Otherwise the size comes from the image at 128 pixels per map (a 512×384 image becomes 4×3), and the server assigns new map ids. Images that would go over MaxSize are skipped with a console message.

The server saves what it decided to imageframe-bundled-maps.yml in the main world folder. It stays the same on every restart and survives plugin data folder wipes, so there is nothing to copy back. Keep that file with the world.

Replacing a bundled image with a new file of the same name keeps its size and map ids, and frames update after the restart. Animated GIFs are supported. File names can't contain spaces or colons.

To override the name, size or dithering, or to pin exact map ids, add an entry to common/src/main/resources/maps.yml (see the comments at the top of that file). Never change the MapIds of an existing map — item frames in the world reference those ids.

Useful extras

• /imageframe info <name> — shows a map's size (handy to build a matching frame grid).
• /imageframe refresh <name> [file] — re-renders an existing map. Maps made from the images folder re-read their file, so edit the image in place and refresh to update it live. Pass a different file name (or upload) to swap the image. Bundled maps re-render from the jar. Maps whose stored source is a web URL can no longer be refreshed.
• Optional flags on create/get: a dithering type, and combined/separated.

Behaviour of this fork

• Image URLs are not accepted anywhere; the old RestrictImageUrl whitelist is gone.
• Images are stretched to fill the whole frame grid (edge to edge) instead of being letterboxed with a transparent border. Match your frame grid's width:height to the image's aspect ratio to avoid distortion.
• Item frames filled by the plugin are automatically made invisible, so neighbouring tiles join seamlessly with no thin border between them.

Built against Spigot

Built against Spigot's API (required mc versions are listed on the spigot page above). Plugins built against Spigot usually also work with Paper.

Development Builds

• Jenkins

Maven

<repository>
  <id>loohp-repo</id>
  <url>https://repo.loohpjames.com/repository</url>
</repository>

<dependency>
  <groupId>com.loohp</groupId>
  <artifactId>ImageFrame</artifactId>
  <version>VERSION</version>
  <scope>provided</scope>
</dependency>

Replace VERSION with the version number.

Official Addons

• ImageFrameClient (Complementary client mod for servers with ImageFrame to display HD and full color images)

Partnerships

Server Hosting

Use the link or click the banner below to get a 25% discount off your first month when buying any of their gaming servers!
It also supports my development, take it as an alternative way to donate while getting your very own Minecraft server as well!

P.S. Using the link or clicking the banner rather than the code supports me more! (Costs you no extra!)

https://www.bisecthosting.com/loohp