Points & modifiers

Set up the rules that award points for driving and events, boost them with modifiers, and keep the economy healthy with caps and decay.

How points work#

Points are your Hub's activity currency. Rules turn things drivers do — completing a delivery, attending a convoy — into points; modifiers boost them during campaigns; caps and decay keep the totals meaningful. Every change lands in an append-only ledger, so a driver's history is always explainable and nothing is ever double-counted: the same delivery or roll-call can only award each rule once, even if it's processed twice.

Everything lives in the Hub panel's Engagement group: Points rules, Points modifiers, Points ledger and Points settings. Editing rules, modifiers, caps and settings needs the points.manage_rules permission; viewing the ledger needs points.view; awarding by hand needs points.award.

Changing a rule only affects future awards — points already in the ledger are never rewritten.

The rules every Hub starts with#

Three fully editable rules are created with your Hub. Retune, rename, deactivate or delete any of them:

The Trucky triggers need your Hub linked to Trucky — see /integrations/trucky. Attendance points are awarded when staff mark a driver present at roll-call, not when they RSVP — see /admin/events.

Create or edit a rule#

On Points rules, create a rule and work through the sections:

1. Rule — the Name and the Trigger: Event attendance, Distance driven (Trucky), Delivery completed (Trucky), Clean delivery (Trucky), Driving score reached (Trucky), Manual award or Custom trigger.
2. Amount — the Points for a flat award. Only the distance trigger can switch Amount type to Per unit, where you set Points per unit, the Unit size (km) and the Rounding (Round down, Round up, Round to nearest).
3. Conditions — optional filters; leave blank to match everything. Depending on the trigger: Event type, Minimum km per job, Minimum driving score (0–100), Game.
4. Availability — the Active toggle and an optional Effective from / Effective until window, handy for seasonal rules.

The Preview section keeps you honest: a plain-language summary plus a live simulation ("A 750 km delivery would earn 7 pts") computed by the same engine that will do the real awarding.

Custom triggers#

A Custom trigger rule is one your Hub invents — "Screenshot contest winner", "Convoy control volunteer" — with a flat amount. It never fires on its own; staff award it from the ledger page, individually or in bulk, and every award stays traceable to the rule.

Worked example: a delivery#

A driver completes a 620 km Trucky delivery, with the default rules and no modifiers active:

• Distance driven — 620 km ÷ 100 km per unit = 6.2 units, rounded down to 6; 6 × 1 point = 6 points.
• Complete a delivery — a flat 5 points.

Two ledger entries are written against that one job, so the driver earns 11 points in total. If the same delivery were somehow reported again, neither rule would award a second time.

Modifiers#

Modifiers are your campaign tool: a Multiplier scales matching awards ("2× points this weekend"), a Flat bonus adds a fixed number of points on top. Create them on Points modifiers:

1. Modifier — the Name, the Type, and the Value (e.g. 2 for 2×, or the bonus points).
2. Applies to — the Scope: All rules, Specific rules, or Trigger types (e.g. every attendance rule).
3. Window — when it's live. Fixed dates runs between Starts at and Ends at; Recurring weekly repeats on chosen Days of week between two times of day, in your Hub's timezone ("double points every Friday and Saturday evening").
4. Availability — the Active toggle.

When several multipliers overlap, the Modifier stacking policy in Points settings decides the outcome: Highest wins (the default) applies only the single largest multiplier, so campaigns never compound; Stack multiplicatively multiplies them together. Flat bonuses always add on, whatever the policy. The final amount is the base times the effective multiplier (rounded to the nearest point), plus the bonuses.

Worked example: a convoy during a double-points weekend#

Your Hub runs a "Double points weekend" (a 2× multiplier on all rules) that happens to overlap a "Convoy season" 1.5× multiplier. A driver is marked present at a convoy:

• Base award: Attend an event = 50 points.
• With the default Highest wins stacking, only the 2× applies: 50 × 2.0 = 100 points.
• Had you set Stack multiplicatively, the factors combine: 50 × (2.0 × 1.5) = 150 points.

The ledger entry stores the full breakdown — base, which modifiers applied, and the effective multiplier — so you can always answer "why did this award 100?".

Caps#

Caps put a per-driver ceiling on earnings so a marathon session can't run away with the leaderboard. They live on the Points settings page under Caps — use Add cap and set:

• Name — e.g. "Daily driving cap".
• Source — what it limits: Trucky job, Event attendance, Manual award, or leave it as All sources.
• Period — Per day, Per week or Per month, rolling over at your Hub's local midnight.
• Max points — the ceiling, and an Active toggle.

At award time the engine sums what the driver already earned from that source in the current period and trims the new award to fit; anything over the ceiling is simply dropped (and recorded in the entry's breakdown).

Decay#

Optionally, idle balances shrink over time so ranks reflect who's active. On Points settings under Points decay:

Decay runs once a month and writes negative Decay entries to the ledger — history is never rewritten, and a balance can't go below zero. For example, with the default 2% a driver holding 1,250 points loses 25 on the next run.

Before you commit, use the Preview decay button at the top of the page: it evaluates the values currently in the form — even unsaved ones — and tells you exactly how many members would lose how many points.

Manual awards and corrections#

The Points ledger page is the Hub-wide feed of every entry — filter by member to see one driver's history. Its two header actions (permission points.award) are how staff move points by hand:

• Award points — pick a Member, an Amount (negative to deduct), an optional Reason category, and a required Reason the driver will see in their history. A live Resulting balance preview shows the balance move before you confirm.
• Bulk award — the same, to many people at once: hand-picked members, or every confirmed attendee of an event. Bulk awards run in the background and you're notified when they finish; the event variant is safe to re-submit — nobody is credited twice.

If the bot is in your Discord server, staff can also award from there with /points award — see slash commands.

Two knobs on Points settings shape this, under Manual awards: Reason categories (the default list is Bonus, Correction, Contest, Recognition, Other) and Require a linked custom trigger for manual awards (off by default) — turn it on and every positive hand-award must reference a custom-trigger rule, which keeps ad-hoc awards accountable. Corrections (negative amounts) are always exempt.

Driving score and points#

If your Hub scores driving behaviour on Trucky deliveries, you can pay points for quality, not just distance. It's opt-in: on the driving score page, turn on Let driving score feed points (see /integrations/trucky). Then two triggers come alive:

• Clean delivery (Trucky) — a flat award whenever a delivery comes in clean under your Hub's clean-delivery threshold.
• Driving score reached (Trucky) — a flat award gated by the rule's Minimum driving score condition, so you can reward "scored 90 or better".

Neither default rule exists for these — create them yourself when you're ready.

What drivers see#

Drivers follow their own balance on My points in the driver panel — every entry with its reason — and on the dashboard widgets. Points feed rank thresholds (see /admin/ranks) and competitions.

Related guides#

• /admin/ranks — turn points into a ladder drivers climb
• /admin/loas — approved leave can pause decay
• /admin/events — attendance is a points source
• /integrations/trucky — the delivery data behind the driving triggers