Complete Configuration Reference

Every option in config.yml explained with examples and defaults.

File Location

plugins/InviteMe/config.yml

After editing, reload with: /im reload

Storage Configuration

type

Key: storage.type | Type: string | Default: sqlite

Storage backend for invite data.

Options:

json - Text files (legacy, small servers only)
sqlite - Local database file (recommended)
mysql - MySQL/MariaDB remote
postgresql - PostgreSQL remote

storage:
  type: sqlite

Remote Database Settings

Use only if storage.type is mysql or postgresql.

host

Key: storage.remote.host | Type: string | Default: localhost

Database server hostname.

storage:
  remote:
    host: "db.example.com"

port

Key: storage.remote.port | Type: integer | Default: 3306 (MySQL) or 5432 (PostgreSQL)

Database server port.

storage:
  remote:
    port: 3306

database

Key: storage.remote.database | Type: string | Default: inviteme

Database name.

storage:
  remote:
    database: "inviteme"

username

Key: storage.remote.username | Type: string | Default: root

Database user.

storage:
  remote:
    username: "inviteme_user"

password

Key: storage.remote.password | Type: string | Default: password

Database password. Keep secret!

storage:
  remote:
    password: "SecurePassword123"

pool-size

Key: storage.remote.pool-size | Type: integer | Default: 10

Max simultaneous connections. Recommendation:

Small servers (1-5 players): 5-10
Medium (5-50 players): 10-20
Large (50+ players): 20-50

storage:
  remote:
    pool-size: 15

Language Settings

language

Type: string | Default: en

Plugin message language.

Options: en (English), es (Spanish), de (German)

language: "en"

Console Output

ansi-colors

Key: console.ansi-colors | Type: boolean | Default: true

Enable ANSI colors in console (✓, ✗, ⚠). Set false on Windows or log collectors without ANSI support. In the startup block only the [✓]/[-]/[!] mark is coloured; the logo never is.

console:
  ansi-colors: true

Key: console.banner | Type: boolean | Default: true

Draw the “IM” ASCII logo next to the version, server and author on startup. With false those three lines are printed without the logo. The status block below it is always printed, in the language set by language:

 ___  __  __
|_ _||  \/  |   InviteMe v26.09.29.0
 | | | |\/| |   Running on Paper 1.21.10 | Java 25
 | | | |  | |   by SergiSvK
|___||_|  |_|
[✓] Language: en | Max invites per player: 5
[✓] Storage: SQLite (invites.db) | 42 invite(s)
[✓] Access: native whitelist | sync every 60 min
[-] LuckPerms: disabled in config
[!] Update checks are disabled
    → Set version-checker.enabled: true in config.yml

[✓] works, [-] is off, [!] needs attention and is followed by how to fix it. /im reload prints the same block without the logo.

A few seconds after the server’s “Done”, one more line sums up the work that finishes in the background — the first whitelist sync, the skin cache and the first update check:

[✓] Background: whitelist sync +0/-0 | 12 skin(s) loading | up to date (26.09.29.0)

When an update is out (or the check fails) that line becomes a [!] with the download link (or /im version check) under it. Later checks, every version-checker.interval-hours, only print when there is an update or the check fails.

console:
  banner: true

Version Checker

enabled

Key: version-checker.enabled | Type: boolean | Default: true

Check for updates on Modrinth. With false nothing is checked and the console shows a warning on every startup and /im reload.

Existing installs keep the value already in their config.yml: if it was false, change it by hand.

Only versions whose Modrinth listing includes the server’s exact Minecraft version are offered. A newer release that does not list it (for example, one that drops support for that version) produces no notice.

version-checker:
  enabled: true

interval-hours

Key: version-checker.interval-hours | Type: integer | Default: 24

How often to check (0 = startup only).

version-checker:
  interval-hours: 24

notify-admins

Key: version-checker.notify-admins | Type: boolean | Default: true

Notify OPs and invite.admin in-game about new versions: those online when the version is found, and each one on join, once per version while the server keeps running.

version-checker:
  notify-admins: true

notify-for

Key: version-checker.notify-for | Type: list | Default: [release]

Version types to notify about: release, beta, alpha.

version-checker:
  notify-for:
    - release

Invite Limits

max-invites

Type: integer | Default: 5

Default invitations per player. Overrideable by:

LuckPerms permission invite.number.X
LuckPerms group limits
plugin-xp-slots progression (if enabled)

Note: Console and admins have no limit.

max-invites: 5

Invite Cooldown

invite-cooldown

Type: integer | Default: 30

Seconds between /invite uses per player. 0 = disabled.

Note: Players with invite.admin bypass this.

invite-cooldown: 30

LuckPerms Integration

enabled

Key: luckperms.enabled | Type: boolean | Default: false

Enable LuckPerms group-based invite limits.

luckperms:
  enabled: false

default-group

Key: luckperms.default-group | Type: string | Default: default

Group assigned to new invited players (must exist in LuckPerms).

luckperms:
  default-group: "member"

group-limits

Key: luckperms.group-limits | Type: map<string, integer> | Default: {}

Per-group invite limits. Priority: invite.number.X permission > group-limits > max-invites.

luckperms:
  enabled: true
  group-limits:
    member: 3
    vip: 10
    moderator: 20

Whitelist Synchronization

enabled

Key: whitelist-sync.enabled | Type: boolean | Default: true

Keep vanilla whitelist in sync with InviteMe data.

whitelist-sync:
  enabled: true

auto-register-console

Key: whitelist-sync.auto-register-console | Type: boolean | Default: true

Auto-register players added via console to InviteMe.

whitelist-sync:
  auto-register-console: true

sync-interval-minutes

Key: whitelist-sync.sync-interval-minutes | Type: integer | Default: 60

How often to run background sync (in minutes).

whitelist-sync:
  sync-interval-minutes: 60

cleanup-removed

Key: whitelist-sync.cleanup-removed | Type: boolean | Default: false

Remove all players from whitelist when syncing. WARNING: Dangerous!

whitelist-sync:
  cleanup-removed: false

notify-on-sync

Key: whitelist-sync.notify-on-sync | Type: boolean | Default: false

Notify admins on each sync completion.

whitelist-sync:
  notify-on-sync: false

Access Control Mode

access-control-mode

Type: string | Default: native

How players are checked for access on join.

Options:

native - Vanilla whitelist controls access (recommended)
plugin - InviteMe controls access. Requires white-list=false in server.properties. Bypass: OP or invite.admin

access-control-mode: native

Temporary Invitations

check-interval-minutes

Key: temp-invites.check-interval-minutes | Type: integer | Default: 60

How often to check for and revoke expired temporary invites (in minutes).

temp-invites:
  check-interval-minutes: 60

Action Logging

max-entries

Key: action-log.max-entries | Type: integer | Default: 0

Max action log entries to keep. 0 = unlimited.

action-log:
  max-entries: 0

profile-history-limit

Key: action-log.profile-history-limit | Type: integer | Default: 5

Recent action entries shown per player in /im log list.

action-log:
  profile-history-limit: 5

Invite Chain Break

Controls how deep the invite chain can go. When enabled, players who were invited by another player (not directly by an admin or console) can be restricted from inviting others.

How it works: every invite record stores a depth value.

Console or admins (op / invite.admin) invite someone → that player gets depth 0
A depth-0 player invites someone → that player gets depth 1
A depth-1 player invites someone → depth 2, and so on

The max-depth value sets the highest depth that can still send invites. Players at or above that depth are blocked.

Example with max-depth: 1:

Who invites	Invited player depth	Can they invite?
Admin / Console	0	✅ Yes
Depth-0 player	1	❌ No (`1 >= max-depth`)

enabled

Key: chain-break.enabled | Type: boolean | Default: false

Enable invite chain restriction. When false, all players can freely invite up to their max-invites limit as normal.

chain-break:
  enabled: false

max-depth

Key: chain-break.max-depth | Type: integer | Default: 1

Maximum invite depth that can still invite others. Players whose depth equals or exceeds this value are blocked.

Value	Effect
`0`	Only admins/console can invite (no player can invite)
`1`	Only players directly invited by admin/console can invite
`2`	Two generations can invite; the third cannot

chain-break:
  max-depth: 1

Join Notifications

welcome-message

Key: join-notifications.welcome-message.enabled | Type: boolean | Default: true

Send welcome message to new players on first join (shows inviter).

join-notifications:
  welcome-message:
    enabled: true

inviter-notification

Key: join-notifications.inviter-notification.enabled | Type: boolean | Default: true

Notify inviter when their invitee joins for the first time.

join-notifications:
  inviter-notification:
    enabled: true

Mutual Invite Boost

XP boost for players directly linked by an invite (inviter ↔ invitee). Activates when both online, same world, within radius.

enabled

Key: mutual-invite-boost.enabled | Type: boolean | Default: true

Enable the boost system.

mutual-invite-boost:
  enabled: true

radius

Key: mutual-invite-boost.radius | Type: map<string, integer> | Default: {overworld: 50, nether: 75, end: 100}

Activation radius (blocks) per world.

mutual-invite-boost:
  radius:
    overworld: 50
    nether: 75
    end: 100
    # Custom worlds (optional):
    # mining_world: 60

xp-multiplier

Key: mutual-invite-boost.xp-multiplier | Type: decimal | Default: 1.5

XP gain multiplier. 1.0 = normal, 1.5 = +50%, 2.0 = +100%.

mutual-invite-boost:
  xp-multiplier: 1.5

check-interval

Key: mutual-invite-boost.check-interval | Type: integer | Default: 5

Proximity check interval (seconds). Recommended: 5-10.

mutual-invite-boost:
  check-interval: 5

show-actionbar

Key: mutual-invite-boost.show-actionbar | Type: boolean | Default: true

Show actionbar message when boost starts/stops.

mutual-invite-boost:
  show-actionbar: true

particle-effects

Key: mutual-invite-boost.particle-effects | Type: boolean | Default: true

Particle effects on boost transitions (happy villager = start, red dust = end).

mutual-invite-boost:
  particle-effects: true

cooldown-seconds

Key: mutual-invite-boost.cooldown-seconds | Type: integer | Default: 30

Cooldown after boost ends (shown in actionbar).

mutual-invite-boost:
  cooldown-seconds: 30

max-boost-partners

Key: mutual-invite-boost.max-boost-partners | Type: integer | Default: 3 (Range: 1-10)

Max simultaneous boost partners per player.

mutual-invite-boost:
  max-boost-partners: 3

max-multiplier

Key: mutual-invite-boost.max-multiplier | Type: decimal | Default: 2.5

Cap on total multiplier (prevents stacking abuse).

mutual-invite-boost:
  max-multiplier: 2.5

min-xp-for-boost

Key: mutual-invite-boost.min-xp-for-boost | Type: integer | Default: 1

Minimum XP gain to trigger boost.

mutual-invite-boost:
  min-xp-for-boost: 1

max-xp-per-event

Key: mutual-invite-boost.max-xp-per-event | Type: integer | Default: 1000

Max XP per single event (prevents exploit).

mutual-invite-boost:
  max-xp-per-event: 1000

streak-window-seconds

Key: mutual-invite-boost.streak-window-seconds | Type: integer | Default: 10 (Range: 2-60)

Seconds without XP before streak resets (“Combo broken!”).

mutual-invite-boost:
  streak-window-seconds: 10

xp-sharing.enabled

Key: mutual-invite-boost.xp-sharing.enabled | Type: boolean | Default: true

Share XP with boost partners.

mutual-invite-boost:
  xp-sharing:
    enabled: true

xp-sharing.share-percentage

Key: mutual-invite-boost.xp-sharing.share-percentage | Type: decimal | Default: 0.25

Percentage of earned XP given to each partner. 0.25 = 25%.

mutual-invite-boost:
  xp-sharing:
    share-percentage: 0.25

stats-flush-interval

Key: mutual-invite-boost.stats-flush-interval | Type: integer | Default: 30

Seconds between database flushes. 0 = write immediately (not recommended).

mutual-invite-boost:
  stats-flush-interval: 30

Plugin XP Progression

Unlock extra invite slots via Plugin XP from boost gameplay.

enabled

Key: plugin-xp-slots.enabled | Type: boolean | Default: false

Enable Plugin XP progression. Set false to use classic limits (max-invites / perms / groups).

plugin-xp-slots:
  enabled: false

invites-per-level

Key: plugin-xp-slots.invites-per-level | Type: integer | Default: 1

Extra invite slots unlocked per Plugin XP level.

plugin-xp-slots:
  invites-per-level: 1

levels

Key: plugin-xp-slots.levels | Type: map<integer, integer> | Default: {1: 100, 2: 300, 3: 700, 4: 1500, 5: 3000}

XP thresholds per level. Level 0 = base limit (no XP required).

plugin-xp-slots:
  levels:
    1: 100
    2: 300
    3: 700
    4: 1500
    5: 3000

levelup-sound

Key: plugin-xp-slots.levelup-sound | Type: string | Default: ENTITY_PLAYER_LEVELUP

Bukkit Sound enum name played on level-up.

plugin-xp-slots:
  levelup-sound: ENTITY_PLAYER_LEVELUP

Inactivity Slot Return

Auto-revoke invites to players who never join.

enabled

Key: inactivity-slot-return.enabled | Type: boolean | Default: false

Enable auto-revoke.

inactivity-slot-return:
  enabled: false

days

Key: inactivity-slot-return.days | Type: integer | Default: 30

Days before revoking if never joined. Once a player joins even once, check stops permanently.

inactivity-slot-return:
  days: 30

Re-Invite Restrictions

Prevent rapid re-invites of removed players.

enabled

Key: re-invite-restrictions.enabled | Type: boolean | Default: false

Enable restrictions.

re-invite-restrictions:
  enabled: false

max-removals

Key: re-invite-restrictions.max-removals | Type: integer | Default: 3

Removals before blocking (0 = disabled).

re-invite-restrictions:
  max-removals: 3

cooldown-days

Key: re-invite-restrictions.cooldown-days | Type: integer | Default: 7

Days before they can be re-invited after removal (0 = disabled).

re-invite-restrictions:
  cooldown-days: 7

Webhooks

Send HTTP POST requests to external URLs on invite events.

enabled

Key: webhooks.enabled | Type: boolean | Default: false

Enable webhooks.

webhooks:
  enabled: false

timeout-ms

Key: webhooks.timeout-ms | Type: integer | Default: 3000

Request timeout in milliseconds.

webhooks:
  timeout-ms: 3000

events

Key: webhooks.events | Type: map<string, string> | Default: all empty

Event URLs (empty = disabled for that event). Available events: invite, uninvite, expired, inactive_removed.

webhooks:
  events:
    invite: "https://example.com/webhook/invite"
    uninvite: "https://example.com/webhook/uninvite"
    expired: ""
    inactive_removed: ""

Bug Reports

Configuration for the /im report command, which generates a diagnostic snapshot and uploads it to a paste service, returning a clickable URL.

backend

Key: report.backend | Type: string | Default: pastefox

Upload backend to use.

Value	Description
`pastefox`	pastefox.com — supports expiry, visibility, and password protection
`mcloggs`	mclo.gs — anonymous, no configuration needed, Minecraft-specific log highlighting

report:
  backend: pastefox

Backend Comparison

Feature	PasteFox	mclo.gs
Log highlighting	Generic (`log` language)	✅ Minecraft-specific
Expiry control	✅ Configurable	❌ No control
Visibility	✅ PUBLIC / UNLISTED / PRIVATE	❌ Always public
Password protection	✅ Optional	❌ Not supported
API key	Optional (anonymous supported)	Not needed
Anonymous limit	PUBLIC only, max 7 days	—

pastefox.api-key

Key: report.pastefox.api-key | Type: string | Default: "" (empty)

Optional API key for PasteFox. Get one at pastefox.com/dashboard/api-keys.

Without a key: reports are forced to PUBLIC and expire after at most 7 days (enforced by PasteFox).

report:
  pastefox:
    api-key: "pk_your_api_key_here"

pastefox.visibility

Key: report.pastefox.visibility | Type: string | Default: UNLISTED

Visibility of uploaded reports. Requires an api-key for UNLISTED and PRIVATE.

Option	Description
`PUBLIC`	Anyone can find it via search
`UNLISTED`	Only accessible with the direct URL (recommended)
`PRIVATE`	Requires API key to view

report:
  pastefox:
    visibility: UNLISTED

pastefox.expires-hours

Key: report.pastefox.expires-hours | Type: integer | Default: 24

How long the report stays available, in hours. 0 = never expires.

Without api-key: maximum 168 hours (7 days), enforced by PasteFox
With api-key: no upper limit

report:
  pastefox:
    expires-hours: 24

pastefox.password

Key: report.pastefox.password | Type: string | Default: "" (empty)

Optional password to protect the report (4–100 characters). Leave empty to disable.

report:
  pastefox:
    password: ""

Example Configurations

Simple Setup (SQLite - Single Server)

storage:
  type: sqlite

language: "en"
access-control-mode: native
max-invites: 5
invite-cooldown: 30

mutual-invite-boost:
  enabled: true
  xp-multiplier: 1.5

version-checker:
  enabled: false

Production Setup (MySQL + LuckPerms)

storage:
  type: mysql
  remote:
    host: "db.production.com"
    port: 3306
    database: "inviteme"
    username: "inviteme_user"
    password: "SecurePassword123"
    pool-size: 20

language: "en"
access-control-mode: native
max-invites: 3

luckperms:
  enabled: true
  default-group: "member"
  group-limits:
    member: 3
    vip: 10
    moderator: 20
    admin: 99

mutual-invite-boost:
  enabled: true
  xp-multiplier: 1.5

version-checker:
  enabled: true
  notify-admins: true

Plugin Mode (Full Access Control)

storage:
  type: sqlite

language: "en"
access-control-mode: plugin
max-invites: 5

# Required: set white-list=false in server.properties

mutual-invite-boost:
  enabled: true

Boost-Enabled Setup

storage:
  type: sqlite

max-invites: 1  # Start small

mutual-invite-boost:
  enabled: true
  radius:
    overworld: 50
    nether: 75
    end: 100
  xp-multiplier: 2.0
  show-actionbar: true
  particle-effects: true
  xp-sharing:
    enabled: true
    share-percentage: 0.25

Chain Break Setup

# Only directly invited players (depth 0) can invite others.
# Their invitees (depth 1) cannot invite anyone.
chain-break:
  enabled: true
  max-depth: 1

max-invites: 5

Plugin XP Setup

storage:
  type: sqlite

max-invites: 1  # Base limit

plugin-xp-slots:
  enabled: true
  invites-per-level: 1
  levels:
    1: 100
    2: 300
    3: 700
    4: 1500
    5: 3000

mutual-invite-boost:
  enabled: true

Reloading Configuration

After editing config.yml:

/im reload

Check changes applied:

/im debug

What reloads: config.yml, language files, LuckPerms group limits, access control mode

What does NOT reload: Active database connections (requires restart), cached player heads in GUI

Troubleshooting

“Database connection failed”

Check host/port/credentials in config.yml
Ensure database exists
Check firewall rules

“Changes not applied”

Run /im reload
Check for YAML syntax errors
Verify file permissions

“LuckPerms limits not working”

Ensure LuckPerms installed
Set luckperms.enabled: true
Run /im reload
Check group exists: /lp listgroups