Player Teleport

Player Teleport

Player Teleport is a Fabric server-first mod that lets regular players teleport to other online players without requiring operator permission.

The interaction model is intentionally minimal:

• use /pt to view online players
• click chat buttons to teleport
• use simple commands to decide who can teleport to you
• let administrators choose between direct teleport and request-based confirmation
• let administrators manage global behavior and team rules

Contents

• Overview
• Interaction Design
• Permission Rules
• Compatibility
• Dependencies
• Installation
• Player Commands
• Admin Commands
• Configuration
• Development and Build

Overview

• paged online player list
• clickable teleport actions in chat
• online player search
• random teleport to an eligible player
• each player can directly allow or deny who may teleport to them
• optional target approval before teleport happens
• target players can approve or reject requests through chat buttons or commands
• separate outgoing and incoming rules
• whitelist and blacklist support
• admin-configurable team teleport shortcuts
• admin-configurable global switches, cross-dimension behavior, request timeout, random teleport, page size, and cooldown
• persistent storage for player rules and cached player names

Interaction Design

Player Experience

• Run /pt to open the online player list
• Eligible targets show a green clickable button
• Ineligible targets show a direct reason instead
• The header includes quick buttons for random and rules
• Page navigation is handled through previous and next buttons
• Use /pt allow <player> or /pt deny <player> for direct control over who may teleport to you
• When approval mode is enabled, teleport attempts create a request instead of teleporting immediately
• The target player can use chat buttons or /pt accept <player> and /pt reject <player> to respond

Admin Experience

• Use /ptadmin to inspect current global settings
• Use /ptadmin set ... to update global configuration
• Use /ptadmin player <player> reset to reset one player’s rules
• Configure team-based shortcuts such as same-team bypass or same-team-only teleport
• Configure whether teleport requires target approval and how long requests remain valid

Permission Rules

A teleport is allowed only when all of the following checks pass:

1. the global feature is enabled
2. cross-dimension teleport is allowed when needed
3. same-team-only restrictions are satisfied when enabled
4. the source player is not on cooldown
5. the source player’s outgoing rule allows the target
6. the target player’s incoming rule allows the source
7. when approval mode is enabled, the target accepts the request before it expires

Rule Modes

| Mode | Meaning |
| — | — |
| all | allow everyone |
| none | deny everyone |
| whitelist | allow only listed players |
| blacklist | deny listed players and allow the rest |

Rule Directions

| Direction | Meaning |
| — | — |
| outgoing | who I can teleport to |
| incoming | who can teleport to me |

Team Rules

Administrators can configure teleport behavior around vanilla scoreboard teams:

• allowSameTeamBypassRules = true: same-team players bypass personal outgoing and incoming checks
• sameTeamOnly = true: teleport is allowed only between players on the same team

Compatibility

| Item | Requirement |
| — | — |
| Minecraft | 1.21 to 1.21.11 |
| Fabric Loader | 0.16.0+ |
| Java | 21+ |
| Fabric API | Required |
| Fabric Language Kotlin | Required |

The project currently targets Minecraft 1.21.11.

Dependencies

Install the following dependencies into the target mods directory together with this mod:

| Dependency | Required | Notes |
| — | — | — |
| Fabric API | Yes | Provides Fabric commands and runtime APIs |
| Fabric Language Kotlin | Yes | Required because this mod is written in Kotlin |

Installation

Server-first Usage

This mod is designed primarily as a server-side mod:

• Dedicated server: normally only the server needs this mod and its dependencies
• Singleplayer: local installation is still required because singleplayer uses an integrated server

Player Commands

| Command | Description |
| — | — |
| /pt | Show the first page of the online player list |
| /pt page <page> | Show a specific page |
| /pt search <keyword> | Search online players |
| /pt search <keyword> <page> | Search with pagination |
| /pt tp <player> | Teleport directly, or send a request when approval mode is enabled |
| /pt random | Teleport randomly to an eligible player |
| /pt rules | Show your current rule summary |
| /pt allow <player> | Directly allow a player to teleport to you and switch to incoming whitelist mode |
| /pt deny <player> | Directly deny a player from teleporting to you and switch to incoming blacklist mode |
| /pt accept <player> | Accept a pending teleport request |
| /pt reject <player> | Reject a pending teleport request |
| /pt mode outgoing <mode> | Set your outgoing mode |
| /pt mode incoming <mode> | Set your incoming mode |
| /pt add outgoing <player> | Add a player to your outgoing list |
| /pt add incoming <player> | Add a player to your incoming list |
| /pt remove outgoing <player> | Remove a player from your outgoing list |
| /pt remove incoming <player> | Remove a player from your incoming list |

Admin Commands

| Command | Description |
| — | — |
| /ptadmin | Show the current global config summary |
| /ptadmin reload | Reload the config file |
| /ptadmin set enabled <true|false> | Enable or disable the feature |
| /ptadmin set allowCrossDimension <true|false> | Enable or disable cross-dimension teleport |
| /ptadmin set allowRandom <true|false> | Enable or disable random teleport |
| /ptadmin set requireTargetApproval <true|false> | Require target-side approval before teleport |
| /ptadmin set requestTimeoutSeconds <5-120> | Set request expiration time |
| /ptadmin set allowSameTeamBypassRules <true|false> | Let same-team players bypass personal rules |
| /ptadmin set sameTeamOnly <true|false> | Restrict teleport to same-team players only |
| /ptadmin set pageSize <4-20> | Set page size |
| /ptadmin set cooldownSeconds <0-300> | Set teleport cooldown |
| /ptadmin set defaultOutgoing <mode> | Set the default outgoing mode for new players |
| /ptadmin set defaultIncoming <mode> | Set the default incoming mode for new players |
| /ptadmin player <player> reset | Reset one player’s rules |

Configuration

Config file path:

config/player-teleport.json

Default key settings:

{
  "enabled": true,
  "allowCrossDimension": true,
  "allowRandom": true,
  "requireTargetApproval": false,
  "requestTimeoutSeconds": 20,
  "allowSameTeamBypassRules": false,
  "sameTeamOnly": false,
  "pageSize": 8,
  "cooldownSeconds": 3,
  "defaultOutgoingMode": "ALL",
  "defaultIncomingMode": "ALL"
}

Notes:

• playerNames caches player display names for cleaner list output
• players stores outgoing and incoming rules by UUID
• The direct allow and deny commands operate on incoming rules
• When requireTargetApproval = true, regular teleport actions become request-based

中文

Player Teleport 是一个 Fabric 服务端优先模组，用于让普通玩家在没有 OP 权限的情况下，快速传送到其他在线玩家身边。

设计目标是把操作压缩到最少：

• 用 /pt 查看在线玩家列表
• 直接点击聊天按钮完成传送
• 用简单命令决定谁可以传送到自己身边
• 管理员可选择“直接传送”或“请求后确认”
• 由管理员统一控制全局行为和队伍规则

目录

• 功能概览
• 交互设计
• 权限规则
• 兼容性
• 依赖
• 安装方式
• 玩家命令
• 管理员命令
• 配置说明
• 开发与构建

功能概览

• 在线玩家分页展示
• 聊天消息点击传送
• 搜索在线玩家
• 随机传送到当前可用玩家
• 每个玩家都可以直接允许或禁止指定玩家传送到自己身边
• 支持管理员开启“目标玩家确认后才传送”
• 目标玩家可通过聊天点击或命令同意、拒绝传送请求
• 发送规则与接收规则分离
• 支持白名单与黑名单
• 支持管理员配置同队传送快捷规则
• 管理员可配置全局开关、跨维度、随机传送、请求超时、分页大小和冷却时间
• 玩家规则与名称缓存持久化保存

交互设计

玩家视角

• 输入 /pt 即可查看在线玩家列表
• 可传送的目标会显示绿色点击按钮
• 不可传送的目标会直接显示原因
• 页眉中带有 随机 和 规则 快捷按钮
• 翻页使用 上一页 和 下一页 按钮
• 如需直接控制“谁能传送到我”，可直接使用 /pt allow <玩家> 或 /pt deny <玩家>
• 如果服务器开启了传送确认，发起传送后会先向目标玩家发送请求
• 目标玩家可点击聊天中的 同意 / 拒绝，或使用 /pt accept <玩家>、/pt reject <玩家> 处理请求

管理员视角

• 使用 /ptadmin 查看当前全局配置摘要
• 使用 /ptadmin set ... 修改全局配置
• 使用 /ptadmin player <玩家> reset 重置单个玩家的传送规则
• 可配置“同队可无视个人规则传送”或“仅同队可传送”
• 可配置传送是否必须经过目标玩家确认

权限规则

一次传送是否允许，由以下条件共同决定：

1. 全局功能是否开启
2. 是否允许跨维度传送
3. 是否被限制为仅同队玩家可传送
4. 发起者是否处于冷却中
5. 发起者的发送规则是否允许目标玩家
6. 目标玩家的接收规则是否允许发起者
7. 如果开启确认模式，目标玩家是否在超时时间内同意请求

规则模式

| 模式 | 含义 |
| — | — |
| all | 全部允许 |
| none | 全部拒绝 |
| whitelist | 仅名单内允许 |
| blacklist | 名单内拒绝，其余允许 |

规则方向

| 方向 | 含义 |
| — | — |
| outgoing | 我能传送到谁 |
| incoming | 谁能传送到我 |

队伍规则

管理员可通过全局配置控制基于原版记分板队伍的传送行为：

• allowSameTeamBypassRules = true：同队玩家可跳过双方个人规则检查
• sameTeamOnly = true：仅允许同队玩家之间传送

兼容性

| 项目 | 要求 |
| — | — |
| Minecraft | 1.21 到 1.21.11 |
| Fabric Loader | 0.16.0+ |
| Java | 21+ |
| Fabric API | 必需 |
| Fabric Language Kotlin | 必需 |

当前工程以 Minecraft 1.21.11 为主目标版本。

依赖

请确保以下依赖与本模组一起安装到对应环境的 mods 目录：

| 依赖 | 是否必需 | 说明 |
| — | — | — |
| Fabric API | 必需 | 提供 Fabric 命令与运行时 API |
| Fabric Language Kotlin | 必需 | 本模组使用 Kotlin 编写，缺失时无法加载 |

安装方式

服务端优先

本模组优先按服务端模组使用：

• 专用服务器：通常只需服务端安装本模组和依赖，客户端不需要安装
• 单人游戏：仍需本地安装，因为单人模式本质上运行的是内置服务器

玩家命令

| 命令 | 说明 |
| — | — |
| /pt | 查看在线玩家列表第一页 |
| /pt page <页码> | 查看指定页 |
| /pt search <关键字> | 搜索在线玩家 |
| /pt search <关键字> <页码> | 搜索结果分页 |
| /pt tp <玩家> | 直接传送到指定玩家身边，或在确认模式下发送请求 |
| /pt random | 随机传送到一个当前可用玩家 |
| /pt rules | 查看自己的当前规则 |
| /pt allow <玩家> | 直接允许指定玩家传送到你身边，并切换为接收白名单模式 |
| /pt deny <玩家> | 直接禁止指定玩家传送到你身边，并切换为接收黑名单模式 |
| /pt accept <玩家> | 同意指定玩家的传送请求 |
| /pt reject <玩家> | 拒绝指定玩家的传送请求 |
| /pt mode outgoing <模式> | 设置发送规则模式 |
| /pt mode incoming <模式> | 设置接收规则模式 |
| /pt add outgoing <玩家> | 将玩家加入发送名单 |
| /pt add incoming <玩家> | 将玩家加入接收名单 |
| /pt remove outgoing <玩家> | 将玩家移出发送名单 |
| /pt remove incoming <玩家> | 将玩家移出接收名单 |

管理员命令

| 命令 | 说明 |
| — | — |
| /ptadmin | 查看当前全局配置摘要 |
| /ptadmin reload | 重载配置文件 |
| /ptadmin set enabled <true|false> | 开启或关闭玩家传送功能 |
| /ptadmin set allowCrossDimension <true|false> | 开启或关闭跨维度传送 |
| /ptadmin set allowRandom <true|false> | 开启或关闭随机传送 |
| /ptadmin set requireTargetApproval <true|false> | 配置传送是否必须由目标玩家确认 |
| /ptadmin set requestTimeoutSeconds <5-120> | 配置传送请求过期时间 |
| /ptadmin set allowSameTeamBypassRules <true|false> | 配置同队玩家是否跳过个人规则 |
| /ptadmin set sameTeamOnly <true|false> | 配置是否仅允许同队玩家互相传送 |
| /ptadmin set pageSize <4-20> | 设置每页显示数量 |
| /ptadmin set cooldownSeconds <0-300> | 设置传送冷却时间 |
| /ptadmin set defaultOutgoing <模式> | 设置新玩家默认发送模式 |
| /ptadmin set defaultIncoming <模式> | 设置新玩家默认接收模式 |
| /ptadmin player <玩家> reset | 重置指定玩家的规则 |

配置说明

配置文件路径：

config/player-teleport.json

默认关键配置：

{
  "enabled": true,
  "allowCrossDimension": true,
  "allowRandom": true,
  "requireTargetApproval": false,
  "requestTimeoutSeconds": 20,
  "allowSameTeamBypassRules": false,
  "sameTeamOnly": false,
  "pageSize": 8,
  "cooldownSeconds": 3,
  "defaultOutgoingMode": "ALL",
  "defaultIncomingMode": "ALL"
}

说明：

• playerNames 用于缓存玩家显示名，方便在名单中展示
• players 使用 UUID 作为键保存每个玩家的发送与接收规则
• 直接命令 allow 和 deny 实际作用于接收规则
• requireTargetApproval = true 时，普通传送会先进入请求确认流程