[XxFran10xX]

What

A referral system inside ActivityTF that reuses the plugin's reward pools, claim flow and menu style. This is still a draft. The reward values below are the ones agreed with fran for Act I.

• Linking: a new player opens /referral (or the head button at slot 22 of /activity), clicks Who invited you?, picks an online player or types a name (/referral invitedby <name>), and confirms. Each account gets one link, and the player can never change it. Staff can fix links with /referral link and /referral unlink.
• Invites are unlimited (link.max-invitees: 0). The rare track still ends at 10 players, so inviting more people after that adds nothing to it. max-links-per-day (3) still applies.
• Timed rewards: milestones are based on the new player's counted playtime. They are the same in every act and fully set in config (milestones: in referral.yml: any number of milestones, any hours, any reward per side). The new player claims each one once ever per season. The inviter claims each one once per invited player, from the same menu. The row shows seven at a time and scrolls past that.
• Rare track (inviter only): a separate list (rare-track:). Every invited player who reaches the last milestone (24h) moves the inviter one step along it. Each step is claimed once per season.
• Acts: what a milestone holds comes from the act in use. acts.<id> sets starts and its own pools, and the latest act that has started applies. A pool is looked up in the act's pools, then the shared pools, then the activity's week-locked rewards.pools.
• Season: for the first season.open-days (14) days after season.start, any account can link, and its playtime since the season start already counts. After that, only accounts in their first link.new-account-days (7) days can link. Changing season.start moves referrals.yml aside and starts a fresh season. If the store can't be saved first, the season doesn't change (it logs SEVERE), and the next reload tries again.

Rewards (Act I)

Milestone	New player	Inviter (per invited player)
1h	Steel Pickaxe, Hatchet, Shovel and Hoe + 64 Dry Rations	10 gold denars
4h	12 Ignitium + 10 gold denars	6 Ignitium
12h	20 Ignitium + 15 gold denars	10 Ignitium
24h	32 Ignitium + 2 raw tin + 2 abyssalite fragments + 25 gold denars	16 Ignitium
Total	4 steel tools, 64 rations, 64 Ignitium, 2 tin, 2 fragments, 50 denars	10 denars, 32 Ignitium

Rare track (invited players at 24h)	Reward	Running total
2	1 raw tin + 1 abyssalite fragment	1 + 1
4	1 + 1	2 + 2
6	2 + 2	4 + 4
8	2 + 2	6 + 6
10	2 + 2	8 + 8

There are no denars on the rare track. Its total, 8 tin and 8 fragments, is 40:1 against the 320 Ignitium ten invitees pay their inviter, as in rule 4 of the Act System. ACT-SYSTEM.md in the workspace logs referrals as a new one-off source of act materials, with these tables and their impact.

Cooking reward items

Reward items can now be Cooking items: c.<category>(type=<food>;...), such as c.dry_ration(type=dry_ration;quality=1) from the RPCharacters starting kit. They are handed over through TLibs like m. paths. Any reward item can also set name:, what the menu calls it (the shipped m.tools.steel_axe is named "Steel Hatchet", as in game). A malformed path is named at load time, and if Cooking isn't enabled, a warning says the path hands over nothing. They are only accepted as reward items, not as craft keys or icons.

Menu (/referral, 54 slots)

Slots	What
0	Inviter head (Invited by: X), Who invited you?, or why linking is closed
4	Progress clock: a bar with milestone markers, e.g. 14h / 24h
8	Rules book
10 / 12 / 14 / 16	Your 1h / 4h / 12h / 24h milestones, each showing its reward item. The lore lists exactly what is inside. Locked: grey name with the time left. Claimable: green and glowing. Claimed: ✔. On hold: locked, with a "on hold - ask staff" line
22	Players you invited (n)
27-44	One head per invited player, with their hours and [CLAIM 20h]. A click claims everything due for that player
9 / 17	Earlier / later milestones, only shown when there are more than seven
45 / 48 / 49 / 50	Back to Weekly Activity / previous page / rare-track star (glows when a step is ready, click to open) / next page

The rare-track menu has a header listing who counts and one item per step (locked / glowing claimable / ✔ claimed, with the step's contents and how many more players it needs).

Anti-abuse

I checked several public referral plugins (RallyRefer, MysticalReferral, InviteRewards, RedeemMaster, ReferMe) and some fraud-prevention write-ups. Most of them pay on a single playtime threshold plus a same-IP check. This PR goes further:

• AFK time doesn't count. A minute counts only if, within playtime.afk-minutes, the player moved at least move-blocks blocks, chatted, ran a real command, or broke or placed a block, and Paper's idle timer is under the limit too. Turning the camera, swinging or autoclicking alone earns nothing. Movement is sampled every second.
• Ignored worlds (character_selection): no counting and no claiming there.
• Connection history: each account keeps its last 16 connections this season, stored as salted hashes. Accounts that shared a connection can't link, and if they share one later, both sides' claims are held. /referral allowip <a> <b> allows one real household pair.
• No self links and no loops, at any depth.
• Rare track: an invitee counts only when they have really reached the last milestone, and not when they share a connection with the inviter. Once a step is claimed, the invitees it stood on are tied to that inviter for good (rare-counted-for). The goal is recorded when an invitee reaches it (rare-reached-goal), so raising the goal mid-season doesn't take credit away.
• Claims are keyed by milestone hours, so a milestone is never paid twice when the act changes. A claim is saved before paying and rolled back if the save or the payout fails. Every link, claim and staff action logs a REFERRAL-AUDIT line.
• Kill switch: enabled: false.

Commands and permissions

• /referral (alias /referrals) and /referral invitedby <name>: activity.referral (default true).
• Staff (activity.referral.admin, op, and a child of activity.admin). /referral help lists these:
  • info <player>: hours, inviter, claims on both sides, invitees and their claims, rare count and who counts, rare claims, ties and flags.
  • link <player> <inviter> / unlink <player>: staff links skip the season, daily and connection checks and replace an existing link, but still refuse self links and loops.
  • addtime <player> <minutes> / settime <player> <minutes>: lowering time below the goal a player reached removes their rare credit, unless a claimed step already ties them.
  • unclaim <player> <hours|all> [new|inviter|both] / markclaimed ...: reopen or close milestones.
  • rare unclaim|markclaimed <inviter> <players|all>: unclaim all also frees the invitee ties, and markclaimed ties the invitees it stands on.
  • rare exclude|include <player>: keep an invitee off every rare track.
  • hold <player> / release <player>: an account on hold can't claim anything, and its inviter can't claim for it.
  • allowip <player> <player>: toggle the household pair.
• Each staff command saves immediately. If the save fails, the change is undone and staff see "could not be saved".
• /activity reload also reloads referral.yml.

Deploy notes

• season.start ships empty, so set it before going live.
• Playtime only counts from the moment this jar runs.
• messages.yml: Main's plugins/activity/messages.yml (from 09-18) has no referral: section, so every referral text comes from the jar's defaults and nothing needs editing at deploy. To change a referral text, copy that key from the jar's messages.yml into the file and run /activity reload. Once a key is in the file, later jars won't update it.
• Water streams and pistons moving a player still look like walking. A macro running a real command every few minutes still counts as activity.

Tests

mvn verify: 1075 tests pass. The new code has 100% line coverage. Locally, 10 lines in the existing ActivityCommand/PlayerStore are uncovered because their POSIX-only tests are skipped on Windows. That is unchanged from main, and Linux CI covers them.

Dev test (TFMCDev01, now activity-DEV-referral-20261022d.jar)

~/referral-test/claims.js ran 40 checks with mineflayer bots that have real characters, and all 40 passed on …22d (the halved values and the name: key). Earlier versions of the run passed 38/38 on …22b and …22c. TestChar2 was the new player and TestChar1 the inviter.

• Staff commands:
  • Help, allowip, link (and its loop refusal), settime, unclaim all, rare unclaim all and info all answered correctly.
  • hold refused the claim and handed over nothing; release let it through.
• New player: all four milestones paid. The inventory held exactly 4 steel tools, 64 Dry Rations, 64 Ignitium, 50 gold denars, 2 raw tin and 2 abyssalite fragments, and every milestone then showed ✔. The 1h lore names the Steel Hatchet.
• Inviter: one click on TestChar2's head claimed all four milestones: 10 gold denars and 32 Ignitium, with no tools or tin.
• Rare-track menu: it shows the five steps at 2/4/6/8/10 players. The 4-player step lists 1 raw tin + 1 fragment and the 10-player step 2 + 2, and no step lists denars. With 2 players counted, the 2-player step paid 1 tin + 1 fragment.
• Console checks: markclaimed on an already-claimed milestone changed nothing. rare exclude shows flags: rare-excluded in info, and include undoes it.
• Dev log: no activity warnings or errors.

Nothing was changed on Main or Tutorial. The old jars are backed up under ~/dev-jar-backup/.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}