Skip to content

General XP

General XP is a separate, server-wide progression balance for configured sources that do not belong to a skill. Built-in sources include configured advancement rewards, daily join and login-streak rewards, and AFK-aware active-time rewards. Compatible integrations can also award it through the public adapter API.

General XP is not a pseudo-skill. It does not raise any skill level, change skill leaderboards, or satisfy item, recipe, action, or world gates. Global Rank adds converted General XP points to the sum of enabled skill levels. General XP is global-only; world and world-group leaderboard scopes do not change it.

Player commands and placeholders

  • /mcp general shows the player's General XP, describes the built-in source types, and shows the rank-point contribution with its configured conversion rate. It explains when Global Rank is disabled or General XP is excluded from its score.
  • /mcp top general shows the server-wide General XP leaderboard.
  • /mcp rank shows the combined score and its skill-level/General XP breakdown.
  • %mcprogression_general_xp% returns lifetime General XP.
  • %mcprogression_general_rank_points% returns the converted General XP contribution.
  • %mcprogression_global_skill_score% returns enabled skill levels only.
  • %mcprogression_global_score% returns the combined Global Rank points.

Configure advancement rewards

Edit plugins/McProgression/general-xp.yml and restart the server. The shipped file contains a small exact-key reward list. Unlisted advancements earn zero XP by default. Recipe advancements are omitted because recipe unlocks can occur through ordinary crafting and can make poor progression milestones. Configure the shared daily-boundary timezone as time-zone in config.yml; the default is Europe/Brussels.

enabled: true
maximum-xp-per-award: 25
daily-xp-cap: 100 # configured local calendar day; use 0 for no daily cap

advancements:
  enabled: true
  default-xp: 0
  rewards:
    "minecraft:story/mine_stone": 2
    "minecraft:story/smelt_iron": 3
    "minecraft:husbandry/tame_an_animal": 4

sources: {}

Use the advancement's namespaced key. Rewards must be finite and non-negative; zero explicitly disables a reward. The per-award maximum caps any configured value. The optional daily cap applies to all General XP sources together. Both totals are stored in the progression backend and do not depend on CoreProtect.

The plugin only observes completions after it starts; it does not grant retroactive XP for advancements a player already earned. A player's advancement claim is durable and one-time, so revoking and completing an advancement again does not pay twice. Bukkit's completion event does not identify whether a completion came from gameplay or an administrator's /advancement grant command. Keep that command restricted to trusted staff, and give staff mcprogression.admin.bypass.xp if they should receive no McProgression XP.

Daily join and active-time rewards

activity-rewards.daily-join grants its configured base amount once per player per calendar date in the configured time-zone. Its optional streak-bonus adds xp-per-consecutive-day for each consecutive local calendar day after the first, up to maximum-bonus-xp; for example, the defaults add 1 XP on day 2, 2 XP on day 3, and stop increasing after a 7 XP bonus. The streak breaks when a local calendar date is missed. Both the daily claim and the last successfully rewarded date/streak count are stored with the player's profile, so reconnecting or restarting cannot pay twice. A join counts on its own; there is no minimum session requirement.

The base reward and streak bonus are one General XP award and share the per-award and daily caps with every other source. If no XP can be applied because a cap is exhausted, that date is not added to the streak. Set activity-rewards.daily-join.streak-bonus.enabled: false to keep the daily reward without streak bonuses.

Set time-zone in config.yml to a Java/IANA timezone ID such as Europe/Brussels, Europe/Amsterdam, or UTC. This one setting controls daily skill XP caps, General XP caps, daily join claims, and login-streak dates. Day changes follow the timezone's daylight-saving rules; no fixed-length overlap window is used. If the setting is blank or invalid, McProgression logs a warning and uses UTC. XP history buckets remain grouped by UTC date/month.

activity-rewards.active-time pays at the configured XP-per-hour rate in bounded intervals. Time only accumulates while the player is online in Survival or Adventure and has moved or performed a successful interaction, inventory, crafting, fishing, consumption, block, or combat action within the inactivity timeout. It stops after that timeout and resumes after another qualifying action. The default rate is 5 XP per active hour, evaluated in five-minute intervals. Partial intervals are retained in the profile and never count offline time.

This is an inactivity heuristic, not reliable human-presence or anti-cheat detection: movement macros and automated gameplay can still appear active, and vanish/AFK plugin state is not read. Configure the rate conservatively and disable the source if the server needs stronger AFK controls. Daily join and active-time rewards share the General XP per-award and configured local-calendar-day caps with all other General XP sources.

Global Rank conversion

Configure global-rank.general-xp-per-score-point in config.yml. For example, 100 means each 100 General XP adds one point to Global Rank. Set it to 0 to exclude General XP from the rank score while still tracking and displaying the balance. Tune the conversion together with global-rank.tiers; the total score now consists of:

sum(enabled skill levels) + floor(General XP / general-xp-per-score-point)

Existing skill XP and levels are not migrated or changed. General XP begins at zero for existing profiles, and contributes only as players earn it after installation.

Adding another uncategorized source

Only successful, player-attributed events with meaningful progression value belong in General XP. Do not feed passive statistics, generic interactions, pickups, drops, damage ticks, or raw counters into this track. If an event clearly represents a skill, award that skill instead.

A server plugin can call the public method from its successful event adapter:

McProgressionPlugin progression = (McProgressionPlugin)
        Bukkit.getPluginManager().getPlugin("McProgression");
if (progression != null) {
    progression.awardGeneralXp(player, "myplugin_quest", 5.0, questCompletionId);
}

Use a stable event key for one-time rewards. McProgression stores the claim with that player's General XP in the configured persistence snapshot, so retrying the same event cannot pay twice. For repeatable sources, pass null as the event key and configure sources.<sourceId>.cooldown-seconds; calls without either a unique event key or a cooldown are rejected. Cooldowns are in-memory and reset on restart, so durable one-time rewards should always use an event key. The global per-award and daily caps apply to adapter awards too. Source IDs must be stable lowercase identifiers using letters, numbers, _, or -. Call the adapter on the server's main thread.

Operations and validation

The startup audit checks caps, advancement-key format, reward values, and rewards above the per-award cap. General XP is persisted in the same configured YAML/SQLite/MySQL/PostgreSQL progression store as skills. Validate advancement completion, restart persistence, duplicate/revoked completion, daily caps, Global Rank conversion, placeholders, and command behavior on every claimed server version. Compilation against the current Paper API does not validate the 26.3 runtime baseline.

XP history is stored as compact daily player/action/rank/group buckets, then monthly snapshots. It records successful skill awards, General XP awards, and identified history imports after this feature is installed; it does not reconstruct old balances. See moderator XP investigation for permissions and retention.