« Access Condition System (ACS) MENU Security »

Achievements

ENiGMA½ includes a built-in achievement system that rewards users for activity on the board. Achievements are defined in config/achievements.hjson and fire automatically as users accumulate stats. When an achievement is earned the user sees a private interrupt notification; a separate global notification is broadcast to all other online users (if globalText is defined for that tier).

Configuration

Top-level keys

Key	Description
`enabled`	Set to `false` to disable the entire system. Default: `true`
`art`	Art file names for the four achievement interrupt frames (see Art below)
`achievements`	Map of achievement tag → achievement definition

Achievement Definition

Each entry under achievements has a unique tag (e.g. user_login_count) and the following fields:

Field	Required	Description
`type`	Yes	Trigger type — see Achievement Types
`statName`	Yes	The user property stat name that drives this achievement
`retroactive`	No	If `true` (default), earning a higher tier also awards all lower unarned tiers in the same achievement. Set to `false` to only award the exact tier reached.
`match`	Yes	Map of numeric threshold → match details

Match Details

Each key under match is a numeric threshold. When the triggering stat reaches or exceeds that value, the corresponding tier is awarded.

Field	Required	Description
`title`	Yes	Short title for the achievement tier
`text`	Yes	Private notification text shown only to the earning user. Supports format variables.
`globalText`	No	Text broadcast to all other online users when this tier is earned. Omit to suppress global notifications. Supports format variables.
`points`	Yes	Points awarded. Set to `0` for shame/novelty badges that carry no score.

Example:

user_login_count: {
    type: userStatSet
    statName: login_count
    match: {
        10: {
            title: "Curious Caller"
            globalText: "{userName} has logged into {boardName} {achievedValue} times!"
            text: "You've logged into {boardName} {achievedValue} times!"
            points: 10
        }
        25: {
            title: "Inquisitive"
            text: "You've logged into {boardName} {achievedValue} times!"
            points: 15
        }
    }
}

Achievement Types

The type field controls when and how the stat value is compared against thresholds.

Type	Fires on	Value compared
`userStatSet`	Any `setUserStat` call	The new absolute value of the stat
`userStatInc`	Any `incrementUserStat` call	The increment delta for that single event (not the running total)
`userStatIncNewVal`	Any `incrementUserStat` call	The new cumulative total after the increment

When to use each:

userStatSet — Use when the stat is written as an absolute value (login count, streak days, account age in days, UL/DL ratio). The system compares the stored value against your thresholds.
userStatIncNewVal — Use when the stat is incremented and you want to award based on lifetime totals (total messages posted, total mail sent, total files downloaded).
userStatInc — Use when you want to award based on a single-event quantity (e.g. “downloaded 30 files in one session”). The threshold is compared against the per-event delta, not the running total. Set retroactive: false for these since they’re per-event.

Format Variables

The following variables may be used in text, globalText, and title fields via {variableName} syntax. ENiGMA½ string format modifiers (e.g. {achievedValue!sizeWithAbbr}) are supported.

Variable	Description
`{userName}`	Username of the user who earned the achievement
`{userRealName}`	User’s real name
`{userLocation}`	User’s location
`{userAffils}`	User’s affiliations
`{nodeId}`	Node the user is on
`{title}`	Title of the earned tier
`{points}`	Points awarded for this tier
`{achievedValue}`	The threshold value that was met (e.g. `25` for the 25-login tier)
`{boardName}`	System board name from `general.boardName` in config
`{timestamp}`	ISO timestamp when the achievement was earned

Art

Four art files frame achievement interrupt displays. These are configured under the top-level art key and reference art files by name (resolved from the active theme, then system defaults):

Key	Description
`localHeader`	Header shown above the private (local) achievement notification
`localFooter`	Footer shown below the private notification
`globalHeader`	Header shown above the global broadcast notification
`globalFooter`	Footer shown below the global broadcast notification

Art files support the same format variables as text fields, so you can display the achievement title, points, and user name directly in the art.

Built-in Achievements

The default config/achievements.hjson ships with the following achievement categories. All can be customized, extended with additional tiers, or removed entirely.

Achievement	Type	Stat	Tiers
`user_login_count`	`userStatSet`	`login_count`	2, 10, 25, 75, 100, 250, 500 logins
`user_login_streak`	`userStatSet`	`login_streak_days`	7, 14, 30, 60, 100, 365 consecutive days
`user_post_count`	`userStatIncNewVal`	`post_count`	2, 5, 20, 100, 250, 500 posts
`user_mail_sent_count`	`userStatIncNewVal`	`mail_sent_count`	1, 10, 50, 200 messages
`user_node_msg_sent_count`	`userStatIncNewVal`	`node_msg_sent_count`	1, 10, 50, 100 messages
`user_upload_count`	`userStatIncNewVal`	`ul_total_count`	1, 10, 50, 100, 200 files
`user_upload_bytes`	`userStatSet`	`ul_total_bytes`	10 KB → 23 GB
`user_download_count`	`userStatIncNewVal`	`dl_total_count`	1, 10, 50, 100, 200 files
`user_download_bytes`	`userStatSet`	`dl_total_bytes`	640 KB → 5 GB
`user_session_dl_count`	`userStatInc`	`dl_total_count`	5, 15, 30, 45, 60, 90, 120 in one session
`user_session_ul_count`	`userStatInc`	`ul_total_count`	5, 15, 30, 60 in one session
`user_ul_dl_ratio`	`userStatSet`	`ul_dl_ratio`	0.25:1 → 10:1 ratio
`user_door_runs`	`userStatIncNewVal`	`door_run_total_count`	1, 10, 50, 100, 200 runs
`user_individual_door_run_minutes`	`userStatInc`	`door_run_total_minutes`	1, 5, 15, 30, 60, 120, 240 min single session
`user_door_run_total_minutes`	`userStatSet`	`door_run_total_minutes`	10, 30, 60, 120, 240 min lifetime
`user_account_age`	`userStatSet`	`account_days_old`	30 days, 1, 2, 5 years
`user_failed_login_count`	`userStatIncNewVal`	`failed_login_attempts`	3, 10, 25, 50 failures (0 pts — shame badges)
`user_total_system_online_minutes`	`userStatSet`	`minutes_online_total_count`	30 min → 1440 min lifetime

The login streak system uses an anti-cheat minimum gap of 20 hours between logins before a new login counts toward the streak. This prevents the “midnight exploit” where logging in at 11:58 PM and again at 12:02 AM would count as two separate days despite only 4 minutes apart. A 48-hour grace window means missing a day by a few hours doesn’t break the streak — useful for users who log in at slightly different times each day.

UL/DL Ratio Notes

The ul_dl_ratio stat is stored as an integer representing (uploads / downloads) * 100. A value of 100 means a 1:1 ratio; 200 means 2:1; 50 means 0.5:1. The ratio is only computed once the user has at least one upload and one download on record — new accounts are excluded to avoid divide-by-zero.

ACS Integration

Two ACS codes check achievement progress:

Code	Condition
`AC<n>`	User has earned >= n total achievements
`AP<n>`	User has >= n total achievement points

See ACS for general ACS documentation.

MCI Codes

Two MCI codes expose achievement stats for use in art/menus:

Code	Description
`%AC`	Current user’s total achievement count
`%AP`	Current user’s total achievement points

See MCI for general MCI documentation.

Leaderboards

Achievement totals can be surfaced in Top-X leaderboards using the User Event Log:

mciMap: {
    1: {
        type: userEventLog
        value: achievement_pts_earned
        sum: true
        daysBack: 7   // omit for all-time
    }
    2: {
        type: userEventLog
        value: achievement_earned
        sum: false    // count individual achievements earned
        daysBack: 30
    }
}

« Access Condition System (ACS) Security »

Achievements

Achievements

Configuration

Top-level keys

Achievement Definition

Match Details

Achievement Types

Format Variables

Art

Built-in Achievements

Login Streak Notes

UL/DL Ratio Notes

ACS Integration

MCI Codes

Leaderboards