YuTeleport 配置说明

主配置文件位于：

plugins/YuTeleport/config.yml

语言文件位于：

plugins/YuTeleport/lang/zh_CN.yml
plugins/YuTeleport/lang/en_US.yml

配置结构

区块	用途
config-update-mode	配置升级时使用模板重建，或保留现有排版只补齐缺失键。
language	默认语言与是否跟随玩家客户端语言。
integrations.placeholderapi	是否注册 PlaceholderAPI 扩展。
update-check	是否异步检查 YuTeleportIssueReport 的 GitHub Release。
economy	是否启用经济，以及使用 Vault 还是 PlayerPoints。
cooldowns	是否把未过期冷却保存到 cooldowns.yml。
teleports.defaults	所有模块共享的等待、倒计时、打断和世界访问规则。
teleports.rtp	随机传送模块、范围、安全点、生物群系、预缓存和自动传送。
teleports.warp	warp 模块、命令名、数量上限、公开 warp、费用和钩子。
teleports.home	home 模块、命令名、数量上限、公开 home、世界限制和钩子。
teleports.tpa	tpa 模块、命令名、请求过期、费用、冷却和钩子。
teleports.share	坐标分享、分享冷却、有效期、费用和最大保留数量。
teleports.back	/back 历史返回、命令名、捕获来源、历史上限、过期、持久化、费用和钩子。
effects	音效、标题、粒子、BossBar 平滑和交互式聊天。
groups	按 yuteleport.group.<组名> 覆盖冷却、费用和数量上限。
debug	是否输出安全点查找、拒绝原因和原生方块状态。
config-version	当前模板版本，最新版为 20。

官方链接同步

默认配置顶部内置最新官方入口：

# 官方文档 Wiki: https://vicuna-main.github.io/YuPluginHub/plugins/items/yu-teleport/
# Modrinth 下载: https://modrinth.com/plugin/yuteleport
# Bug / Issue 反馈: https://github.com/vicuna-main/YuTeleportIssueReport
# 官方 QQ 交流群: https://qm.qq.com/q/xiwJYBYdh0
# 赞助作者 / 爱发电: https://afdian.com/a/vicuna

经济配置

economy:
  enabled: false
  provider: vault

provider 可写：

值	说明
vault	通过 Vault 对接金币经济，例如 EssentialsX、CMI、XConomy。
playerpoints	直接对接 PlayerPoints 点券；小数费用会向上取整。

费用在各模块中分别配置，例如 teleports.rtp.worlds.default.cost、teleports.warp.cost、teleports.home.cost、teleports.tpa.cost、teleports.share.cost、teleports.back.cost。

世界访问控制

teleports:
  defaults:
    world-access:
      blacklist:
        - 'lobby'
        - 'playerworld*'
      whitelist: []

黑白名单支持 * 通配符且不区分大小写。whitelist 非空时只允许匹配的世界，blacklist 会被忽略。warp、home、tpa、share、back 可单独覆写 world-access。

随机传送范围

teleports:
  rtp:
    worlds:
      default:
        shape: square
        center:
          x: 0
          z: 0
        radius:
          min: 500
          max: 10000

shape 可写 square 或 circle。世界独立覆盖写在 teleports.rtp.worlds.overrides.<世界名> 下，未填写的字段继承 default。

安全检查与生物群系

safety:
  check: true
  allow-void: false
  allow-water: false
  allow-lava: false
  max-attempts: 32
  min-air-above: 8
  blocked-materials:
    - "MAGMA*"
    - "CACTUS"
  allowed-materials: []
  blocked-biomes: []
  allowed-biomes: []

材质、生物群系和世界名都支持 * 通配符。allowed-materials 或 allowed-biomes 非空时，以白名单为准。

等待、倒计时和打断

teleports:
  defaults:
    warmup-seconds: 5
    countdown-display: actionbar
    cancel-on-move: true
    cancel-triggers:
      move: true
      damage: true
      interact: true
      chat: true
      command: true

模块自己的 warmup-seconds 写 -1 表示继承默认值，写 0 表示立即传送。countdown-display 支持 chat、bossbar、actionbar、none，也可用逗号或 YAML 列表组合。

模块与命令

teleports:
  warp:
    enabled: true
    commands:
      warp: [warp, warps]
      setwarp: [setwarp]
      delwarp: [delwarp]

第一个名称是主命令，其余是别名。写成 [] 可禁用对应逻辑命令。home、tpa 与 back 使用同样结构。

Back 历史返回

teleports:
  back:
    enabled: true
    commands:
      back: [back]
    warmup-seconds: 5
    cooldown-seconds: 10
    cost: 0.0
    safety-rescue: true
    max-history: 5
    expire-seconds: 1800
    persist: true
    capture:
      plugin-teleports: true
      death: true
      external-teleports: true
      include-types: [random, warp, home, tpa, share, back]
      min-distance: 3.0
    priority: [death, teleport, external]

/back 默认记录三类来源：插件传送成功前的位置、死亡位置、以及非 YuTeleport 触发的外部传送前位置。include-types 控制哪些 YuTeleport 传送类型会被记录；min-distance 用来过滤原地或极短距离移动。priority 决定无参数 /back 选择历史时的优先级，取值为 death、teleport、external。

persist: true 时，历史写入 plugins/YuTeleport/data/back/<玩家UUID>.yml。max-history 会被限制在 1-50，expire-seconds 可设为 0 表示不过期，最大支持 30 天。

命令钩子

每个模块都有 hooks，由控制台执行，不要写 /：

hooks:
  on-request: []
  on-warmup-start: []
  on-countdown: []
  on-cancel: []
  on-success: []
  on-fail: []

常用占位符包括 {player}、{sender}、{mover}、{payer}、{type}、{world}、{cost}、{seconds}、{total}、{reason}、{x}、{y}、{z}。Back 钩子还会提供 {source} 与 {caused_by}。

权限组覆盖

groups:
  vip:
    rtp:
      cooldown-seconds: 10
      cost: 5.0
    warp:
      max-warps: 40
    home:
      max-homes: 20

玩家拥有 yuteleport.group.vip 时套用该组。多个组同时匹配时，以配置中靠前的组为准。