Snowy 插件文档
Snow Welcome

安装与配置

Snow-Welcome 的安装、config.yml 全部字段、欢迎奖励配置与已知限制。

Snow-Welcome

新玩家第一次进服时全服广播一条带点击按钮的欢迎消息，其他玩家点击（或输入 /welcome <玩家名>）来欢迎他，欢迎者获得奖励。

本手册基于插件当前源码整理，配置字段均以代码实际读取的为准。当前版本 1.0.0。

环境要求

项目要求
服务端Paper 及其衍生（Leaves、Purpur 等）
版本1.21+（api-version: 1.13，实际用到 Adventure API）
硬依赖Vault（写在 depend 里，不装插件不会启动）
奖励依赖按你配的奖励命令而定，如 Essentials（money）、PlayerPoints（points）
Vault 是硬依赖：plugin.yml 里写了 depend: [Vault]，服务器上没有 Vault 插件时 Snow-Welcome 根本不会加载。但插件代码本身没有调用 Vault API——发钱是靠 Bukkit.dispatchCommand 执行你配置的命令。也就是说 Vault 只是个必须存在的门槛，实际发钱依赖的是你配的那条命令对应的插件。

安装

  1. 把 jar 放进 plugins/
  2. 启动服务器，插件会释放 plugins/Welcome/config.yml
  3. 控制台出现 Welcome enabled! Author: SnowyMC 即成功

插件目录下会生成两个文件：

plugins/Welcome/
├── config.yml    # 全部配置
└── data.yml      # 新玩家记录与「谁欢迎过谁」

工作流程

新玩家首次加入

插件检查 data.yml 里有没有这个 UUID。没有就登记（记下名字与加入时间戳），然后按 welcome-message 全服广播。

其他玩家点击「点我欢迎新玩家」

按钮实际执行的是 /welcome <新玩家名>，等同于手动输入。

校验四件事

依次检查：目标玩家在线、不是欢迎自己、目标在 data.yml 里登记过、距离登记时间没超过 welcome-limit-seconds、自己没欢迎过这个人。

发奖 + 代替欢迎者发言

任一校验失败就发对应提示并中止。全部通过则先发奖励，再从 sender-messages 随机抽一条以欢迎者身份发到聊天。

config.yml 全部字段

welcome-message: |
  <white>————————————————
  <white>⻬:offset_-1:⻭
  <white>
  <green>欢迎新玩家 <player> 加入服务器！</green>
  <red><click:run_command:/welcome <player>>     [点我欢迎新玩家]</click></red>
  <white>————————————————

sender-messages:
  - "厥新人！厥新人！厥新人！！"
  # - "<player> 来啦，欢迎欢迎！"
  # - "新人 <player>，多多关照！"

welcome-limit-seconds: 90
welcome-limit-seconds-message: "§c时间过了！"
welcomed: "§c你已经欢迎过该玩家了！"
not-new: "§c不是新玩家或过期了"

rewards:
  money:
    enable: true
    min: 100
    max: 800
    command: "money give %player% %amount%"

  playerpoints:
    enable: true
    min: 1
    max: 2
    command: "points give %player% %amount%"

  command:
    enable: true
    commands:
      - "titlemsg %sender% -in:10 -out:10 -keep:20 \n⻪:offset_-1:⻫"
字段类型说明
welcome-message文本（多行）新人加入时的全服广播，MiniMessage 格式
sender-messages列表欢迎成功后，随机抽一条以欢迎者身份发到聊天
welcome-limit-seconds整数新人加入后多少秒内可以被欢迎，默认 90
welcome-limit-seconds-message文本超时提示，§ 颜色码
welcomed文本重复欢迎同一人的提示
not-new文本目标不在新人记录里的提示
rewards.money.*—见下文
rewards.playerpoints.*—见下文
rewards.command.*—见下文
welcome-message 走 MiniMessage（<green>、<click:run_command:...> 这类标签）；而四条提示消息（welcomed、not-new 等）是直接原样发送的，只能用 § 传统颜色码。两套语法不通用，别弄混。

欢迎消息里的可点击按钮

默认配置里那行是关键：

<red><click:run_command:/welcome <player>>     [点我欢迎新玩家]</click></red>

<player> 会被替换成新玩家的名字，所以点击就等于执行 /welcome 那个新人。想改按钮文字只改 [点我欢迎新玩家] 部分，<click:run_command:...> 结构别动。

想加悬浮提示：

<red><hover:show_text:'<gray>点一下就有奖励哦'><click:run_command:/welcome <player>>     [点我欢迎新玩家]</click></hover></red>

奖励配置

三类奖励互相独立，可以只开其中一部分，也可以全开（会一起发）。

金币与点券：随机数额

rewards:
  money:
    enable: true
    min: 100          # 最小值
    max: 800          # 最大值（含）
    command: "money give %player% %amount%"

插件在 min ~ max 之间抽一个整数，替换进命令后以控制台身份执行。

占位符替换为
%player%欢迎者的名字（不是新玩家）
%amount%本次随机出的数额
max 小于 min 时不会报错，而是直接取 min。两个都填 0 就是固定发 0，等于白跑一条命令——不想发就把 enable 设成 false。

money 与 playerpoints 这两个键名只是分类标签，实际发什么完全由 command 决定。你可以把 playerpoints 那条改成任何命令，比如发经验：

  playerpoints:
    enable: true
    min: 50
    max: 200
    command: "experience add %player% %amount%"

自定义命令：固定内容

rewards:
  command:
    enable: true
    commands:
      - "titlemsg %sender% -in:10 -out:10 -keep:20 \n⻪:offset_-1:⻫"
      - "give %sender% diamond 1"
      - "broadcast &e%sender% &f欢迎了新人 &b%newplayer%"

这一组按顺序全部执行，没有随机数额，占位符也不同：

占位符替换为
%sender%欢迎者的名字
%newplayer%被欢迎的新玩家名字
注意 %player% 在这一组里不生效——它只用于 money 和 playerpoints。自定义命令组用的是 %sender%。这是最容易配错的地方：写了 %player% 不会报错，命令会带着字面的 %player% 执行然后失败。

全部命令都以控制台身份执行，所以不受玩家权限限制。

命令与权限

命令用法权限
/welcome <玩家名>欢迎一个新玩家无权限节点

插件没有定义任何权限节点，/welcome 所有人都能用。这符合设计——它本来就是给全服玩家点的按钮。

没有 reload 命令。改完 config.yml 需要重启服务器，或用第三方插件（如 PlugManX）重载 Welcome。

data.yml 数据结构

new-players:
  069a79f4-44e9-4726-a5be-fca90e38aaf5:
    name: Notch
    join-time: 1754000000000
    welcomed-by:
      - 853c80ef-3c37-49fd-aa49-938b674adae6
字段含义
顶层键新玩家的 UUID
name当时的玩家名（仅供人看，逻辑不用它）
join-time首次加入的毫秒时间戳，超时判定基于它
welcomed-by欢迎过他的玩家 UUID 列表，用于防重复

数据在插件关闭时保存，每次登记与欢迎也会立即写盘。

这个文件只增不减。 插件没有清理逻辑，每个进过服的新玩家都会永久留一条记录。长期运营的服务器 data.yml 会持续变大。它只用于「是否新人」与「超时判定」，超过 welcome-limit-seconds 的记录实际已无用——需要瘦身可以在停服时手动删掉旧条目。「是否新玩家」判据是 data.yml，不是服务器的 hasPlayedBefore。 所以删掉 data.yml 后，所有老玩家下次进服都会被当成新人广播一遍。迁移服务器或清理数据时注意这一点。

已知限制

现象说明
默认 data.yml 里有 players: []插件释放的模板残留，代码从不读它。可以忽略，也可以删掉
没有 /welcome reload改配置要重启，或用 PlugManX 之类重载
没有权限节点/welcome 对所有人开放
奖励发给欢迎者新玩家本人不会获得任何奖励，插件没有这个功能
Vault 装了但没被调用硬依赖，必须装；实际发钱靠你配的命令

排错

新人进服没有广播

  • 确认这个 UUID 不在 data.yml 的 new-players 下（他可能之前进过服）
  • 确认 welcome-message 不是空的——留空会直接跳过广播，不报错

点击按钮提示「不是新玩家或过期了」

目标 UUID 不在 data.yml 里。常见于服务器重启后 data.yml 未正确保存，或点的是老玩家。

点击按钮提示「时间过了」

超过 welcome-limit-seconds（默认 90 秒）。想放宽就调大这个值。

奖励没发出来

奖励是以控制台身份执行命令，所以要先确认：

  1. 那条命令在控制台手动敲能不能成功（比如 money give Notch 100）
  2. 对应插件是否安装（money 需要经济插件，points 需要 PlayerPoints）
  3. 占位符是否用对：money/playerpoints 用 %player%，command 组用 %sender%

欢迎者的发言没出现在聊天里

sender-messages 是通过让玩家「说话」实现的，会被聊天插件、静音、聊天频道等机制影响。若消息渲染后开头是 /，插件会自动加一个零宽字符防止被当成命令执行。

权限节点

SnowyGems 全部权限节点、user/admin 两个伞节点的用法，以及权限组配置示例。

更新日志

Snow-Welcome 各版本的变更记录。

Copyright © 2026