All documentation
Documentation

HyperAds+

Video billboards with synced positional audio, plus playlists, sponsor pools and analytics. The plugin builds and hosts its own resource pack.

v1.0.2 Paper 1.21.4+ (including 26.1.x)Java 21+One open TCP port for the built-in pack host (default 8163)PlaceholderAPI (optional)ffmpeg (optional, downloaded automatically)

Quick start

  1. Drop the jar in plugins/ and restart the server.
  2. Open TCP port 8163 to players, then set resource-pack.host.public-address in plugins/HyperAdsPlus/config.yml to the IP or domain players join with. Run /ha reload.
  3. Try the demo clips that install on first start: run /ha create demo hyperads_demo_mp4 and click two opposite corner blocks of a wall.
  4. Add your own media to plugins/HyperAdsPlus/images/ or videos/, then run /ha pack rebuild.
  5. Run /ha to open the GUI editor and set audio, clicks, schedules and sponsor pools.
  6. Run /ha pack status to see the pack URL, size and the startup self-test result.

#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.
Only need still images?

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

  1. Put the jar in plugins/ and restart the server.
  2. Open port 8163 (TCP) in your firewall or host panel, or pick another port with resource-pack.host.port.
  3. In plugins/HyperAdsPlus/config.yml, set resource-pack.host.public-address to the IP or domain players use to join. Run /ha reload.
  4. 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.
The public address matters

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

  1. Put an image in plugins/HyperAdsPlus/images/ (png, jpg, jpeg, gif, bmp) or a video in plugins/HyperAdsPlus/videos/.
  2. Run /ha pack rebuild so the media is converted and added to the pack.
  3. Run /ha create <name> [media]. If you leave out the media, the plugin uses media with the same name as the billboard.
  4. 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.

  1. Upload the video at ezgif.com/video-to-png, set the frame rate to 20, then convert.
  2. Download the frames as a ZIP and drop it into videos/ as promo.zip. There is no need to unzip it.
  3. For sound, also drop the original promo.mp4 next 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.gif plus promo.mp3. A .ogg, .mp3 or .wav next 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.

No ffmpeg, but you want sound?

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. With look-follow: true it 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.

Players control the volume

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 status shows the pack URL, size, estimated client memory, how many players have it loaded, and the startup self-test result.
  • /ha pack rebuild converts 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.

Pack size limit

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

TabWhat it controls
MediaPick 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.
AudioAudio mode, volume 0 to 200 percent, and audio distance.
LookHighlight color, pulsing outline, highlight distance, video playback distance, and STAGED or LIVE visibility.
ClicksLeft and right click commands, click effect (confetti), click sound, click cooldown and a click permission.
ScheduleCampaign start and end for the billboard.
SponsorSponsor mode (INHERIT, PER_SLOT or SHARED_POOL) and the billboard's group.
ManageRename, 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 like 22:00-02:00 work), and days of the week such as SAT,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-seconds in 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-distance sets how far away a billboard can be clicked, and -1 uses highlight-distance.
Turn effects off everywhere

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:

  • FALLBACK shows a fallback image or video you pick, such as an "Advertise here!" banner.
  • BILLBOARD lets each screen play its own media.
  • HIDE leaves 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%.

PlaceholderValue
%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.

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
Resource packNoneBuilds and hosts it itself
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
Campaigns and fallbackNoStart and end times, "Advertise here" fallback
Billboard groupsNoSettings for many billboards at once
Click analyticsNoViews, left and right clicks, placeholders
Click effectsNoConfetti and custom sounds
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. 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.

CommandWhat it doesPermission
/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 clearRemove 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 listList all billboards with media and size.hyperads.admin
/ha info <name>Show media, size, highlight color, click command and location.hyperads.admin
/ha video buildConvert new media and rebuild the pack.hyperads.admin
/ha video listList converted videos with resolution, fps and audio.hyperads.admin
/ha pack statusPack URL, size, client memory estimate, players loaded and the self-test result.hyperads.admin
/ha pack rebuildConvert 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 listList 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 resetReset the since-last-reset counters (all-time totals are kept).hyperads.admin
/ha cancelCancel a placement, move or clone selection.hyperads.admin
/ha reloadReload configs, rescan media and rebuild the pack.hyperads.admin
/ha helpShow 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.

PermissionWhat it allowsDefault
hyperads.adminEvery /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/.

Back up first

Copy plugins/HyperAdsPlus/ before updating. Rebuilding the pack after an update sends it to players only if it changed.