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
- 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.
Module details
Referral Program
What it does
- Referrers run
/refcodeto 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.
/refstatsand/reftopmake the program visible to players.
Verified dashboard chat flow
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.Bot1_rafo2g0runs!refcodeand receives referral codeN4A46Q.Bot1_rabo2g0runs!referral N4A46Q.- The referee receives the
17currency welcome bonus. - The payout sweep completes the referral and sends the referrer a chat PM for
123currency. !refstatsshows the referrer has1paid referral and123currency earned.!refstatsfor the referee shows they were referred byBot1_rafo2g0.!reftopshows the referrer at the top of the leaderboard.

Player commands
| Command | Purpose |
|---|---|
/refcode | Generate or display the player's referral code. |
/referral <code> | Claim a referral code from the player who invited them. |
/refstats | Show personal referral stats, rewards, and referral status. |
/reftop | Show the top referrers by paid referral count. |
Staff commands
| Command | Purpose |
|---|---|
/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


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 whenprizeIsCurrencyis 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
enabled, cronjobs (reset-daily-counters, sweep-pending-referrals), hook (on-player-disconnect), and commands (referral, reftop, refstats, refunlink, refcode, reflink).Verified sandbox result
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.- Referral code generated:
N4A46Q - Referral link status:
paid - Referee welcome bonus:
17currency - Referrer reward:
123currency referralsTotal:1referralsPaid:1referralsRejected:0currencyEarned:123
Readable variable evidence



Components Overview
New Module: referral-program
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)
Prize is currency
trueReferrer currency reward
500Referee welcome bonus (currency)
100Item prize pool (used when prizeIsCurrency is false)
[] (empty array)Minutes referee must play before referrer is paid
60Max hours since first connect to claim a referral
24Max referrals per day
Maximum number of successful referrals a player can earn per day
5Max referrals lifetime
Maximum number of paid referrals a player can earn in total (lifetime cap)
50UI 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.
referral
Description
Arguments (1)
code
stringPosition 0NoneFunction Implementation
referral Function
JAVASCRIPTUsage Example
refstats
Description
Function Implementation
refstats Function
JAVASCRIPTUsage Example
reftop
Description
Function Implementation
reftop Function
JAVASCRIPTUsage Example
reflink
Description
Arguments (2)
referee
stringPosition 0Nonereferrer
stringPosition 1NoneFunction Implementation
reflink Function
JAVASCRIPTUsage Example
refunlink
Description
Arguments (1)
referee
stringPosition 0NoneFunction Implementation
refunlink Function
JAVASCRIPTUsage Example
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
on-player-disconnect
Description
Function Implementation
on-player-disconnect Hook Function
JAVASCRIPTEvent Details
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
Description
Schedule Details
Cron Expression
Human-Readable Schedule
Every 15 minutes
Function Implementation
sweep-pending-referrals Function
JAVASCRIPTCron Expression Format
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
Description
Schedule Details
Cron Expression
Human-Readable Schedule
Daily at midnight
Function Implementation
reset-daily-counters Function
JAVASCRIPTCron Expression Format
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
Function Implementation
referral-helpers Function
JAVASCRIPTImport Usage
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
Referral admin
REFERRAL_ADMINPermission KeyDescription
Required for /reflink, /refunlink; bypasses caps and window checks
Permission Details
REFERRAL_ADMINUse referral system
REFERRAL_USEPermission KeyDescription
Required for /refcode, /referral, /refstats, /reftop
Permission Details
REFERRAL_USEVIP tier
REFERRAL_VIPPermission KeyCountableDescription
Count = tier; +5% referrer reward per tier, capped at +25%
Permission Details
REFERRAL_VIPCountable 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.

































