auth-limbo/docs/configuration.md

# Configuration reference

`plugins/AuthLimbo/config.yml` is created on first start with the
defaults below. Reload at runtime with `/authlimbo reload`.

```yaml
limbo:
  world: auth_limbo
  spawn-x: 0.5
  spawn-y: 128.0
  spawn-z: 0.5
  build-platform: true
  platform-y: 127

authme:
  db-path: plugins/AuthMe/authme.db
  teleport-delay-ticks: 10
  preload-chunks: true

debug: false
```

## `limbo.*`

Settings for the void auth-limbo world. The plugin creates this world
on enable if it does not already exist.

### `limbo.world`

| | |
|---|---|
| Type | string |
| Default | `auth_limbo` |

The Bukkit world name. The world folder will live at the server data
root (`<world-name>/`). Changing this **after** the world has been
created will cause the plugin to create a second world with the new
name on next start; the old one is left on disk and you can delete it
manually.

### `limbo.spawn-x`, `limbo.spawn-y`, `limbo.spawn-z`

| | |
|---|---|
| Type | double |
| Defaults | `0.5`, `128.0`, `0.5` |

World spawn coordinates inside `auth_limbo`. The `.5` offsets put the
player on the centre of a block, which avoids fall-through edge cases
when standing on the barrier platform.

### `limbo.build-platform`

| | |
|---|---|
| Type | boolean |
| Default | `true` |

If true, the plugin builds a 5x5 patch of `BARRIER` blocks at
`platform-y` directly under spawn so unauth players cannot fall into
the void. Disable if you want to manage the platform yourself with a
schematic.

### `limbo.platform-y`

| | |
|---|---|
| Type | integer |
| Default | `127` |

Y-level of the barrier platform. Should be exactly one below `spawn-y`
so players land on top of the barriers.

## `authme.*`

Settings for the AuthMe integration.

### `authme.db-path`

| | |
|---|---|
| Type | string |
| Default | `plugins/AuthMe/authme.db` |

Path to AuthMe's SQLite database. Resolved relative to the server data
directory if not absolute. Only SQLite is supported — if your AuthMe
deployment uses MySQL, this plugin won't read your data and the
LoginEvent restore will be a no-op.

### `authme.teleport-delay-ticks`

| | |
|---|---|
| Type | long |
| Default | `10` (≈ 0.5 s at 20 TPS) |

How many ticks to wait after AuthMe's `LoginEvent` fires before issuing
our authoritative teleport. The delay exists so AuthMe's own (broken)
teleport runs first; we then overwrite the player position with the
correct one.

If you see players briefly appearing at world spawn before snapping to
their saved location, lower this value. If you see the saved-location
teleport fail because some other plugin teleports the player in
between, raise it.

### `authme.preload-chunks`

| | |
|---|---|
| Type | boolean |
| Default | `true` |

If true, the plugin listens to `AuthMeAsyncPreLoginEvent` and pins the
chunk at the saved quit-location with `Chunk#addPluginChunkTicket`
before the password check completes. This warms the chunk so the actual
`getChunkAtAsyncUrgently` + `teleportAsync` chain roughly 1 second
later does not race against an unloaded chunk
([PaperMC/Paper#4085](https://github.com/PaperMC/Paper/issues/4085)).

The ticket is released ~5 seconds after the teleport completes — long
enough for the client to download the chunk before it can unload.

Disabling this is safe — the post-login `getChunkAtAsyncUrgently` call
will still load the chunk before teleporting — but you may see the
original teleport bug re-emerge under load if AuthMe's own teleport
fires before the chunk is ready.

## `debug`

| | |
|---|---|
| Type | boolean |
| Default | `false` |

If true, the plugin logs every chunk forceload, every teleport result,
and every "no saved location" decision at INFO level. Useful when
diagnosing a player report; noisy in production.

`limbo.world` cannot be changed without a full server restart — the
limbo world is created during `onEnable`. Other keys take effect on
`/authlimbo reload`.