Takaro module library

Takaro Modules

Takaro is a game server management platform for running, automating, and moderating multiplayer communities. These modules install into Takaro to add server automation, Discord workflows, economy systems, and moderation tools.

referral-program

by Takaro
for All Games
Grow a game server community with referral codes, playtime thresholds, and configurable rewards. Referral Program lets players invite friends, tracks successful referrals, and pays rewards when new players qualify.
Use this module to:
  • Let players generate and share personal referral codes.
  • Let new players claim a referral during the configured join window.
  • Reward referees with welcome currency when enabled.
  • Pay referrers with currency or item rewards after the referee reaches the playtime threshold.
  • Track referral stats, referral leaderboards, VIP multipliers, and admin-managed referral links.
Good fit for server owners who want player acquisition, friend invites, retention rewards, and community growth loops managed through Takaro.

Module details

Referral Program

Let players invite friends with personal referral codes and reward the people who help grow your server.

What it does

  • Referrers run /refcode to generate or view a shareable code.
  • New players run /referral <code> during the configured referral window.
  • Referees can receive an immediate welcome currency bonus.
  • Referrers are paid once the referee reaches the configured playtime threshold.
  • Rewards can be currency or items, with VIP reward multipliers for donor/supporter roles.
  • Daily and lifetime caps help prevent referral farming.
  • Admin commands let staff force-link or unlink referrals when needed.
  • /refstats and /reftop make the program visible to players.

Verified dashboard chat flow

The main evidence is the Takaro dashboard chat for koji-paper-1. For this sandbox capture the game-server command prefix was temporarily set to ! so Mineflayer sends normal chat messages instead of Minecraft slash commands. On a normal server the same module commands use whatever command prefix the server has configured.
The screenshot shows the full player-facing referral flow:
  1. Bot1_rafo2g0 runs !refcode and receives referral code N4A46Q.
  2. Bot1_rabo2g0 runs !referral N4A46Q.
  3. The referee receives the 17 currency welcome bonus.
  4. The payout sweep completes the referral and sends the referrer a chat PM for 123 currency.
  5. !refstats shows the referrer has 1 paid referral and 123 currency earned.
  6. !refstats for the referee shows they were referred by Bot1_rafo2g0.
  7. !reftop shows the referrer at the top of the leaderboard.
Takaro dashboard chat showing the referral flow

Player commands

CommandPurpose
/refcodeGenerate or display the player's referral code.
/referral <code>Claim a referral code from the player who invited them.
/refstatsShow personal referral stats, rewards, and referral status.
/reftopShow the top referrers by paid referral count.

Staff commands

CommandPurpose
/reflink <referee> <referrer>Force-create a paid referral link and pay rewards.
/refunlink <referee>Remove a referral link and roll back tracked stats where possible.

Install configuration

These are the fields shown in Takaro when installing the module on a game server.
Referral Program install configuration fields, top
Referral Program install configuration fields, bottom

User config fields

  • prizeIsCurrency: pay referrers currency when enabled; use item rewards when disabled.
  • referrerCurrencyReward: currency paid to the referrer after the referee qualifies.
  • refereeCurrencyReward: immediate welcome currency bonus paid to the referred player.
  • items: item prize pool used when prizeIsCurrency is false.
  • playtimeThresholdMinutes: minutes the referee must play before the referrer is paid.
  • referralWindowHours: how long after first connect a player can still claim a referral code.
  • maxReferralsPerDay: daily cap for successful referrals a player can earn.
  • maxReferralsLifetime: lifetime cap for paid referrals a player can earn.

System config shown during install

The install drawer also shows Takaro's standard system controls for the module: enabled, cronjobs (reset-daily-counters, sweep-pending-referrals), hook (on-player-disconnect), and commands (referral, reftop, refstats, refunlink, refcode, reflink).

Verified sandbox result

This module was smoke-tested against the Takaro Minecraft Paper sandbox (koji-paper-1). The run imported and installed the module, assigned REFERRAL_USE, generated a referral code from live bot chat, claimed it from a second player through live bot chat, ran the payout sweep, and verified /refstats + /reftop in the dashboard chat.
Final state from the dashboard-backed run:
  • Referral code generated: N4A46Q
  • Referral link status: paid
  • Referee welcome bonus: 17 currency
  • Referrer reward: 123 currency
  • referralsTotal: 1
  • referralsPaid: 1
  • referralsRejected: 0
  • currencyEarned: 123

Readable variable evidence

The final Takaro variables are shown below with readable values.
Readable referral code variable
Readable referral link variable
Readable referral stats variable
communityTakaro 0.0.0

Components Overview

1
config
6
commands
1
hooks
2
Cron Jobs
1
functions
3
permissions

New Module: referral-program

May 8, 2026
Added referral-program to the repository

Configuration

Configure this module using the schemas below. The JSON schema defines the data structure, while the UI schema customizes how the configuration form is displayed.

Configuration Schema

Configuration Properties (8)

prizeIsCurrency*boolean
Prize is currency
Default: true
referrerCurrencyReward*number
Referrer currency reward
Default: 500
refereeCurrencyRewardnumber
Referee welcome bonus (currency)
Default: 100
itemsarrayitem
Item prize pool (used when prizeIsCurrency is false)
Default: [] (empty array)
playtimeThresholdMinutes*number
Minutes referee must play before referrer is paid
Default: 60
referralWindowHours*number
Max hours since first connect to claim a referral
Default: 24
maxReferralsPerDay*number
Max referrals per day

Maximum number of successful referrals a player can earn per day

Default: 5
maxReferralsLifetime*number
Max referrals lifetime

Maximum number of paid referrals a player can earn in total (lifetime cap)

Default: 50

UI Schema

No configuration properties defined. This module uses default settings.

About Configuration Schemas

The Configuration Schema defines the structure and validation rules for module settings. The UI Schema customizes how the configuration form is displayed in the Takaro interface, including field ordering, labels, and input types.

Commands (6)

These commands can be executed by players in-game. Each command has a trigger word, optional arguments, and executes JavaScript code on the server.

refcode

/refcodeTrigger Command

Description

Usage: /refcode — Displays your unique referral code. Share it with new players to earn rewards when they join.

Function Implementation

refcode Function

JAVASCRIPT

Usage Example

Player types: /refcode

referral

/referralTrigger Command

Description

Usage: /referral — Enter a referral code from the player who invited you. You must use this within the referral window of your first join (see server config).

Arguments (1)

code
stringPosition 0
Help: Referral code from the player who invited you
Default: None

Function Implementation

referral Function

JAVASCRIPT

Usage Example

Player types: /referral <code>

refstats

/refstatsTrigger Command

Description

Usage: /refstats — View your referral stats including total referrals, earnings, and who referred you.

Function Implementation

refstats Function

JAVASCRIPT

Usage Example

Player types: /refstats

reftop

/reftopTrigger Command

Description

Usage: /reftop — Shows the top 10 players by number of successful referrals.

Function Implementation

reftop Function

JAVASCRIPT

Usage Example

Player types: /reftop

reflink

/reflinkTrigger Command

Description

Usage: /reflink — Admin only. Provide the full exact display name of each player (case-sensitive). Force-creates a paid link and pays both rewards.

Arguments (2)

referee
stringPosition 0
Help: Full exact display name of the referee player
Default: None
referrer
stringPosition 1
Help: Full exact display name of the referrer player
Default: None

Function Implementation

reflink Function

JAVASCRIPT

Usage Example

Player types: /reflink <referee> <referrer>

refunlink

/refunlinkTrigger Command

Description

Usage: /refunlink — Admin only. Provide the full exact display name of the referee player (case-sensitive). Removes their referral link.

Arguments (1)

referee
stringPosition 0
Help: Full exact display name of the referee player to unlink
Default: None

Function Implementation

refunlink Function

JAVASCRIPT

Usage Example

Player types: /refunlink <referee>

About Module Commands

Commands allow players to interact with your module through chat. Each command has a trigger word that players type (prefixed with /), optional arguments for parameters, and a JavaScript function that executes when the command is used. Arguments are automatically validated and passed to the function.

Hooks (1)

These hooks respond to various game events automatically. Each hook executes JavaScript code when its specific event type occurs, allowing modules to react to player actions, system changes, and more.

Real-time Events

1 hook

on-player-disconnect

player-disconnectedEvent Type
Description
Check and pay referrer when a referee disconnects (catches short sessions before the 15-min sweeper runs)
Function Implementation

on-player-disconnect Hook Function

JAVASCRIPT
Event Details
Event Type:player-disconnected
Trigger:Automatic
Category:Real-time Events

About Module Hooks

Hooks allow your module to respond automatically to game events like player actions, server status changes, and chat messages. Each hook has an event type that determines when it triggers, optional regex patterns for filtering specific events, and a JavaScript function that executes when the conditions are met. Hooks are grouped by category for better organization.

Scheduled Jobs (2)

These jobs run automatically on a schedule defined by cron expressions. Each job executes JavaScript code at specific times or intervals.

sweep-pending-referrals

*/15 * * * *Schedule

Description

Walk pending referral links and pay out referrers who have crossed the playtime threshold

Schedule Details

Cron Expression
*/15 * * * *
Human-Readable Schedule

Every 15 minutes

Function Implementation

sweep-pending-referrals Function

JAVASCRIPT

Cron Expression Format

minute hour day-of-month month day-of-week

Each field can contain numbers, ranges (1-5), lists (1,3,5), or wildcards (*). Use */n for intervals (e.g., */5 for every 5 units).

reset-daily-counters

0 0 * * *Schedule

Description

Reset daily referral counts at UTC midnight

Schedule Details

Cron Expression
0 0 * * *
Human-Readable Schedule

Daily at midnight

Function Implementation

reset-daily-counters Function

JAVASCRIPT

Cron Expression Format

minute hour day-of-month month day-of-week

Each field can contain numbers, ranges (1-5), lists (1,3,5), or wildcards (*). Use */n for intervals (e.g., */5 for every 5 units).

About Scheduled Jobs

Cron jobs allow your module to execute code automatically on a schedule. Each job has a cron expression that defines when it runs, and a JavaScript function that executes at those times. Jobs run server-side and can perform maintenance tasks, send notifications, or update game state automatically.

Functions (1)

Reusable JavaScript functions that can be imported and used by other module components like commands, hooks, and cron jobs. These promote code reuse and modularity.

referral-helpers

functionReusable Component

Function Implementation

referral-helpers Function

JAVASCRIPT

Import Usage

Import: import { referral-helpers } from './utils';

About Module Functions

Functions are reusable JavaScript components that can be imported and used by commands, hooks, and cron jobs within your module. They promote code reuse, improve maintainability, and allow you to organize complex logic into modular pieces. Functions must be exported with proper ES6/CommonJS syntax to be importable by other components.

Permissions (3)

These permissions control who can access different features of this module. Administrators can assign these permissions to roles, allowing fine-grained access control.

General Permissions

3 permissions

Referral admin

REFERRAL_ADMINPermission Key
Description

Required for /reflink, /refunlink; bypasses caps and window checks

Permission Details
Full Key:REFERRAL_ADMIN
Can Have Count:No
Category:General

Use referral system

REFERRAL_USEPermission Key
Description

Required for /refcode, /referral, /refstats, /reftop

Permission Details
Full Key:REFERRAL_USE
Can Have Count:No
Category:General

VIP tier

REFERRAL_VIPPermission KeyCountable
Description

Count = tier; +5% referrer reward per tier, capped at +25%

Permission Details
Full Key:REFERRAL_VIP
Can Have Count:Yes
Category:General
Countable Permission

This permission supports numeric values/levels. For example, you could grant someone "10" of this permission to limit their usage or set permission levels.

About Module Permissions

Permissions control access to module features and functionality. Each permission has a unique key for identification, a friendly name for display, and a description explaining what it allows. Some permissions are countable, meaning they can have numeric values or limits assigned. Administrators assign these permissions to user roles to control who can use different module features.