Configuration Reference¶
One jar covers every platform. Configuration is generated on first server start and lives under plugins/RTP/ on the Bukkit family (Paper, Spigot, Folia and their forks, Arclight, Mohist) or under config/rtp/ on Fabric / NeoForge.
How to Update Configuration¶
RTP provides multiple ways to view and update settings (starting with the visual web workspace and region definitions):
- Browser Map Workspace (
/rtp editor): The recommended first thing to try - visually drag region borders (shape.radius,centerRadius,POLYGONvertices) on a 2D map, configuredefinitions/regions/*.yml(shapeandvertsettings) anddefinitions/worlds/*.ymlmappings with inline docs, and preview diffs before applying (WEB_EDITOR_GUIDE.md). - Guided Setup & Admin Menu (
/rtp admin setup//rtp admin): Run/rtp admin setupfor the guided multi-world and radius wizard, or/rtp adminfor the in-game book editor (IN_GAME_CONFIG.md). - Command Line (
/rtp config <section> <key>=<value>): Quick runtime updates from console or chat with immediate atomic persistence (e.g./rtp config regions default shape.radius=5000b). - Direct File Editing (
plugins/RTP/definitions/regions/...): Edit YAML files directly and run/rtp reloadto apply changes.
📎 Detailed Admin Guides: See WEB_EDITOR_GUIDE.md and IN_GAME_CONFIG.md for full instructions on
/rtp editor,/rtp admin setup, and/rtp config.Folder layout: the everyday files (
config.yml,economy.yml,language.yml,safety.yml) sit at the top level. The named definitions you author (regions/,worlds/,effects/, plus the sharedshape/andvert/catalogs) live underdefinitions/. The rarely-hand-edited tuning and text files (performance.yml,logging.yml,metrics.yml,ttl.yml,network.yml,database.yml,biomes.yml,blocks.yml, themessages/tree, and theschematics/folder) live underadvanced/. The per-locale translation mirror stays atlang/. Each rename map is a co-located hidden dotfile (.<name>.lang.yml) beside the file it describes. On upgrade from an older layout, RTP relocates your authored files automatically and archives the old folders as<name>.migrated.Inheritance: to avoid repeating the same value across many region/world files, a region/world setting can inherit a global default with an
@<file>token (e.g.@config,@economy). See CORE_CONFIG.md → Defaults (inheritance).📎 How RTP loads, reloads, and upgrades these files (including what the
.old1/.old2files are, and how your customizations are preserved across version bumps and locale switches): see CONFIG_LIFECYCLE.md.
File Overview¶
| File | Purpose | Detailed Reference |
|---|---|---|
config.yml |
Core plugin settings (delays, database) | CORE_CONFIG.md |
economy.yml |
Teleport costs and refund policy (requires Vault) | ECONOMY.md |
safety.yml |
Landing safety checks, invulnerability, biome filters | SAFETY.md |
language.yml |
Locale selection (loaded before all other files) | LANGUAGE.md |
definitions/regions/*.yml |
Per-region teleport area, shape, queue settings | REGIONS.md |
definitions/worlds/*.yml |
Per-world default region and permission settings | WORLDS.md |
definitions/effects/*.yml |
Per-event teleport effects (sounds, particles, potions) | EVENTS_AND_EFFECTS.md |
advanced/performance.yml |
Background task timing, cache behaviour, TPS thresholds | PERFORMANCE.md |
advanced/messages/*.yml |
All player-facing message strings (split by concern) | MESSAGES.md |
advanced/logging.yml |
Console logging verbosity | LOGGING.md |
advanced/metrics.yml |
Runtime-health metrics SPI reporting knobs | METRICS.md |
advanced/ttl.yml |
Spatial memory expiration and cause-based TTL tiers | TTL.md |
advanced/bit.yml |
BIT finding severity and strict action registration | BIT.md |
advanced/network.yml |
Multi-server / multi-proxy network mode | proxies/CONFIGURATION.md |
advanced/database.yml |
Database backend and connection settings | CORE_CONFIG.md |
advanced/biomes.yml, advanced/blocks.yml |
Biome / block tag catalogs used by safety filters | SAFETY.md |
advanced/schematics/ |
Per-region arrival structures (.schem or .litematic) pasted on landing; also where prefabs drop their bundled schematic |
SCHEMATICS.md |
definitions/regions/<name>.yml — Region Configuration¶
Each file in the definitions/regions/ folder defines one teleport region. The filename (without .yml) is the region's name.
📎 Detailed Reference: See REGIONS.md for a full breakdown of every key and engine parameter in the region configuration.
Top-level keys¶
| Key | Type | Default | Description |
|---|---|---|---|
world |
String | "[0]" |
Target world name. [0] = main world, [1] = the_nether, [2] = the_end, or a literal world name. Create a dedicated region per world in definitions/regions/ and map it in definitions/worlds/. |
worldBorderOverride |
Boolean | false |
Not generally recommended. If true, replaces the entire shape block (ignoring radius and centerRadius) with a square matching the vanilla /worldborder. Prefer setting shape.radius with a unit suffix (e.g. 2500b or 5km) in definitions/regions/<name>.yml or /rtp editor. |
requirePermission |
Boolean | false |
If true, players need rtp.regions.<regionName> to use this region. |
override |
String | "default" |
Region to redirect to if a player lacks permission for this region. |
cacheCap |
Integer | 50 |
Maximum pre-generated safe locations to hold in the queue. Set to 0 to disable background caching. |
backlogCacheCap |
Integer | 1000 |
Maximum unverified candidates staged upstream of cacheCap. Spiral picks land here without chunk I/O, then a per-region pulse verifies one .mca bin at a time and promotes in insertion order. Set to 0 to disable. See REGIONS.md → Backlog Cache (L3). |
activeChunkCap |
Integer | 10 |
Maximum chunks kept loaded simultaneously for zero-latency teleportation. |
price |
Double | 0.0 |
Economy cost override for this region (overrides the global economy.yml price). |
cooldown |
Integer / Duration / String | (global fallback) | Per-region cooldown duration between successful teleports. Accepts seconds, duration strings (5m), or "@config". Negative values / sentinels (-1, infinite, permanent) are not supported per region: they are ignored and the region falls back to the global teleportCooldown and shared timer. Defaults to global teleportCooldown. |
delay |
Integer / Duration / String | (global fallback) | Per-region warmup delay before teleporting. Accepts seconds, duration strings (5s, 40t), 0 (instant), or "@config". Defaults to global teleportDelay. |
spatialResolution |
Integer / String | "auto" |
Precision for spatial memory (bad location tracking). Can be "auto" or any positive integer (e.g. 1, 3, 4). Higher values check fewer, more widely spaced spots (faster scans, less memory, but can miss small safe pockets). |
version |
String | "1.0" |
Internal config version (do not change). |
shape section¶
The shape block defines how horizontal coordinates are selected. The name key selects the shape engine; the remaining keys configure it.
Keys common to all shapes¶
| Key | Type | Description |
|---|---|---|
name |
String | Shape: CIRCLE (default), SQUARE, RECTANGLE, ELLIPSE, or POLYGON. |
mode |
String | Selection logic. See table below. |
centerX |
Integer | Chunk X coordinate of the region centre (default 0). |
centerZ |
Integer | Chunk Z coordinate of the region centre (default 0). |
uniquePlacements |
Integer | Chunk radius cleared around each used location so it is never reused. 0 = off (default), 1 = the landing chunk only, N = an (2N-1)x(2N-1) chunk square centred on the landing chunk. (Legacy true/false are still accepted and map to 1/0.) |
mode options:
| Value | Behaviour |
|---|---|
ACCUMULATE |
Even distribution; accumulates all sectors up to the current point to compute a shift, with distances precomputed at region load. Recommended default. |
NEAREST |
Tries the closest non-blocked spot. Fast, but can cause clustering near edges. |
REROLL |
Re-selects when a bad sector is hit. Even distribution and fast, but not strictly bounded. |
NONE |
No pre-check at all. Best for massive radii where pre-checking is impractical. |
CIRCLE and SQUARE — additional keys¶
| Key | Type | Default | Description |
|---|---|---|---|
radius |
Integer / Distance | 256 |
Maximum distance from the centre in chunks (supports spatial suffixes, e.g. 4096b, 256c, 4r, 5km). |
centerRadius |
Integer / Distance | 64 |
Minimum distance from the centre (donut hole) in chunks (supports spatial suffixes, e.g. 1024b, 64c). Players won't land inside this radius. |
weight |
Double | 1.0 |
Distribution weight. > 1.0 shifts landings toward the centre; < 1.0 shifts toward the edge. |
expand |
Boolean | false |
If true, the radius grows automatically as locations are consumed. |
RECTANGLE — additional keys¶
| Key | Type | Default | Description |
|---|---|---|---|
width |
Integer / Distance | — | Full width of the rectangle (total X-axis extent, centred on the region; supports spatial suffixes). |
height / length |
Integer / Distance | — | Full height / length of the rectangle (total Z-axis extent, centred on the region; supports spatial suffixes). |
rotation |
Double | 0.0 |
Rotation of the rectangle in degrees around the centre. |
ELLIPSE — additional keys¶
| Key | Type | Default | Description |
|---|---|---|---|
radius / radius2 |
Integer / Distance | 256 |
The two outer semi-axes in chunks (supports spatial suffixes). The wider of the two bounds the spiral mapping. |
centerRadius / centerRadius2 |
Integer / Distance | 0 |
The two semi-axes of the inner exclusion ellipse, in chunks. |
rotation |
Double | 0.0 |
Rotation of both the outer and inner ellipse in degrees around the centre. |
weight |
Double | 1.0 |
Distribution weight, same meaning as CIRCLE. |
expand |
Boolean | false |
If true, the radii grow automatically as locations are consumed. |
POLYGON — additional keys¶
| Key | Type | Default | Description |
|---|---|---|---|
vertices |
List of [x, z] pairs |
— | Boundary vertices in traversal order, in the same format Chunky uses: one pair per list item, e.g. - [-125c, 187c] / - [2000b, 3000b], or inline vertices: [[-125c, 187c], [2000b, 3000b], [10, -4]]. Each coordinate takes a spatial suffix (b blocks, c chunks, ...); a coordinate without a suffix is in chunks. At least 3, not all collinear, no self-intersections. Invalid or self-intersecting vertices trigger a warning and fall back to the bounding square. See REGIONS.md. |
weight |
Double | 1.0 |
Distribution weight across the vertex bounding box. |
expand is not part of the polygon surface and is ignored: the boundary is admin-authored, so growing it would push landings outside it.
Advanced / Legacy Benchmark Shape Aliases (Optional)
Normal servers never need these aliases — standard `CIRCLE` and `SQUARE` already use the current engine by default. These names exist only for bell-curve customization, legacy config migration, or side-by-side benchmark tests: - `CIRCLE_NORMAL` and `SQUARE_NORMAL`: Gaussian bell-curve variants that replace `weight` with `mean` (`0.0` = centre, `1.0` = edge) and `deviation` (smaller = tighter cluster; larger = wider spread), alongside `radius`, `centerRadius`, and `expand`. - `CIRCLE_OPTIMIZED_DUAL_LAYER` and `SQUARE_OPTIMIZED_DUAL_LAYER`: Explicit aliases for the default `CIRCLE` and `SQUARE` engine (accepts the same keys as `CIRCLE` and `SQUARE`). - `CIRCLE_DEPRECATED_PURE_SPIRAL` and `SQUARE_DEPRECATED_PURE_SPIRAL`: Legacy v1/v2 shapes retained for backwards compatibility and regression testing.vert section¶
The vert block controls how the Y coordinate (height) is chosen once a horizontal position is selected.
Keys common to all vert adjustors¶
| Key | Type | Default | Description |
|---|---|---|---|
name |
String | "JUMP" |
Vertical adjustor engine: JUMP, LINEAR, or FIXED. |
minY |
Integer | 32 |
Minimum Y level a player can land at. |
maxY |
Integer | 255 |
Maximum Y level a player can land at. |
requireSkyLight |
Boolean | false |
If true, only accept locations with direct sky access (above-ground only). |
maxHillAngle |
"off" or degrees |
"off" |
LINEAR and JUMP only. Refuse landings on hillsides or cliff edges this steep or steeper. Suggested values: "off" (fastest), 30, 45, 60. See REGIONS.md. |
maxSlope |
Integer | -1 |
LINEAR and JUMP only. Largest floor-Y step (in blocks) allowed between the landing spot and the floor slopeRadius blocks away (-1 or omitted = disabled, 0 = flat ground only). See REGIONS.md. |
slopeRadius |
Integer | 2 |
LINEAR and JUMP only. Horizontal distance (in blocks, 1 to 8) from the landing spot where maxSlope samples the floor. |
JUMP — additional keys¶
| Key | Type | Default | Description |
|---|---|---|---|
step |
Integer | 16 |
Number of blocks to skip per vertical search iteration. Larger = faster but coarser scan. |
LINEAR — additional keys¶
| Key | Type | Default | Description |
|---|---|---|---|
direction |
Integer | 2 |
Search direction: 0 = bottom-up (scan from minY to maxY), 1 = top-down (scan from maxY to minY), 2 = middle-out (default), 3 = edges-in, any other integer = randomized order. |
FIXED — additional keys¶
| Key | Type | Default | Description |
|---|---|---|---|
y |
Integer | 64 |
Exact Y level for mid-air placement. No terrain scan runs, so minY, maxY, direction, and requireSkyLight are ignored. Intended for skyblock-style worlds; pair it with a platform builder or the player falls through air. See REGIONS.md. |
Full example — a nether region:
world: "world_nether"
worldBorderOverride: false
requirePermission: false
override: "default"
cacheCap: 10
activeChunkCap: 5
price: 0.0
spatialResolution: "auto"
shape:
name: "CIRCLE"
mode: "ACCUMULATE"
radius: 128
centerRadius: 32
centerX: 0
centerZ: 0
weight: 1.0
uniquePlacements: 0
expand: false
vert:
name: "JUMP"
minY: 32
maxY: 120
step: 16
requireSkyLight: false
definitions/worlds/<name>.yml — World Configuration¶
Each file in the definitions/worlds/ folder maps a world to its default region and permission settings. See WORLDS.md for the complete reference.
| Key | Type | Default | Description |
|---|---|---|---|
region |
String | "default" |
Default region used when a player runs /rtp in this world. |
requirePermission |
Boolean | false |
If true, players need rtp.worlds.<name> to RTP in this world. |
override |
String | "[0]" |
World to redirect to if a player lacks permission. |
version |
String | "1.0" |
Internal version — do not change. |
Dedicated Configuration Guides¶
For in-depth explanations and complete key tables of each configuration file:
- Core & Defaults: CORE_CONFIG.md
- Safety & Hazard Checks: SAFETY.md
- Economy (Vault): ECONOMY.md
- Language / Locale: LANGUAGE.md
- Regions: REGIONS.md
- Worlds: WORLDS.md
- Events & Effects: EVENTS_AND_EFFECTS.md
- Performance: PERFORMANCE.md
- Messages: MESSAGES.md
- Logging: LOGGING.md
- Metrics: METRICS.md
- Multi-Server / Proxy Network: proxies/CONFIGURATION.md
- Arrival Schematics: SCHEMATICS.md
Custom Shapes and Addons¶
The built-in shape engines (CIRCLE, CIRCLE_NORMAL, CIRCLE_OPTIMIZED_DUAL_LAYER, CIRCLE_DEPRECATED_PURE_SPIRAL, SQUARE, SQUARE_NORMAL, SQUARE_OPTIMIZED_DUAL_LAYER, SQUARE_DEPRECATED_PURE_SPIRAL, ELLIPSE, RECTANGLE, POLYGON) are configured inline inside each region's shape: block, as there are no separate per-shape config files.
That list is the set this build registers at startup. Addons can register more, so the authoritative list for your install is written to plugins/RTP/definitions/regions/SHAPES.md (and VERT.md for vertical adjustors) on every start and /rtp reload, generated from the live registry.
Custom shapes can be registered at runtime via rtp-api. See addons/ for examples. A registered custom shape appears as a valid shape.name value in any region config.
Tips¶
- Run
/rtp reloadafter every edit; no restart needed. - Never change
version:fields, as they are used internally for config migration. - Use
[0],[1],[2]as world placeholders instead of hardcoded names if your world names may change. - Set
cacheCapto match your player count — a server with 50 concurrent players benefits from a larger cache than a server with 5. - Lower
minTPS(e.g.,18.0) on busy servers to prevent the plugin from adding load during lag spikes.