All documentation
Documentation

HyperAds

Clickable image billboards built from item frames and maps, with a glowing hover outline. No resource pack, no dependencies.

v1.0.1 Spigot or Paper 1.20+Java 17+

Quick start

  1. Drop the jar in plugins/ and restart the server.
  2. Put your images (PNG, JPG, BMP or GIF) in plugins/HyperAds/images/.
  3. Stand near a flat wall and run /ha create myad, then click two opposite corner blocks of the area to cover.
  4. Set a glow color with /ha edit myad color RED and a click command with /ha edit myad command console say hi %player%.
  5. Not sure how the maps line up? Run /ha test to place a numbered 4x4 test billboard.

#Overview

HyperAds turns any flat wall into an image billboard. You drop an image in a folder, click two corner blocks, and the plugin places every item frame and map for you (up to 400 frames per billboard). Players who aim at a billboard see a clean glowing outline, and a left click can run a command, which makes it a good fit for store links, vote links, rules boards and promotions.

It uses only item frames and maps. There is no resource pack, no client mod and no other plugin to install.

Looking for video or sound?

HyperAds only shows still images. Video billboards, synced audio, playlists, sponsor pools and analytics are in the paid HyperAds+. See Free vs Plus.

#Installation

Requirements

  • Spigot or Paper 1.20 or newer
  • Java 17 or newer
  • Nothing else: no other plugins, no resource pack and no client mods are needed.

Steps

  1. Put the HyperAds jar in your server's plugins/ folder.
  2. Restart the server. The plugin creates plugins/HyperAds/ with an images/ folder and its config files, including messages.yml.
  3. Copy your images into plugins/HyperAds/images/.
  4. Run /ha reload to reload configs and refresh the images.
Command aliases

Everything lives under /ha. The aliases /hyperads, /hads and /ads work the same way.

#Creating billboards

A billboard is a rectangle of item frames, each holding a map that shows one tile of your image.

Create one

  1. Put the image in plugins/HyperAds/images/ and run /ha reload.
  2. Run /ha create <name> [image].
  3. Click the first corner block of the wall area, then the opposite corner block. Every frame and map is placed for you.

If you change your mind during the selection, run /ha abort to cancel it.

Supported images

PNG, JPG, BMP and GIF. A GIF shows its first frame only. A billboard can use up to 400 frames, and it works on any flat wall.

Manage billboards

  • /ha edit <name> image <image> swaps the image at any time.
  • /ha move <name> lets you click two new corners to move it.
  • /ha delete <name> removes it.
  • /ha list shows your billboards and /ha info <name> shows the details of one.

Players cannot break or rotate the frames of a billboard.

Check the map order first

Run /ha test to place a numbered 4x4 test billboard. It shows exactly how the maps tile together, which helps if a wall does not look right.

#Hover glow

When a player aims at a billboard, a clean glowing outline appears around it. It uses no particles.

  • Set the color per billboard with /ha edit <name> color <color>. You can use a color name or a hex code, which is matched to the closest glow color.
  • Use NONE to turn the glow off for that billboard.
  • You can set how far away players can see the glow and click, in blocks.

The glow range and the other tunable values live in the plugin's config files in plugins/HyperAds/. Each file is commented, so open it to see the exact option names for your version.

#Click commands

Each billboard can run one left-click command, even from far away.

Set or clear it

/ha edit myad command console give %player% diamond 1
/ha edit myad command player spawn
/ha edit myad command clear
  • console runs the command as the server console.
  • player runs it as the player who clicked.
  • clear removes the command.
  • %player% is replaced with the name of the player who clicked.

Cooldown

To stop spam, clicks have a configurable cooldown. Decimal values such as 0.5 seconds are allowed.

Be careful with console commands

A console command runs with full permissions. Only use commands you trust, and prefer player mode when a normal command is enough.

#Map quality

Maps only have a limited color palette, so HyperAds applies three optional tweaks to make map art look its best:

  • Saturation boost
  • Sharpening
  • Dithering

You can tune all three in the config. If an image looks washed out or blotchy, try changing these values and run /ha reload.

#Free vs Plus

HyperAds is the simple way to put clickable images on your walls. HyperAds+ is the upgraded version with video, sound and a full ad network. Both use the same /ha command and the same permission.

FeatureHyperAds (free)HyperAds+ (paid)
Image billboardsMapsFull-resolution resource pack rendering
Hover glowYesYes
Click commandsOne per billboardLeft and right click, per ad
Video billboardsNoMP4, MOV, GIF, frames, up to 20 fps
Synced audioNoPositional, in sync, 0 to 200% volume
Rotation playlistsNo (one static image)Playlists with commands per entry
SchedulingNoDates, time windows, days of the week
Sponsor slots and poolsNoSell ad space across many screens
Per-ad limitsNoPlays, clicks, airtime, expiry
Billboard groupsNoSettings for many billboards at once
Click analyticsNoViews, left and right clicks, placeholders
GUI editorNo (commands and config)Every setting, in game
Clone, import, exportNoCopy billboards, move between servers

#Commands

Everything lives under /ha. Aliases: /hyperads, /hads, /ads. All commands need hyperads.admin.

CommandWhat it doesPermission
/ha create <name> [image]Click two opposite corner blocks to build a billboard.hyperads.admin
/ha move <name>Click two new corners to move a billboard.hyperads.admin
/ha edit <name> image <image>Swap the image.hyperads.admin
/ha edit <name> color <color>Set the glow color by name or hex code, or NONE to turn it off.hyperads.admin
/ha edit <name> command <console|player> <command>Set the left-click command. %player% is the clicker.hyperads.admin
/ha edit <name> command clearRemove the click command.hyperads.admin
/ha delete <name>Delete a billboard.hyperads.admin
/ha testPlace a numbered 4x4 test billboard.hyperads.admin
/ha abortCancel a corner selection.hyperads.admin
/ha listList your billboards.hyperads.admin
/ha info <name>Show the details of a billboard.hyperads.admin
/ha reloadReload configs and refresh images.hyperads.admin

#Permissions

HyperAds has a single permission node. Players do not need any permission to see the glow or click a billboard.

PermissionWhat it allowsDefault
hyperads.adminUse every /ha command.op

#Messages and config

Every message the plugin sends can be changed in plugins/HyperAds/messages.yml. After editing, run /ha reload.

The config files are commented. They hold the map quality values (dithering, saturation, sharpening), the glow and click range, and the click cooldown. Open the file for the exact option names in your version.

#Troubleshooting and FAQ

My image is not in the list when I run /ha create.

Check that the file is in plugins/HyperAds/images/ and is a PNG, JPG, BMP or GIF. Then run /ha reload to refresh the images.

The billboard would not build.

The two corners you click must be on the same flat wall, and the billboard cannot be larger than 400 frames. Run /ha test to see how a billboard tiles on that wall.

The maps look washed out or noisy.

Maps have a small color palette. Try adjusting the dithering, saturation and sharpening values in the config, then run /ha reload.

Can players edit or break the frames?

No. Players cannot break or rotate the frames of a billboard.

Does a GIF animate?

No. A GIF shows its first frame. For animated video and sound you need HyperAds+.

I get "no permission".

Give the player hyperads.admin. It is OP by default.

The glow does not appear.

Check the billboard color with /ha info <name>. If it is NONE, set a color with /ha edit <name> color RED. Also check the glow range in the config.

#Updating

  1. Stop the server.
  2. Replace the old jar in plugins/ with the new one.
  3. Start the server.

Your billboards, images and messages stay in plugins/HyperAds/. As with any update, copy that folder somewhere safe first. Release notes are on the BuiltByBit page.