InviteRewards
追踪谁邀请了谁,并在被邀请成员完成验证(而非仅仅加入)后发放游戏内奖励。
Discord 机器人已内置于插件中。无需托管第二个进程,也无需设置外部数据库。只需将 JAR 文件放入 plugins/ 目录,在 config.yml 中配置机器人令牌,然后重启即可。
工作原理
- 成员通过他人的邀请链接加入 Discord。插件通过比对邀请使用计数来确定是谁的邀请。
- 成员在验证频道点击按钮并获得验证角色。
- 此时才会为邀请人记账。仅加入而不验证不会获得任何奖励。
- 邀请人使用
/link 绑定其 Minecraft 账号,当确认的邀请数量达到配置的阈值时,奖励将被发放。
功能特性
- 在被邀请成员验证之前,加入行为不计入任何奖励,因此防止了“路过式”加入和机器人攻击获利。
- 一个 Discord 账号只能产生一次有效积分。这是由数据库主键强制执行的,而非易受竞态条件影响的检查逻辑。离开、重新被邀请并再次加入等操作都会合并到同一条记录中。
- 年龄小于可配置天数的 Discord 账号无法为其邀请人提供积分。
- 每个邀请人每日有最大积分上限,以防止批量邀请爆发。
- 如果被邀请成员在保留窗口期内离开,或在任何时候被封禁,则撤销该积分,并移除高于新计数的所有奖励。
- 没有人可以邀请自己,且一个 Minecraft 账号只能绑定一个 Discord 账号。
- 每个阈值仅发放一次奖励。中途重启不会导致重复发放等级或物品。
- 玩家在离线期间跨越的阈值会被排队,并在其下次上线时交付。
- 重启后,插件会尝试通过匹配邀请使用增量与停机期间加入的成员来补全遗漏的归属关系。无歧义的情况会自动解决;其余情况将记录日志供
/invitereward attribute 命令处理。
命令与权限
| 命令 |
描述 |
权限 |
默认值 |
/link <code> |
兑换在 Discord 中通过 /link 生成的代码 |
无 |
所有人 |
/invitereward reload |
从 config.yml 重新读取奖励和消息配置 |
inviterewards.admin |
op |
/invitereward status <player> |
显示玩家的 Discord 绑定状态、已确认邀请数及各阈值进度 |
inviterewards.admin |
op |
/invitereward unlink <player> |
移除玩家的 Discord 绑定 |
inviterewards.admin |
op |
/invitereward attribute <discordId> <inviterId> |
为追踪器无法自动归属的成员手动设置邀请人 |
inviterewards.admin |
op |
在 Discord 中,机器人注册了一个斜杠命令 /link,用于生成一个六位数的代码,玩家需在游戏中的聊天框输入该代码。
/invitereward reload 仅重新加载奖励和消息配置。更改令牌、服务器、频道或角色需要重启服务器。
要求
Paper 或其分支版本。Spigot 未经测试。
Minecraft 1.21 至 26.2。插件基于 1.21 API 编译,并已验证可在 26.1.2 和 26.2 下编译。
Java 21 或更高版本,即你的 Minecraft 版本所要求的 Java 版本(1.21.x 需要 Java 21,26.x 需要 Java 25)。
你需要自行创建一个 Discord 机器人应用程序。详见下方“设置”部分。
LuckPerms 是可选的,仅在需要使用 luckperms-group 类型奖励时才必需。如果没有 LuckPerms,群组奖励会记录警告并被跳过。Vault 加上经济插件也是类似的可选项,用于 money 类型奖励。命令和物品奖励则没有任何依赖项。
设置
Discord 侧的设置往往是出错的地方,请按顺序执行以下步骤:
- 在 创建应用程序,并为其添加一个 Bot。复制机器人令牌。
- 在 Bot 标签页中,启用 Server Members Intent(服务器成员意图)。它是特权功能,默认关闭。没有它,邀请追踪将无法工作。
- 使用拥有 Manage Server(管理服务器)权限(使其能够读取邀请)和 Manage Roles(管理角色)权限将该机器人邀请到你的服务器。
- 在服务器的角色列表中,将机器人的自身角色拖放到已验证角色的上方。Discord 不允许机器人分配位置高于其自身角色的角色。
- 在 Discord 中启用开发者模式(设置 → 高级),然后右键点击以复制你的服务器 ID、验证频道 ID 和已验证角色 ID。
- 将 JAR 文件放入
plugins/ 目录,启动服务器一次以生成 config.yml,填入令牌和三个 ID,然后重启服务器。
启动时,插件会发布带有按钮的验证消息,并对现有的邀请情况进行基线快照。已经存在的邀请链接将继续正常工作。在安装插件 之前 发生的加入行为没有基线数据,也不会进行回溯归属。
配置
以下是生成的 config.yml:
discord:
token: ''
guild-id: ''
# 发布带按钮的验证消息的频道。
verify-channel-id: ''
# 成员验证后获得的角色。
verified-role-id: ''
verify-message:
title: 'Verification'
body: 'Press the button below to verify and gain access to the server.'
button: 'Verify'
anti-abuse:
# 年龄小于此天数的 Discord 账号无法为其邀请人提供积分。这是防止一次性小号最有效的方法。
min-account-age-days: 7
# 如果被邀请成员在此天数内 LEAVE(离开),积分将被撤销。
# BAN(封禁)始终会撤销积分,无论账号年龄如何。
hold-window-days: 7
# 每个邀请人每天可获得的最大积分。0 表示禁用上限。
daily-credit-cap: 10
linking:
# /link 代码的有效时长。
code-expiry-minutes: 10
启动:
重启后,尝试通过将邀请使用量的变化与在此窗口期间加入的成员进行匹配,来归因服务器停机时发生的加入行为。仅解决明确的情况;其余情况会记录日志。
recover-missed-joins: true
恢复过程需要加载成员列表。超过此成员数量时将跳过。
recovery-max-guild-size: 10000
阈值是已确认邀请的数量(已验证且未被撤销的)。
每个键都是可选的——仅使用你需要的奖励类型。
commands : 从控制台运行,%player% 会被替换
luckperms-group : 需要 LuckPerms;如果计数下降则移除
money : 需要 Vault;如果计数下降则扣除
items : 如果玩家离线,则在下次加入时给予;永远不会收回
rewards:
5:
commands:
- 'broadcast &a%player% &7has invited 5 members!'
luckperms-group: 'vip'
money: 1000.0
10:
money: 5000.0
items:
- material: DIAMOND
amount: 8
- material: NETHERITE_INGOT
amount: 1
name: 'gradient:#f0a:#0afInvite Reward</gradient>'
lore:
- '<gray>Thank you for growing the server.</gray>'
MiniMessage 格式说明。
messages:
prefix: '<gray>[</gray><aqua>Invites</aqua><gray>]</gray> '
link-usage: '<yellow>Usage: /link - run /link in Discord to get a code.</yellow>'
link-unknown-code: '<red>That code is invalid or has expired.</red>'
link-already-linked: '<red>This Minecraft account is already linked to a Discord account.</red>'
link-discord-taken: '<red>That Discord account is already linked to another Minecraft account.</red>'
link-success: '<green>Linked to Discord as <white><user></white>.</green>'
reward-granted: '<green>Reward unlocked for <white><threshold></white> invites!</green>'
reward-revoked: '<red>An invite was revoked, so your <white><threshold></white>-invite reward was removed.</red>'
items-pending: '<yellow>You had reward items waiting - they are in your inventory now.</yellow>'
inventory-full: '<red>Your inventory was full, so some reward items were dropped at your feet.</red>'
奖励阈值是任意数字。你可以添加任意多个。每个阈值仅支付一次。
### 当信用被撤销时会发生什么
如果撤销导致某人低于他们已经达到的阈值,奖励将尽可能合理地回滚。LuckPerms 组将被移除,Vault 金钱将被扣除。物品不会被收回,因为它们可能已经被花费或交易出去,而追踪它们既不可靠也不友好。
如果计数后来再次超过该阈值,组和金钱将返回,但物品和控制台命令不会再次触发。否则,“邀请、收集、被封禁、重复”会导致物品打印出来。
## 安装前须知
**机器人仅在您的 Minecraft 服务器运行时运行。** 这是将其作为单个 JAR 分发且无需托管的权衡。
Discord 不会回填邀请归因。它是通过比较某人加入时的邀请使用量来实时解决的。正常重启需要一两分钟,启动时的恢复过程可以解决大多数遗漏的情况。
**空服时休眠的服务器(例如 Aternos)不太适合。** 服务器处于离线状态时,机器人也会离线,这通常是大部分时间,因此大多数加入行为将无法归因。如果您的主机符合这种情况,此插件对您来说效果不佳。
## 故障排除
**控制台中出现“机器人缺少管理服务器权限”。** 邀请跟踪已关闭。请使用 Manage Server 权限重新邀请机器人,或通过角色授予该权限。
**成员验证了但没有人获得信用。** 在启动时检查控制台的基线消息。如果未启用“服务器成员意图”,机器人永远不会收到加入事件。还要检查邀请者是否仍在公会中,因为拒绝向已离开的人提供信用。
**“我们无法告诉谁邀请了您。”** 加入行为存在歧义:可能是 vanity URL、小部件邀请、同时进行的两个加入,或在停机期间加入。使用 `/invitereward attribute <discordId> <inviterId>` 修复它;信用仍要求成员经过验证。
**验证按钮无效或角色分配失败。** 机器人的角色必须位于公会角色列表中已验证角色的上方。
**游戏中未收到奖励。** 玩家必须通过 `/link` 链接。通过 `/invitereward status <player>` 确认,该命令显示链接的 Discord ID、已确认的邀请数量以及每个阈值的状态。
InviteRewards
Track who invited whom on your Discord, and pay out in-game rewards once the
invited member verifies rather than merely joins.
The Discord bot is built into the plugin. There is no second process to host and
no external database to set up. One JAR in plugins/, a bot token in
config.yml, then restart.
How it works
- A member joins your Discord through someone's invite. The plugin diffs invite
use counts to work out whose invite it was.
- The member presses a button in your verify channel and gets the verified role.
- Only then is the inviter credited. Joining alone earns nothing.
- The inviter links their Minecraft account with
/link, and rewards are handed
out as their confirmed invite count crosses each configured threshold.
|
|
|
|
| Invite tracking |
Verification |
Threshold rewards |
Anti-abuse |
Features
- A join counts for nothing until the invited member verifies, so drive-by joins
and bot raids do not pay.
- One Discord account can produce one credit, ever. A database primary key
enforces that, not a check that can be raced. Leaving, being re-invited and
rejoining all collapse onto the same record.
- Discord accounts younger than a configurable age cannot credit whoever invited
them.
- A daily cap per inviter blunts mass-invite bursts.
- If the invited member leaves within the hold window, or is banned at any point,
the credit is taken back and rewards above the new count are removed.
- Nobody can invite themselves, and one Minecraft account links to exactly one
Discord account.
- Each threshold pays out once. A restart part-way through delivery cannot
duplicate a rank or an item.
- Thresholds crossed while a player is offline are queued and delivered on their
next join.
- After a restart the plugin tries to attribute joins it missed, by matching the
invite-use delta against members who joined during the downtime. Unambiguous
cases resolve automatically; the rest are logged for
/invitereward attribute.
Commands and permissions
| Command |
Description |
Permission |
Default |
/link <code> |
Redeem the code issued by /link in Discord |
none |
everyone |
/invitereward reload |
Re-read rewards and messages from config.yml |
inviterewards.admin |
op |
/invitereward status <player> |
Show a player's Discord link, confirmed invites and per-threshold state |
inviterewards.admin |
op |
/invitereward unlink <player> |
Remove a player's Discord link |
inviterewards.admin |
op |
/invitereward attribute <discordId> <inviterId> |
Set the inviter for a member the tracker could not attribute |
inviterewards.admin |
op |
In Discord the bot registers one slash command, /link, which issues a
six-character code to type in game.
/invitereward reload reloads rewards and messages only. Changing the token,
guild, channel or role needs a server restart.
Requirements
Paper, or a fork of it. Spigot is not tested.
Minecraft 1.21 through 26.2. The plugin is compiled against the 1.21 API, and
also verified to compile against 26.1.2 and 26.2.
Java 21 or newer, which is whatever your Minecraft version already requires
(Java 21 on 1.21.x, Java 25 on 26.x).
A Discord bot application that you create yourself. See Setup below.
LuckPerms is optional and only needed for luckperms-group rewards. Without it,
group rewards log a warning and are skipped. Vault plus an economy plugin is
optional in the same way, for money rewards. Command and item rewards have no
dependencies at all.
Setup
The Discord side is where installs go wrong, so do these in order.
- Create an application at and add
a Bot to it. Copy the bot token.
- In the Bot tab, enable the Server Members Intent. It is privileged and off by
default. Invite tracking does not work without it.
- Invite the bot to your guild with the Manage Server permission, which is what
lets it read invites, and with Manage Roles.
- In your guild's role list, drag the bot's own role above the verified role.
Discord will not let a bot assign a role positioned above its own.
- Enable Developer Mode in Discord (Settings → Advanced), then right-click to
copy the IDs of your guild, your verify channel and your verified role.
- Drop the JAR into
plugins/, start the server once to generate config.yml,
fill in the token and the three IDs, and restart.
On startup the plugin posts the verification message with its button, and takes a
baseline snapshot of your existing invites. Invites that already exist keep
working. Joins that happened before you installed the plugin have no baseline
and are not attributed retroactively.
Configuration
This is the generated config.yml:
discord:
token: ''
guild-id: ''
# Channel where the verification message with the button is posted.
verify-channel-id: ''
# Role granted once a member verifies.
verified-role-id: ''
verify-message:
title: 'Verification'
body: 'Press the button below to verify and gain access to the server.'
button: 'Verify'
anti-abuse:
# A Discord account younger than this cannot produce a credit for whoever
# invited it. The single most effective filter against throwaway alts.
min-account-age-days: 7
# If an invited member LEAVES within this many days, the credit is revoked.
# A BAN always revokes, regardless of age.
hold-window-days: 7
# Maximum credits one inviter can earn per day. 0 disables the cap.
daily-credit-cap: 10
linking:
# How long a /link code stays valid.
code-expiry-minutes: 10
startup:
# After a restart, try to attribute joins that happened while the server was
# down, by matching the invite-use delta against members who joined in that
# window. Only resolves unambiguous cases; the rest are logged.
recover-missed-joins: true
# Recovery has to load the member list. Skipped above this member count.
recovery-max-guild-size: 10000
# Thresholds are counts of CONFIRMED invites (verified, not revoked).
# Every key is optional - use only the reward types you need.
# commands : run from console, %player% is replaced
# luckperms-group : requires LuckPerms; removed again if the count drops
# money : requires Vault; withdrawn again if the count drops
# items : given on next join if the player is offline; NEVER reclaimed
rewards:
5:
commands:
- 'broadcast &a%player% &7has invited 5 members!'
luckperms-group: 'vip'
money: 1000.0
10:
money: 5000.0
items:
- material: DIAMOND
amount: 8
- material: NETHERITE_INGOT
amount: 1
name: '<gradient:#f0a:#0af>Invite Reward</gradient>'
lore:
- '<gray>Thank you for growing the server.</gray>'
# MiniMessage formatting. https://docs.advntr.dev/minimessage/format.html
messages:
prefix: '<gray>[</gray><aqua>Invites</aqua><gray>]</gray> '
link-usage: '<yellow>Usage: /link <code> - run /link in Discord to get a code.</yellow>'
link-unknown-code: '<red>That code is invalid or has expired.</red>'
link-already-linked: '<red>This Minecraft account is already linked to a Discord account.</red>'
link-discord-taken: '<red>That Discord account is already linked to another Minecraft account.</red>'
link-success: '<green>Linked to Discord as <white><user></white>.</green>'
reward-granted: '<green>Reward unlocked for <white><threshold></white> invites!</green>'
reward-revoked: '<red>An invite was revoked, so your <white><threshold></white>-invite reward was removed.</red>'
items-pending: '<yellow>You had reward items waiting - they are in your inventory now.</yellow>'
inventory-full: '<red>Your inventory was full, so some reward items were dropped at your feet.</red>'
Reward thresholds are arbitrary numbers. Add as many as you like. Each one is
paid exactly once.
What happens when a credit is revoked
If a revocation drops someone below a threshold they had already reached, the
reward is rolled back as far as it sensibly can be. The LuckPerms group is
removed and the Vault money is withdrawn. Items are not taken back, because they
may already have been spent or traded away, and hunting them down would be both
unreliable and hostile.
If the count later climbs back over that threshold, the group and the money
return, but the items and the console commands do not fire again. Otherwise
"invite, collect, get them banned, repeat" would print items.
Before you install
The bot only runs while your Minecraft server runs. That is the tradeoff for
shipping it as one JAR with nothing to host.
Discord does not backfill invite attribution. It is worked out live, by comparing
invite use counts at the moment somebody joins. A normal restart is a minute or
two, and the recovery pass on startup resolves most of what it misses.
Servers that sleep when empty, such as Aternos, are a poor fit. The bot is
offline whenever the server is, which is most of the time, so most joins will
never be attributed. If that describes your host, this plugin will not work well
for you.
Troubleshooting
"The bot lacks the Manage Server permission" in the console. Invite tracking
is off. Re-invite the bot with Manage Server, or grant it via a role.
Members verify but nobody gets credited. Check the console at startup for the
baseline message. If the Server Members Intent is disabled the bot never receives
join events. Also check that the inviter is still in the guild, because credits
to someone who has left are refused.
"We could not tell who invited you." The join was ambiguous: the vanity URL,
a widget invite, two simultaneous joins, or a join during downtime. Fix it with
/invitereward attribute <discordId> <inviterId>; the credit still requires the
member to be verified.
The verify button does nothing, or role assignment fails. The bot's role must
sit above the verified role in your guild's role list.
Rewards not arriving in game. The player must have linked with /link.
Confirm with /invitereward status <player>, which shows the linked Discord ID,
the confirmed invite count, and the state of every threshold.
评论 0
登录后参与评分
还没有评论,来抢沙发吧