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.