VelorSTUDIO
EN
BuiltByBit
HomePluginsPlaygroundDocumentationChangelogSupportDiscordBuiltByBit

Configuration reference

config.yml is the operator-owned control surface. ReferralTrack never replaces a customized file silently. When its schema version changes, the plugin preserves the original as config.yml.bak-v<old>, writes the complete new reference to config.new-v<new>.yml, updates only the version marker in the active file and reports missing paths at startup. Bukkit's bundled defaults keep new options operational until the operator copies or customizes them.

Administrative access uses granular Bukkit permission nodes and works with LuckPerms without OP or a hard API dependency. See Commands and permissions; referraltrack.admin remains the all-access parent.

Main systems #

  • database: SQLite or MySQL/MariaDB connection and bounded pool timings. Keep credentials private.
  • referral: claim policy, known sources, personal codes, validation, reward limits, commands, milestones and retention attribution.
  • campaigns: engine switch, timezone and independent campaign dates, filters, codes, multipliers, rewards and milestones. See Campaigns.
  • fraud: risk engine switch, staff-review threshold and account/playtime signals. See Fraud review.
  • discord: optional webhook routes, reports, live-stat update interval, branded embed fields and safe HTTPS media/button URLs. A full Discord bot is not part of this release.
  • integrations.developer-api: Bukkit ServicesManager registration for the read-only asynchronous API. events.pre-claim and events.claim-result independently control the two public claim events; disabling the API disables both. See Developer API.
  • text-formatting: independently enables MiniMessage formatting and legacy ampersand codes. Recognized MiniMessage gradients, rainbow, RGB colour and style tags can coexist with & and &#RRGGBB; ordinary angle-bracket placeholders remain literal.
  • player-interface: selects AUTO, INVENTORY or DIALOG. AUTO uses Paper's native Java Dialog API when present and otherwise opens the standalone inventory. Dialog body/button widths, columns, pause/escape behavior and fallback policy are bounded and configurable. Dialog text and all four button labels are localized under dashboard.dialog-*. /referral inventory always opens the standalone menu.
  • player-feedback.claim: claim title, subtitle, action bar, sound and particle controls. Each channel has its own switch; title timings, sound volume/pitch and particle count/offset/speed are bounded. Particle animation supports bounded BURST, RING and HELIX shapes with configurable frames, interval, radius and height. Invalid sound, particle or animation values fail soft with a once-only diagnostic.
  • onboarding: first-start guidance, automatic read-only validation and maximum reported findings. /referraltrack validate checks database/pool bounds, referral identity and reward constraints, validation/fraud thresholds, report schedules, passive network nodes and enabled-but-unconfigured Discord. It reports paths and safe expectations, never configured secret values.
  • velogrowth: quality-ranking switch, minimum sample, leaderboard size, evaluation window and six relative weights. Raw volume only determines eligibility. Validation, rejection safety, risk safety and mature D1/D7/D30 retention contribute to the 0–100 score; immature cohorts are omitted and every input is shown by /referraltrack growth.
  • campaign-guard: activation preflight switch, ending-soon window, reward-multiplier warning, maximum command count, missing-economy severity and configurable per-claim/estimated-total money thresholds. The total estimate uses exposure.expected-claims. Critical findings block campaign enable and engine-on; warnings remain visible without silently changing the campaign.
  • reward-rescue: staff permission, list size, pending/stuck age thresholds and maximum manual attempts. /referraltrack rescue is read-only unless retry or cancel includes confirm and a printable reason. Processing rows are never retried automatically because Vault or a console command may already have run before a crash. See Reward Rescue.
  • settings: tracking/delivery ownership for networks, ignored identities and retention cleanup.
  • menu: all shipped inventory sizes, slots, materials, titles, lore, page capacities, navigation, reward-history time display and progress-bar appearance.

Every player/staff-visible sentence is in lang/<language>.yml; five complete bundled languages are provided. Missing custom translation keys fall back to bundled English without overwriting the custom language file.

Claim feedback text is localized through feedback.claim-title, feedback.claim-subtitle and feedback.claim-action-bar. Supported placeholders are {player}, {source} and {status}. Visual and audio mechanics remain under player-feedback.claim so operators can change presentation without editing translations.

Inventory sizes must be a multiple of 9 between 9 and 54. Slots are zero-based and must fit the configured inventory. Material fields accept Bukkit materials plus HEADDB:<id>, HDB:<id> and DeluxeMenus-style hdb-<id> references when HeadDatabase is installed and loaded. Missing plugins, unknown IDs and invalid materials fall back to a safe built-in material with a console warning. Out-of-range numeric values are bounded and diagnosed. Slot lists discard invalid and duplicate entries; if none remain, the safe built-in layout is used.

menu.player-dashboard.progress controls the progress slot, material, length (1–40), glyphs and colours. reward-history-button controls its entry button.

menu.reward-history controls its inventory size, ordered content slots, maximum rows (1–45), queued/processing/delivered/cancelled materials, empty/back/close controls, Java date pattern and time zone. Use SYSTEM for the host time zone or an IANA ID such as Europe/Istanbul.

menu.admin-dashboard and menu.admin-review control sizes, ordered page slots, state/risk materials and every navigation/control slot. Their effective page capacity is the count of valid content slots, so pagination stays consistent with custom layouts.

Avoid assigning two actions to the same slot: the item written last will be visible and that can make another action inaccessible. After any layout edit, run /referraltrack reload, inspect console diagnostics, then manually open the player and staff menus before production use.

Presets and secrets #

See Presets and themes before applying /referraltrack install <preset> confirm. Presets never modify database credentials, tokens or webhook URLs. /referraltrack doctor, exports and GUIs do not expose those values. Keep backups outside publicly downloadable web roots and restrict filesystem access to the Minecraft service account.

Themes #

See Presets and themes before applying /referraltrack theme <theme> confirm. Theme preview is read-only; confirmed installation creates an exact backup and changes only documented menu/progress/claim- feedback presentation paths. It never changes reward, campaign, permission, database or secret data.