LobbyLink Plugin

Overview

The LobbyLink plugin connects your Spigot/Paper/Purpur server to your LobbyLink listing. It handles vote delivery and rewards, streak tracking, vote parties, and keeps your listing's player count accurate via heartbeat.

• Vote rewards — tiered permission rewards, per-service bonuses, and a default fallback
• Vote streaks — consecutive day tracking with configurable milestones
• Vote parties — community counter that rewards every online player when the goal is hit
• PlaceholderAPI — 7 placeholders for scoreboards, holograms, and TAB
• Player count sync — heartbeat keeps your listing accurate every 5 minutes

Installation

plugin-token: "ll_live_yourTokenHere"

Server Verification

Setting plugin-token and running the plugin is all you need. The plugin sends a heartbeat every 5 minutes — the first heartbeat automatically marks your listing as verified.

Votifier Setup

External vote sites (Planet Minecraft, TopG, Minecraft-Server-List.com, etc.) can send votes directly to your server via the Votifier protocol. The plugin listens on port 8192 and supports both Votifier v1 (RSA) and NuVotifier v2 (HMAC-SHA256).

Make sure TCP port 8192 is open in your firewall. You can change it via votifier.port in config.yml.

Run /ll pubkey in console or in-game. Copy the full PEM block and paste it into vote sites that require a Votifier v1 public key.

Copy the Votifier Token from Dashboard → Settings → Plugin & Votifier and set it in config.yml:

votifier:
  token: "your-votifier-token-here"

Reward Commands

Rewards resolve in priority order — the first match wins. Commands run as console with {player} replaced by the voter's username.

Players with a matching permission get these rewards. Highest priority tier wins. Sorted by priority descending, so ties in config order are predictable.

rewards:
  tiers:
    mvp:
      priority: 100
      permission: "lobbylink.tier.mvp"
      commands:
        - "give {player} diamond 5"
        - "eco give {player} 500"
    vip:
      priority: 50
      permission: "lobbylink.tier.vip"
      commands:
        - "give {player} diamond 2"

If no tier matches, the plugin checks whether the vote came from a specific site. The service name is case-insensitive.

rewards:
  services:
    "Planet Minecraft":
      commands:
        - "give {player} emerald 1"

Runs for every voter that didn't match a tier or service — always fires.

rewards:
  commands:
    - "give {player} diamond 1"
    - "say Thanks {player} for voting!"

Vote Streaks

The plugin tracks how many consecutive days each player has voted. When a player hits a milestone, bonus commands fire and a special broadcast goes out to the server.

streaks:
  enabled: true
  streak-timezone: "UTC"   # Use your server's local timezone, e.g. "America/New_York"
  milestones: [3, 7, 30, 100]
  milestone-commands:
    - "give {player} diamond {streak}"

{streak} is replaced with the player's current streak count. Day boundaries follow streak-timezone — set this to your community's timezone so midnight resets feel natural.

Vote Parties

A shared community counter climbs toward a configurable goal. When it hits, every online player receives the party reward commands and a broadcast fires in chat. The counter then resets.

vote-party:
  enabled: true
  goal: 50
  announce-every: 10   # Announce progress every 10 votes
  commands:
    - "give {player} firework_rocket 3"
    - "say {player} helped trigger a vote party!"

Progress announcements fire at every multiple of announce-every, e.g. at 10, 20, 30, 40 votes. The announcement at the goal triggers the party.

The current vote party counter is accessible via the %lobbylink_party_progress% placeholder and is shown in /ll status.

PlaceholderAPI

Install PlaceholderAPI to use LobbyLink data in scoreboards, holograms, TAB, chat, and any other PAPI-compatible plugin.

Placeholders can be combined — e.g. %lobbylink_party_progress% / %lobbylink_party_goal% for a progress display.

Leaderboard

/ll top shows the top 10 voters all-time and the top 10 for the current month, directly in chat.

/ll top           → All-time + this month
/ll top alltime   → All-time only
/ll top monthly   → This month only

By default this command requires lobbylink.admin. To let regular players use it, give them the lobbylink.top permission — no admin access needed.

# In LuckPerms or similar:
lp group default permission set lobbylink.top true

HTTP Webhook

An alternative to Votifier — LobbyLink can POST vote notifications directly to your server over HTTP. Useful if you can't expose port 8192 or prefer HTTP.

http://<your-server-ip>:7878/vote

Offline Player Votes

When a vote arrives for a player who is offline, the reward is stored in plugins/LobbyLink/pending-votes.yml. The next time that player joins, all pending rewards are delivered automatically.

Pending votes expire after pending-vote-expiry-days days (default: 7). Set to 0 to never expire.

Commands

All commands support tab completion. lobbylink.admin is granted to ops by default.

Full Config Reference

Complete annotated config.yml:

# LobbyLink Plugin Configuration
# Docs: https://lobbylink.net/docs/plugin

# Plugin token from Dashboard → Settings → Plugin & Votifier
plugin-token: ""

# LobbyLink API base URL — do not change unless self-hosting
api-url: "https://api.lobbylink.net"

# ── Votifier Listener ─────────────────────────────
# Built-in listener — no separate Votifier plugin needed.
# Supports Votifier v1 (RSA) and NuVotifier v2 (HMAC-SHA256).
votifier:
  enabled: true
  port: 8192
  token: ""              # NuVotifier v2 token (optional)
  require-v2-token: false  # Set true to reject v2 votes without a valid token

# ── HTTP Webhook (alternative to Votifier) ────────
webhook:
  enabled: true
  port: 7878
  secret: "change-me-to-a-strong-secret"

# ── Vote Rewards ──────────────────────────────────
# Commands run as console. {player} = voter's username.
rewards:
  tiers:
    mvp:
      priority: 100
      permission: "lobbylink.tier.mvp"
      commands:
        - "give {player} diamond 5"
        - "eco give {player} 500"
    vip:
      priority: 50
      permission: "lobbylink.tier.vip"
      commands:
        - "give {player} diamond 2"
  services:
    "Planet Minecraft":
      commands:
        - "give {player} emerald 1"
  commands:
    - "give {player} diamond 1"
    - "say Thanks {player} for voting!"

# ── Vote Streaks ──────────────────────────────────
streaks:
  enabled: true
  streak-timezone: "UTC"
  milestones: [3, 7, 30, 100]
  milestone-commands:
    - "give {player} diamond {streak}"

# ── Vote Party ────────────────────────────────────
vote-party:
  enabled: true
  goal: 50
  announce-every: 10
  commands:
    - "give {player} firework_rocket 3"

# ── Visual Effects ────────────────────────────────
effects:
  firework:
    enabled: true
    type: BALL_LARGE
    colors: ["RED", "ORANGE"]
    flicker: true
    trail: false
  sound:
    enabled: true
    name: "ENTITY_PLAYER_LEVELUP"
    volume: 1.0
    pitch: 1.2
  title:
    enabled: false
    title: "&6Thanks for voting!"
    subtitle: "&eYour rewards have been delivered."
  actionbar:
    enabled: true
    message: "&aThanks for voting on LobbyLink!"

# ── Messages ──────────────────────────────────────
messages:
  vote-received: "&aThank you for voting! Enjoy your reward."
  reminder: "&7You haven't voted today — &avote now&7 and claim your reward."

# ── Reminders ─────────────────────────────────────
reminders:
  enabled: true
  check-interval-minutes: 60
  cooldown-hours: 20

# ── Data Retention ────────────────────────────────
pending-vote-expiry-days: 7
data:
  keep-months: 3

Troubleshooting

Still stuck? Join our Discord for support.