Access Control Modes

InviteMe supports two modes for controlling which players can join your server. This guide explains the difference and when to use each.

The Two Modes

access-control-mode: native   # default
access-control-mode: plugin

Native Mode (Default)

InviteMe works alongside Minecraft’s built-in whitelist.

How It Works

Player tries to join
       ↓
Minecraft whitelist check (whitelist.json)
       ↓
✓ Player is whitelisted → joins server
✗ Player not whitelisted → rejected by Minecraft

When you run /invite add Steve, InviteMe adds Steve to Minecraft’s whitelist.json automatically. When you run /invite remove Steve, InviteMe removes Steve from whitelist.json.

Requirements

white-list=true in server.properties (standard setup)
No extra configuration needed

Pros

✅ Compatible with all other plugins
✅ Works with standard Minecraft whitelist tools
✅ Easy to understand — behaves like vanilla whitelist
✅ Recommended for most servers

Cons

Whitelist logic split between Minecraft and InviteMe
Manual edits to whitelist.json may create inconsistencies (use /im sync to fix)

Plugin Mode

InviteMe takes full control of who can join. Minecraft’s whitelist is bypassed.

How It Works

Player tries to join
       ↓
InviteMe checks its own database (AsyncPlayerPreLoginEvent)
       ↓
✓ Player is in InviteMe database → joins server
✗ Player not in database → rejected by InviteMe

The server’s whitelist.json is ignored entirely.

Requirements

white-list=false in server.properties:

white-list=false

If white-list=true while using plugin mode, the Minecraft whitelist will still block players even if InviteMe would allow them.

Pros

✅ Single source of truth — InviteMe’s database controls everything
✅ Better integration with permissions (uses LuckPerms async check)
✅ Server operators with invite.admin always bypass (no lockout risk)
✅ Useful for networks where whitelist.json is unreliable

Cons

whitelist.json becomes unused — standard Minecraft tools won’t affect access
Requires white-list=false which some admins find unintuitive
Other plugins that rely on Minecraft’s whitelist events may not work

Switching Between Modes

Switching to Plugin Mode

Edit server.properties:
```
white-list=false
```
Edit plugins/InviteMe/config.yml:
```
access-control-mode: plugin
```
Reload:
```
/im reload
```

Verify:

/im debug
# Should show: Access control: plugin

Switching Back to Native Mode

Edit server.properties:
```
white-list=true
```
Edit config.yml:
```
access-control-mode: native
```
Reload:
```
/im reload
```
Run sync to ensure whitelist.json is in sync with InviteMe’s database:
```
/im sync
```

Bypass Rules (Plugin Mode)

In plugin mode, players are always allowed through if they have:

Server OP status (ops.json)
invite.admin permission (via LuckPerms or other permission plugin)

This prevents admin lockout if the database has an issue.

Which Mode Should I Use?

Use native (default) if:

You’re setting up InviteMe for the first time
You use other plugins that interact with the whitelist
You want familiar Minecraft whitelist behavior
You’re migrating from vanilla whitelist

Use plugin if:

You want InviteMe to be the single authority on access
You’re on a network where whitelist.json isn’t reliable
You want tighter LuckPerms integration for access checks
You’ve decided to fully commit to InviteMe for access control

For most servers, native mode is the right choice.

Troubleshooting

“Player can join even though I removed them via InviteMe (native mode)”

✅ Run /im sync — the player may still be in whitelist.json
✅ Check with /invite list that they’re actually removed

“Nobody can join after switching to plugin mode”

✅ Make sure white-list=false in server.properties
✅ Restart the server (not just reload) after changing server.properties
✅ Run /im sync to populate InviteMe’s database from existing whitelist

“My admin can’t join after switching to plugin mode”

✅ Make sure the admin is in ops.json OR has invite.admin permission
✅ Run /im debug to verify plugin mode is active
✅ If locked out, add white-list=false + restart will let ops through

Next Steps

⚙️ Full config: Config Reference
🔗 LuckPerms: LuckPerms Integration
🔑 Permissions: Permissions Guide