# RTP (Random Teleport)

## 🌍 RTP (Random Teleport)

RTP is a surprisingly opinionated feature — should it be GUI-driven? Biome-aware? Dimension-specific? We've taken a flexible approach that covers the most important use cases for Cobblemon networks — and is designed to grow over time.

Oxygen introduces **RTP Flows**, a system that gives you full control over *where* and *how* players teleport across your network. You define:

* **Flows** — groups of RTP options based on filters (e.g. current server)
* **Filters** — simple JSON objects that match player state (e.g. `{ "server": "spawn" }`)
* **Results** — one or more RTP settings applied if the filter matches

Right now, results are selected randomly and unweighted. In the future, you’ll be able to prefer servers with fewer players, better performance, or based on custom conditions.

***

### ⚙️ How RTP Works

When a player runs `/rtp`, Oxygen:

1. Iterates through all defined flows.
2. Checks whether the `filter` matches the player's current state.
3. If it matches, a random `result` (RTP settings) is selected from that flow.
4. The *last* matching flow overrides earlier ones.

Here’s a minimal example:

```json
"flows": [
  {
    "filter": { "server": "beta" },
    "result": [ { "server": "alpha" } ]
  },
  {
    "filter": { "server": "alpha" },
    "result": [ { "server": "beta" } ]
  }
]
```

If a player is on `beta`, they RTP to `alpha`. If they’re on `alpha`, they RTP to `beta`.

📄 `rtp_config.json` Example (Roanoke Diamond)

```json
{
  "defaultDimension": "minecraft:overworld",
  "defaultCenterX": 0,
  "defaultCenterZ": 0,
  "defaultMinDistance": 100,
  "defaultMaxDistance": 3000,
  "defaultHighestY": 320,
  "defaultMaxAttempts": 30,
  "defaultAllowCaveTeleports": false,
  "flows": [
    {
      "filter": { "server": "spawn" },
      "result": [
        { "server": "core" },
        { "server": "prime" },
        { "server": "haven" }
      ]
    },
    {
      "filter": { "server": "core" },
      "result": [ { "server": "core" } ]
    },
    {
      "filter": { "server": "prime" },
      "result": [ { "server": "prime" } ]
    },
    {
      "filter": { "server": "haven" },
      "result": [ { "server": "haven" } ]
    }
  ]
}
```

#### 🔄 Flow Summary

* **Spawn**: randomly RTPs players to `core`, `prime`, or `haven`
* **Core/Prime/Haven**: RTPs stay on the same server

Because only `server` is defined in each result, all other RTP settings (like distance and cave rules) fall back to the defaults at the top of the config.

### 🛠️ Customising Per-Server Settings

You can override default settings in a specific `result` object. For example, if you want a larger RTP radius on `prime`, just update its entries like so:

```json
{
  "server": "prime",
  "maxDistance": 10000
}
```

Update both the spawn flow *and* the prime flow if you want the setting to apply regardless of where the player comes from:

```json
{
  "filter": { "server": "prime" },
  "result": [ { "server": "prime", "maxDistance": 10000 } ]
}
```

### 🧾 Full RTP Settings Object

Each object in a `result` array represents an RTP destination with optional overrides.

```json
{
  "server": "core",
  "worldId": "minecraft:overworld",
  "centerX": 0,
  "centerZ": 0,
  "minDistance": 250,
  "maxDistance": 5000,
  "highestY": 320,
  "maxAttempts": 30,
  "allowCaveTeleports": false
}
```

* `server`: target server for RTP (required)
* `worldId`: Minecraft dimension to RTP in
* `centerX`, `centerZ`: the centre used for RTP ranges
* `minDistance`, `maxDistance`: range from (0, 0)
* `highestY`: cap Y-level (e.g. avoid mountains)
* `maxAttempts`: number of times to try finding a valid location
* `allowCaveTeleports`: whether caves are valid RTP spots

Any keys not defined will fall back to the global defaults at the top of `rtp_config.json`.

{% hint style="warning" %}
**Teleporting to The Nether?**

**Make sure to set "allowCaveTeleports" to true!**
{% endhint %}

## Setting Unsafe/Air Blocks

You can edit what RTP considers an unsafe block / air block in /config/Oxygen/config.json.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roanoke.dev/mods/mods/oxygen/rtp-random-teleport.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.