Reference

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