#Overview
HyperAds+ shows full-color images and smooth video on billboards made of item frames. Everything is delivered through a resource pack that the plugin builds and hosts by itself, so there is no web host to set up. Videos play synced, positional audio from the billboard, and the same plugin lets you sell the space: playlists, schedules, sponsor slots, shared pools with per-ad limits, and click analytics.
What you get:
- Image and video billboards of any size, up to 20 frames per second.
- Positional audio that fades with distance and stays in sync for players who walk up mid-video.
- A tabbed in-game GUI editor for every setting.
- Playlists, schedules, sponsor slots and pools, billboard groups, click effects, analytics, and clone, import and export.
- Players without the pack (they declined it, or they are on Bedrock) see a still poster on the item-frame maps instead.
The free HyperAds shows clickable image billboards with no resource pack. See Free vs Plus.
#Installation
Requirements
- Paper 1.21.4 or newer, including 26.1.x
- Java 21 or newer
- One TCP port open to players for the built-in resource pack host (default 8163)
- PlaceholderAPI is optional and only needed for placeholders
- ffmpeg is optional. See below.
Steps
- Put the jar in
plugins/and restart the server. - Open port 8163 (TCP) in your firewall or host panel, or pick another port with
resource-pack.host.port. - In
plugins/HyperAdsPlus/config.yml, setresource-pack.host.public-addressto the IP or domain players use to join. Run/ha reload. - Run
/ha pack status. On startup the plugin checks that players can reach the pack URL, and the result shows here. If it fails, the console explains how to fix it.
If public-address is empty, the plugin uses server-ip from server.properties, and if that is empty too it uses 127.0.0.1, which only works on the same machine. Players on other computers would fail to download the pack.
Is ffmpeg needed?
No. Images, GIFs, frame folders, H.264 .mp4 videos and .ogg audio all work in pure Java. ffmpeg is only needed for other formats (webm, mkv, avi, mp3 or wav audio, and the sound inside video files). With ffmpeg-auto-download: true (the default) the plugin downloads an official static build the first time it needs one, checks it against its published checksum, and stores it in plugins/HyperAdsPlus/ffmpeg/. You can also put the binary there yourself, or point ffmpeg-path at it.
Demo media
On the first start, three demo clips with beat-synced jingles are installed, one per source type: hyperads_demo (frame folder), hyperads_demo_gif (GIF) and hyperads_demo_mp4 (MP4). Delete them whenever you like, or set demo.install: false.
#Creating billboards
- Put an image in
plugins/HyperAdsPlus/images/(png, jpg, jpeg, gif, bmp) or a video inplugins/HyperAdsPlus/videos/. - Run
/ha pack rebuildso the media is converted and added to the pack. - Run
/ha create <name> [media]. If you leave out the media, the plugin uses media with the same name as the billboard. - Click the first corner block of a wall, then the opposite corner block. Both corners must be on the same flat wall face, every block between them must be empty air, and the billboard can be at most 400 frames.
Use /ha cancel to abort a placement. To change a billboard later use the GUI, or /ha move <name> to click two new corners, /ha clone <name> <newname> to copy it to a new place, and /ha delete <name> to remove it.
Staged billboards
In the editor, the Look tab has a Visibility toggle. A STAGED billboard is only visible to you, so you can preview it before clicking the toggle to publish it live.
Quick edits from chat
/ha edit <name> image <media>
/ha edit <name> color <name|hex|NONE>
/ha edit <name> command <console|player> <command...>
/ha edit <name> command clear
/ha edit <name> speed <multiplier|reset>
/ha edit <name> audio <always|looking|off|default>
/ha edit <name> volume <0-200|default>
/ha edit <name> audiodistance <blocks|default>
Everything else is in the GUI.
#Images and video
Best quality: frame images (recommended)
A video saved as one picture per frame looks the sharpest and most colorful, and needs nothing extra on the server.
- Upload the video at ezgif.com/video-to-png, set the frame rate to 20, then convert.
- Download the frames as a ZIP and drop it into
videos/aspromo.zip. There is no need to unzip it. - For sound, also drop the original
promo.mp4next to it. The frames supply the picture and the MP4 supplies the sound.
If you made the video yourself, export a PNG or image sequence from your editor at 20 fps into a folder such as videos/promo/. Number the files with leading zeros (frame_0001.png, frame_0002.png) because frames play in file-name order. If the video is not 20 fps, add an fps.txt containing just the number.
Also works
.mp4 .webm .mov .mkv .avi: a little softer, because they are compressed..gif: 256 colors, so it is the least sharp.- To give a GIF or a frame folder sound, add an audio file with the same name, for example
promo.gifpluspromo.mp3. A.ogg,.mp3or.wavnext to a video also replaces the video's own sound.
After adding files, run /ha pack rebuild. Only new or changed files are converted. The pack is rebuilt and sent to everyone online, and players re-download it only when it actually changed. The rebuild also runs on server start and on /ha reload. Use /ha video list to see converted videos with their resolution, fps and audio.
Give the video a mono .ogg of the same name (in Audacity: File, Export, OGG, mono). Stereo plays, but it does not fade with distance.
A HOW-TO-ADD-VIDEOS.txt guide is written into the videos/ folder. While media converts, admins with hyperads.admin see a live progress bar above the hotbar (admin-progress-bar).
#Audio
Videos play their own audio from the billboard. It is positional, fades with distance and follows the playback speed through pitch. The audio is pre-cut every audio.tail-seconds seconds, so a player who walks up mid-video starts hearing it at the next cut, exactly in sync.
Audio modes
ALWAYS: every player within the audio distance hears it.LOOKING: only players within the distance who are looking at the billboard hear it. Withlook-follow: trueit stays loud across the whole distance while a player looks at it.OFF: no sound.
Per billboard overrides
/ha edit <name> audio <always|looking|off|default>
/ha edit <name> volume <0-200|default>
/ha edit <name> audiodistance <blocks|default>
Volume is a percent from 0 to 200. Above 100, the plugin plays a louder copy of the audio (200% is twice as loud). ffmpeg makes that copy and is downloaded automatically when needed. Audio distance can be 1 to 256 blocks. default returns to the global values in config.yml. The same settings are in the Audio tab of the GUI editor.
The sound plays in the Minecraft sound category set by audio.category (default RECORD), so players can turn billboards down in their own sound settings.
#Resource pack
HyperAds+ builds the pack, hosts it on its own small web server (port 8163 by default) and sends it to players when they join. Each frame is cut into tiles of up to 256x256 and stored as glyphs of a bitmap font. One text display per billboard draws the current frame, so every player sees the same frame in the same tick.
/ha pack statusshows the pack URL, size, estimated client memory, how many players have it loaded, and the startup self-test result./ha pack rebuildconverts new media and rebuilds the pack./ha pack send [player]re-sends the pack to one player, or everyone.
Enforcement
With resource-pack.enforcement: OPTIONAL (default), players may decline and see poster maps instead. With REQUIRED, the client must accept the pack to stay on the server, and kick-on-fail decides whether players whose download fails are kicked.
Using your own web host
Set resource-pack.url to a URL if you upload the zip from plugins/HyperAdsPlus/pack/ to your own host. You must re-upload the file after every rebuild.
Clients refuse resource packs above 250 MB. Videos use client memory of width x height x 4 bytes per frame, so keep an eye on the estimate in /ha pack status.
#GUI editor
Run /ha (or /ha gui) to open the main menu. From there you can create billboards, browse and edit them, manage groups and sponsor pools, view the analytics report and rebuild the resource pack. Typing a value (a number, a color, a command) happens in chat, and you can type cancel to back out.
The billboard editor tabs
| Tab | What it controls |
|---|---|
| Media | Pick the image or video, open the rotation playlist, switch IMAGE or VIDEO mode, loop, what happens after one pass (FREEZE the last frame or HIDE), and playback speed. |
| Audio | Audio mode, volume 0 to 200 percent, and audio distance. |
| Look | Highlight color, pulsing outline, highlight distance, video playback distance, and STAGED or LIVE visibility. |
| Clicks | Left and right click commands, click effect (confetti), click sound, click cooldown and a click permission. |
| Schedule | Campaign start and end for the billboard. |
| Sponsor | Sponsor mode (INHERIT, PER_SLOT or SHARED_POOL) and the billboard's group. |
| Manage | Rename, move, clone and delete. |
#Playlists and scheduling
A billboard can rotate through a playlist of images and videos instead of showing one item. Open it from the Media tab. Each playlist entry has its own settings:
- Advance: NATURAL moves on when a video clip ends (images use the default timer), FIXED moves on after the duration you set.
- Click commands: left and right click commands that run while this entry is showing, as the console or as the player.
- Highlight override: a color for this entry, or NONE.
- Schedule: a start and end date, a repeating time-of-day window such as
18:00-22:00(overnight windows like22:00-02:00work), and days of the week such asSAT,SUN. All of them must allow playback, and times use the server's local time. Entries outside their schedule are skipped.
On the billboard itself, the Schedule tab sets a campaign start and end. Dates use YYYY-MM-DD HH:mm, or clear to remove them.
Click commands support {player} and %player% as the name of the player who clicked. A leading / is optional.
#Click commands and effects
Players aim at a billboard to see its outline, and left or right click it to run the commands of the entry that is currently showing. If the current entry has no commands for that click, the billboard's older single left-click command (from /ha edit <name> command) is used instead.
- Cooldown:
click-cooldown-secondsin config.yml (default 3), with a per-billboard and per-group override. - Click permission: a node you choose per billboard in the Clicks tab. Players without it get a message and nothing runs. This is separate from
hyperads.admin. - Click effect: CONFETTI plays a particle burst at the click point. You can also set a click sound by Bukkit sound name, for example
UI_TOAST_CHALLENGE_COMPLETE. - Range:
click-distancesets how far away a billboard can be clicked, and-1useshighlight-distance.
Set click-effects.enabled: false to disable all click effects without touching each billboard.
#Sponsor slots and pools
Sponsor slots (one ad per billboard)
A sponsor slot is one paid ad that replaces the billboard's playlist until it expires.
/ha sponsor assign <billboard> <media> <days>
/ha sponsor clear <billboard>
/ha sponsor list
Use 0 days for no expiry. Assigning a slot resets that billboard's analytics. When a slot expires, sponsors.expiry-behavior decides what happens: VACANT_MEDIA shows the media named in sponsors.vacant-media, REMOVE drops the entry from the playlist, and KEEP keeps the last ad.
Sponsor pools (many billboards, one shared list)
A pool is a group of billboards that rotate through one shared list of ads. Manage them in the GUI (Main Menu, Sponsor Pools) or with commands:
/ha pool create <pool>
/ha pool add <pool> <billboard>
/ha pool remove <pool> <billboard>
/ha pool info <pool>
/ha pool delete <pool>
Ads inside a pool are added and edited in the GUI.
Per-ad limits
Click an ad in the pool to set its limits: max plays, max clicks, max airtime (such as 30m or 2h) and an expiry (such as 7d, or a date). When any limit is reached the ad leaves the rotation. A play limit lets the last run finish. Plays, clicks and airtime show as progress bars. You can pause an ad, or reset its counters so it plays again. 0 means no limit.
Campaign
In Pool Settings you can give the whole pool a start and end time, such as 2h, 3d or 2026-11-02 18:00.
When nothing plays
Used when the pool is paused, before the start, after the end, or when every ad is finished:
FALLBACKshows a fallback image or video you pick, such as an "Advertise here!" banner.BILLBOARDlets each screen play its own media.HIDEleaves the screens blank.
Rotation
Choose whether every screen shows the same ad at the same time (synchronized) or each advances on its own, whether to move on when a clip ends or on a timer, and whether to play in order or shuffled. Counters are saved every 30 seconds and on shutdown.
#Billboard groups
A group shares settings across many billboards: highlight color and distances, pulsing outline, audio distance, loop, speed, click effect, click sound, click permission, click cooldown and pack enforcement. Audio mode and volume apply live. For everything else, press Apply to push the group's settings onto every member. A setting left unset keeps each billboard's own value.
/ha group create <group>
/ha group apply <group>
/ha group delete <group>
Assign a billboard to a group from the Sponsor tab of its editor. Group editing happens in the GUI (Main Menu, Groups).
#Analytics and placeholders
HyperAds+ counts views (a player aiming at a billboard) and left and right clicks for every billboard and playlist entry.
/ha analytics report [billboard]
/ha analytics report-all [billboard]
/ha analytics reset
reset clears the counters since the last reset. All-time totals are kept.
PlaceholderAPI
If PlaceholderAPI is installed, HyperAds+ registers the hyperads expansion automatically. Use a billboard name in place of <billboard>.
#Placeholders
These need PlaceholderAPI. Use the billboard name, for example %hyperads_views_spawn%.
| Placeholder | Value |
|---|---|
| %hyperads_active_<billboard>% | The media currently playing on the billboard (empty if there is none). |
| %hyperads_views_<billboard>% | How many times players have aimed at the billboard. |
| %hyperads_clicks_<billboard>% | Total clicks, left and right. |
| %hyperads_clicks_left_<billboard>% | Left clicks only. |
| %hyperads_clicks_right_<billboard>% | Right clicks only. |
#Clone, export and import
/ha clone <name> <newname> copies a billboard's whole configuration (playlist, group, sponsor and highlight settings) to a new place. Click two corner blocks to place the copy.
To move billboards between servers, export them to a file and import it on the other server:
/ha export all <file>
/ha export billboard <name> <file>
/ha export group <name> <file>
/ha import <file>
Exports are written as .harap.json files into plugins/HyperAdsPlus/exports/. Copy the file to the same folder on the other server. Imported billboards need the same media, so copy your images and videos too. The import reports any missing media. Billboards whose world is not loaded cannot be placed and are skipped with a console warning.
#Configuration
The main file is plugins/HyperAdsPlus/config.yml. Run /ha reload after editing. Messages are in messages.yml (legacy & color codes and MiniMessage both work). Below are the options most servers touch. Per-billboard values set in the GUI override these defaults.
Resource pack host
resource-pack:
# OPTIONAL = players may decline (they see the poster maps).
# REQUIRED = the client must accept the pack to stay on the server.
enforcement: OPTIONAL
# With REQUIRED: kick players whose download fails or who decline.
kick-on-fail: true
# Ticks to wait after join before sending the pack.
send-delay-ticks: 20
# Leave empty to use the built-in host below. Set a URL here if you upload
# the zip from plugins/HyperAdsPlus/pack/ to your own web host instead (the
# file must be re-uploaded after every rebuild).
url: ""
host:
enabled: true
# The port must be open to players (firewall / host panel).
port: 8163
# Your server's PUBLIC IP or domain, as players connect to it.
# Empty = server-ip from server.properties, else 127.0.0.1 (local only).
public-address: ""
# Network interface to listen on (empty = all).
bind-address: ""
Audio
audio:
enabled: true
# Players only hear a billboard within this many blocks; the sound fades
# to silence at that distance. Per billboard:
# /ha edit <name> audiodistance <blocks|default>
distance: 24
# Volume in percent (0-200). Above 100 a louder copy of the audio is played
# (200% = twice as loud). ffmpeg makes it; it is downloaded automatically.
volume: 100
# Who hears it:
# ALWAYS = every player within the distance
# LOOKING = only players within the distance who are LOOKING at it
# OFF = no sound
# Per billboard: /ha edit <name> audio <always|looking|off|default>
mode: ALWAYS
# LOOKING: true = while a player looks at the billboard it stays loud
# across the whole audio.distance (60% at the far edge). false = it fades
# with distance like ALWAYS mode.
look-follow: true
# Sound category players control it with (MASTER, MUSIC, RECORD, AMBIENT,
# BLOCK, NEUTRAL, PLAYER, VOICE, WEATHER, HOSTILE).
category: RECORD
# Players who walk up mid-video start hearing it at the next multiple of
# this many seconds, perfectly in sync. Lower = sooner, bigger pack.
tail-seconds: 4
# OGG Vorbis quality 0-10.
quality: 5
# Even out loud and quiet ads (EBU R128 loudness normalization).
normalize: true
# Upper limit on the encoded audio per video, in seconds.
max-total-seconds: 900
Video conversion and client memory
Video frames use client memory: width x height x 4 bytes per frame. texture-budget-mb caps one video, and longer clips get a lower resolution automatically. Raise max-width, max-height and the budget for sharper video, or lower fps to give longer clips more resolution.
videos:
# Frames per second of every converted video (max 20, the tick rate).
fps: 20
# Largest frame size. Smaller videos are not upscaled.
max-width: 640
max-height: 360
# Videos are cut off after this many seconds (0 = no limit).
max-seconds: 60
max-frames: 1200
# Client memory budget for ONE video's frames, in MB (RGBA textures).
# When a clip would need more, its resolution is lowered automatically.
# This is what keeps long clips from overloading players' PCs.
texture-budget-mb: 192
# Reject source files larger than this (MB).
max-file-size-mb: 500
# Playback speed multiplier: 0.5 = half speed, 2.0 = double speed.
# Audio follows through its pitch (only between 0.5 and 2.0).
speed-multiplier: 1.0
images:
# Largest image side in pixels.
max-size: 1024
ffmpeg
# Path to ffmpeg. Empty = plugins/HyperAdsPlus/ffmpeg/ffmpeg(.exe), then PATH.
ffmpeg-path: ""
# Download a static ffmpeg build (Windows x64, Linux x64/arm64) into
# plugins/HyperAdsPlus/ffmpeg/ when media needs it and none is installed.
# Official builds linked from ffmpeg.org, checked against their checksum.
ffmpeg-auto-download: true
Highlight and click
# When a player LOOKS at a billboard (crosshair on it) from within the
# highlight distance, an invisible glowing display entity draws ONE clean
# outline around the whole billboard in the billboard's highlight color.
highlight-distance: 30
# How often (in ticks) hover detection runs.
highlight-update-interval: 1
# Default highlight color for new billboards (name, hex #RRGGBB, or NONE).
default-highlight-color: "GREEN"
# When true, VIDEO billboards blink their outline on/off rhythmically
# ("pulse") instead of a constant glow. Off by default - a constant glow
# is cleaner; per-billboard toggle in the editor.
highlight-pulse-videos: false
highlight-pulse-period-ticks: 10
# Maximum distance (blocks) from which a billboard can be clicked.
# -1 uses highlight-distance.
click-distance: -1
# Default cooldown (seconds) between click commands. Per-billboard override.
click-cooldown-seconds: 3
Click effects
click-effects:
enabled: true
Screen alignment
If the picture sits slightly off the wall grid on some client version, adjust screen.nudge-x and screen.nudge-y (in blocks).
screen:
# STRETCH fills the whole billboard. CONTAIN keeps the media's aspect
# ratio (the poster map shows in the leftover bars).
fit: STRETCH
# Always fully lit (true) or lit by the world's light like a block (false).
full-bright: true
# Distance in blocks between the wall surface and the screen. Small = no
# visible gap at the edges when viewed from an angle.
wall-gap: 0.025
# Make the billboard's item frames invisible so their poster maps lie flat
# on the wall right behind the screen (needed for a small wall-gap).
hide-item-frames: true
# Shrinks the screen on every side, in blocks.
edge-inset: 0.0
# Fine alignment in blocks, in case a client version renders text
# slightly differently (positive = right / up).
nudge-x: 0.0
nudge-y: 0.0
Poster maps (players without the pack)
render:
dithering: true
dither-strength: 0.7
saturation: 1.15
sharpening: 0.35
Sponsor defaults
sponsors:
# Global default mode for NEWLY created sponsor slots:
# PER_SLOT (each billboard has its own assigned ad) or
# SHARED_POOL (billboards cycle a shared ad inventory).
default-mode: PER_SLOT
# SHARED_POOL behaviour: when true, all member billboards show the same
# ad at the same time; when false each billboard advances on its own timer.
pools-synchronized: true
# Seconds each ad plays on a pool billboard before advancing
# (videos may advance naturally when the clip ends instead - see the
# pool's advance mode in the GUI).
pool-advance-seconds: 10
# What a PER_SLOT billboard shows when its sponsor ad expires:
# VACANT_MEDIA (show the configured vacant media), REMOVE (entry leaves the
# playlist) or KEEP (keep the last ad until manually reassigned).
expiry-behavior: VACANT_MEDIA
# Media shown in VACANT mode (an image or video name in your media folders).
vacant-media: "vacant"
Storage
# --- Storage ------------------------------------------------------
# Where billboards, groups, pools, sponsor data and analytics live.
# yaml : human-readable files inside plugins/HyperAdsPlus/data/
# sqlite : single database file data/hyperads.db
storage:
type: yaml
Other options
# Show live progress (converting, building the pack, downloading ffmpeg) above
# the hotbar of every online admin (permission hyperads.admin).
admin-progress-bar: true
# Install the demo video (videos/hyperads_demo + hyperads_demo.ogg) on the first
# start. Deleting it is permanent; delete videos/.demo-installed to
# get it back.
demo:
install: true
There is also console-banner.enabled, which switches the startup banner in the console to a plain one-line log entry when set to false.
#Free vs Plus
HyperAds+ has the same easy billboard system as the free HyperAds, plus video, sound and a whole ad network. If you only need still images, the free version is enough.
| Feature | HyperAds (free) | HyperAds+ (paid) |
|---|---|---|
| Image billboards | Maps | Full-resolution resource pack rendering |
| Hover glow | Yes | Yes |
| Click commands | One per billboard | Left and right click, per ad |
| Video billboards | No | MP4, MOV, GIF, frames, up to 20 fps |
| Synced audio | No | Positional, in sync, 0 to 200% volume |
| Resource pack | None | Builds and hosts it itself |
| Rotation playlists | No (one static image) | Playlists with commands per entry |
| Scheduling | No | Dates, time windows, days of the week |
| Sponsor slots and pools | No | Sell ad space across many screens |
| Per-ad limits | No | Plays, clicks, airtime, expiry |
| Campaigns and fallback | No | Start and end times, "Advertise here" fallback |
| Billboard groups | No | Settings for many billboards at once |
| Click analytics | No | Views, left and right clicks, placeholders |
| Click effects | No | Confetti and custom sounds |
| GUI editor | No (commands and config) | Every setting, in game |
| Clone, import, export | No | Copy billboards, move between servers |
#Commands
Everything lives under /ha. Aliases: /hyperads, /hads, /ads. Running /ha alone opens the GUI. Every subcommand except /ha help needs hyperads.admin. Most commands that place or move billboards need a player, and the others also work from the console.
| Command | What it does | Permission |
|---|---|---|
| /ha (or /ha gui, /ha editor) | Open the GUI editor. | hyperads.admin |
| /ha create <name> [media] | Click two corner blocks to build a billboard. Media defaults to the billboard name. | hyperads.admin |
| /ha move <name> | Click two new corners to move a billboard. | hyperads.admin |
| /ha edit <name> image <media> | Change the media (image or video). | hyperads.admin |
| /ha edit <name> color <name|hex|NONE> | Set the highlight color, or NONE to turn it off. | hyperads.admin |
| /ha edit <name> command <console|player> <command> | Set the billboard's single left-click command. | hyperads.admin |
| /ha edit <name> command clear | Remove that command. | hyperads.admin |
| /ha edit <name> speed <multiplier|reset> | Video playback speed for this billboard (1.0 is normal). | hyperads.admin |
| /ha edit <name> audio <always|looking|off|default> | Who hears this billboard. | hyperads.admin |
| /ha edit <name> volume <0-200|default> | Volume in percent. Above 100 plays a louder copy. | hyperads.admin |
| /ha edit <name> audiodistance <blocks|default> | How close players must be to hear it (1 to 256 blocks). | hyperads.admin |
| /ha delete <name> | Delete a billboard. | hyperads.admin |
| /ha list | List all billboards with media and size. | hyperads.admin |
| /ha info <name> | Show media, size, highlight color, click command and location. | hyperads.admin |
| /ha video build | Convert new media and rebuild the pack. | hyperads.admin |
| /ha video list | List converted videos with resolution, fps and audio. | hyperads.admin |
| /ha pack status | Pack URL, size, client memory estimate, players loaded and the self-test result. | hyperads.admin |
| /ha pack rebuild | Convert new media and rebuild the pack, then send it to everyone online. | hyperads.admin |
| /ha pack send [player] | Re-send the pack to a player, or to everyone. | hyperads.admin |
| /ha group create <group> | Create a billboard group. | hyperads.admin |
| /ha group apply <group> | Push the group's settings onto every member. | hyperads.admin |
| /ha group delete <group> | Delete a group. Members are released. | hyperads.admin |
| /ha pool create <pool> | Create a sponsor pool. | hyperads.admin |
| /ha pool add <pool> <billboard> | Add a billboard to a pool. | hyperads.admin |
| /ha pool remove <pool> <billboard> | Remove a billboard from a pool. | hyperads.admin |
| /ha pool info <pool> | List the ads in a pool (also /ha pool list <pool>). | hyperads.admin |
| /ha pool delete <pool> | Delete a pool. Member billboards are released. | hyperads.admin |
| /ha sponsor assign <billboard> <media> <days> | Assign a sponsor ad to a billboard for a number of days (0 = never expires). | hyperads.admin |
| /ha sponsor clear <billboard> | Clear the sponsor slot so the playlist plays again. | hyperads.admin |
| /ha sponsor list | List sponsor slots and when they expire. | hyperads.admin |
| /ha clone <name> <newname> | Copy a billboard's configuration, then click two corners to place the copy. | hyperads.admin |
| /ha export all <file> | Export everything to plugins/HyperAdsPlus/exports/<file>.harap.json. | hyperads.admin |
| /ha export billboard <name> <file> | Export one billboard. | hyperads.admin |
| /ha export group <name> <file> | Export one group. | hyperads.admin |
| /ha import <file> | Import a previously exported file. | hyperads.admin |
| /ha analytics report [billboard] | Show views and clicks since the last reset. | hyperads.admin |
| /ha analytics report-all [billboard] | Show all-time views and clicks. | hyperads.admin |
| /ha analytics reset | Reset the since-last-reset counters (all-time totals are kept). | hyperads.admin |
| /ha cancel | Cancel a placement, move or clone selection. | hyperads.admin |
| /ha reload | Reload configs, rescan media and rebuild the pack. | hyperads.admin |
| /ha help | Show the command list. | none |
#Permissions
HyperAds+ has one built-in permission. Players need nothing to see billboards or click them. You can also protect an individual billboard with your own permission node in its Clicks tab.
| Permission | What it allows | Default |
|---|---|---|
| hyperads.admin | Every /ha command (except help), the GUI editor, the live progress bar above the hotbar, and update notifications. | op |
#Troubleshooting and FAQ
Players see a still poster instead of the video.
They declined the pack, the download failed, or they are on Bedrock. Run /ha pack status and check the self-test. The most common cause is a closed port 8163 or a wrong resource-pack.host.public-address. Then ask the player to rejoin and click Yes. Use /ha pack send <player> to re-send the pack.
The self-test fails or the pack never downloads.
Open the TCP port in resource-pack.host.port (default 8163) in your firewall and host panel. Set resource-pack.host.public-address to the IP or domain players connect with, run /ha reload, then check /ha pack status again. If your host cannot open an extra port, upload the zip from plugins/HyperAdsPlus/pack/ to your own web host and put its link in resource-pack.url, remembering to re-upload after every rebuild.
A video has no sound.
Give it sound with an audio file of the same name (for example promo.zip plus promo.mp4), or with a mono .ogg. Check that /ha video list shows audio for it, and that audio.enabled is true and the billboard audio mode is not OFF.
The sound is too quiet or too loud.
Use /ha edit <name> volume <0-200>. Values above 100 need a louder copy made by ffmpeg, which the plugin downloads automatically. The Audio tab shows the status of that copy.
Sound does not fade with distance.
Stereo .ogg files play but do not fade. Use a mono .ogg, or let the plugin convert the audio with ffmpeg.
My video was rejected or came out blurry.
Videos are limited by videos.max-seconds, videos.max-file-size-mb and the client memory budget (videos.texture-budget-mb). Longer clips automatically get a lower resolution. For the best quality, use frame images at 20 fps, and raise max-width, max-height and the budget if you can afford the memory.
The pack is too big.
Clients refuse packs above 250 MB. Lower videos.fps, max-width or max-seconds, or remove media you no longer use, then run /ha pack rebuild.
The picture is slightly off the wall grid.
Adjust screen.nudge-x and screen.nudge-y (in blocks) in config.yml.
My billboard will not build.
Both corners must be clicked on the same flat wall face, every block between them must be empty air, and the maximum is 400 frames.
Can I delete the old videos_frames folder?
Yes. If you upgraded from version 1.0.0, the videos_frames/ folder is no longer used.
#Updating
HyperAds+ can check BuiltByBit for new versions and tell the console and players with hyperads.admin. Control it with the updates section:
# Checks BuiltByBit for new versions. Nothing is sent except the request itself.
updates:
enabled: true
check-on-startup: true
check-interval-hours: 24
# Downloads the new jar into plugins/update. It is installed on the next restart.
# The current jar is copied to plugins/HyperAdsPlus/backup first.
auto-download: false
# Tells the console and players with hyperads.admin.
notify: true
With auto-download: true, the new jar is downloaded into plugins/update and installed on the next restart, after the current jar is copied to plugins/HyperAdsPlus/backup. To update by hand, stop the server, replace the jar and start it again. Billboards, groups, pools and analytics are kept in plugins/HyperAdsPlus/.
Copy plugins/HyperAdsPlus/ before updating. Rebuilding the pack after an update sends it to players only if it changed.