Proficiency is an extensible, data-driven framework designed for Minecraft. It provides server administrators and modpack developers the architecture necessary to construct bespoke, RPG-style progression systems. Utilizing this framework, player statistics (e.g., maximum health, attack damage, movement speed) can be dynamically scaled in response to in-game actions such as mining, combat, traversal, and crafting.
Please Note: As of version 1.0.0-pre1, Proficiency is distributed as a fundamental framework without any default configurations. The mod will not alter gameplay mechanics natively. Administrators are required to explicitly define proficiencies and associated actions via JSON configuration structures.
Upon server initialization or the loading of a single-player environment, the framework establishes the following directory structure within the config path:
config/proficiency/proficiencies/(Designated for stat definitions)config/proficiency/actions/(Designated for XP acquisition triggers)
Administrators may provision an arbitrary number of JSON files within these directories. The nomenclature of each JSON file serves as its internal registry identifier.
A Proficiency dictates the relevant statistic, its maximum progression ceiling, the scaling formula for experience (XP), and the precise attribute modifiers conferred to the player.
Example configuration for config/proficiency/proficiencies/mining.json:
{
"name": "Mining Proficiency",
"max_level": 100,
"starting_level": 1,
"xp_curve": [
{
"up_to_level": 20,
"base_xp": 500.0,
"xp_multiplier": 50.0
},
{
"up_to_level": 100,
"base_xp": 1000.0,
"xp_multiplier": 150.0
}
],
"attribute_modifiers": [
{
"attribute": "minecraft:generic.max_health",
"operation": "add_value",
"amount_per_level": 1.0
}
]
}The experience requisite to advance to the subsequent level operates on a bracketed linear formula. The framework iterates through the xp_curve array to identify the appropriate math for the player's current level:
Required XP = base_xp + (current_level * xp_multiplier)
The attribute_modifiers array accepts an unlimited number of targeted augmentations.
add_value: Implements a flat numerical enhancement (e.g., +1 Max Health per level).add_multiplied_base: Implements a percentage scaling based on the player's core attributes.add_multiplied_total: Implements a compounding percentage scaling incorporating all other existing modifiers.
You can explicitly configure fully customized sensory feedback triggered by either XP gains or level-ups within the indicators object:
- Text Systems: Utilize
"chat_message","action_bar","title", and"subtitle"keys. All text strings parse formatting codes (&) and dynamically inject variables ({xp},{level},{proficiency}). - Sensory Systems: Configure
"sound","sound_pitch","sound_volume","particles", and"particle_count"to spawn vanilla or modded sensory effects. Level-up effects are broadcasted to nearby players, whereas XP gain effects are completely private. - Dynamic Boss Bars: Setting
"show_boss_bar": trueunder"on_xp_gain"will conjure a customized boss bar at the top of the player's screen tracking their exact XP progress toward the next level. The bar automatically decays after"boss_bar_duration_ticks". You can manipulate"boss_bar_color"(BLUE,GREEN,RED,YELLOW,PURPLE,PINK,WHITE) and"boss_bar_style"(PROGRESS,NOTCHED_6,NOTCHED_10,NOTCHED_12,NOTCHED_20).
An Action establishes the contextual trigger. When the conditions of an action are met, the specified proficiency is credited with experience points.
Example configuration for config/proficiency/actions/mine_stone.json:
{
"action_type": "break",
"target_proficiency": "mining",
"flat_xp_reward": 5.0,
"event_value_multiplier": 0.0,
"conditions": {
"main_hand_tag": ["minecraft:pickaxes", "minecraft:shovels"],
"event_block": "minecraft:stone"
}
}The action_type property must exactly match one of the following enumerations:
hit: Triggers upon the player inflicting damage to a valid entity.hurt: Triggers upon the player sustaining damage from an entity.kill: Triggers upon the player terminating an entity.breakorharvested: Triggers upon the player breaking a block.place: Triggers upon the player placing a block.slept: Triggers upon the player completing a sleep cycle in a bed.ride: Triggers upon the player mounting an entity.crafted: Triggers upon the player concluding a crafting operation.smelted: Triggers upon the player completing a smelting operation.walk: Triggers periodically in proportion to walking distance.run: Triggers periodically in proportion to sprinting distance.sneak: Triggers periodically in proportion to sneaking distance.
The experience rewarded for an action can be scaled dynamically using precise algebraic logic. The framework calculates the final reward utilizing the following formula:
Total XP = flat_xp_reward + (event_value * event_value_multiplier)
The event_value is populated dynamically based on the contextual action:
- Hit/Hurt: The numerical damage metric.
- Crafted/Smelted: The resultant output stack size.
- Walk/Run/Sneak: The distance traversed measured in blocks.
- Miscellaneous Actions: Static value of 1.0.
The conditions object evaluates contextual prerequisites before granting XP. If this object is omitted entirely, the action will trigger universally (e.g., inflicting damage without a held item).
Supported condition constraints:
"main_hand": Validates the exact item held by the player (e.g.,minecraft:iron_sword)."main_hand_tag": Validates the tag associated with the player's held item (e.g.,minecraft:swords)."off_hand": Validates the exact item held in the player's off-hand (e.g.,minecraft:shield)."off_hand_tag": Validates the tag associated with the player's off-hand item."event_item": Validates the exact item being processed during crafting or smelting (e.g.,minecraft:cooked_beef)."event_item_tag": Validates the tag associated with the item being crafted or smelted (e.g.,forge:cooked_meat)."event_block": Validates the exact block subject to interaction, such as breaking or placing (e.g.,minecraft:diamond_ore)."event_block_tag": Validates the tag associated with the block subject to interaction (e.g.,minecraft:mineable/pickaxe).
Multiple conditions may be concatenated within a single configuration. All stipulated conditions must be satisfied concurrently for the experience points to be awarded. Furthermore, any individual condition may accept an array [] of strings, which will be evaluated using boolean "OR" logic (e.g., "main_hand": ["minecraft:iron_sword", "minecraft:diamond_sword"]).
To illustrate the absolute limits of the framework, the following examples demonstrate extreme, multifaceted progression scenarios utilizing every available mathematical and conditional feature.
This proficiency represents an endgame combat progression. The XP scaling curve becomes exponentially more difficult across four distinct level brackets. Concurrently, it augments four separate attributes using a mix of flat additions and multiplicative percentage scaling. The associated action only grants experience if the player lands a successful strike while dual-wielding specific endgame weaponry and holding a shield. The XP granted scales directly with the exact damage inflicted.
Proficiency (config/proficiency/proficiencies/apex_predator.json):
{
"name": "The Apex Predator",
"max_level": 100,
"starting_level": 1,
"xp_curve": [
{ "up_to_level": 25, "base_xp": 1000.0, "xp_multiplier": 50.0 },
{ "up_to_level": 50, "base_xp": 2500.0, "xp_multiplier": 150.0 },
{ "up_to_level": 75, "base_xp": 10000.0, "xp_multiplier": 500.0 },
{ "up_to_level": 100, "base_xp": 50000.0, "xp_multiplier": 2000.0 }
],
"attribute_modifiers": [
{
"attribute": "minecraft:generic.attack_damage",
"operation": "add_value",
"amount_per_level": 0.5
},
{
"attribute": "minecraft:generic.max_health",
"operation": "add_value",
"amount_per_level": 1.0
},
{
"attribute": "minecraft:generic.movement_speed",
"operation": "add_multiplied_base",
"amount_per_level": 0.02
},
{
"attribute": "minecraft:generic.attack_speed",
"operation": "add_multiplied_total",
"amount_per_level": 0.05
}
],
"indicators": {
"on_xp_gain": {
"action_bar": "&c+{xp} Apex Predator XP",
"sound": "minecraft:entity.player.attack.crit",
"sound_pitch": 1.5,
"show_boss_bar": true,
"boss_bar_color": "RED",
"boss_bar_style": "NOTCHED_10",
"boss_bar_duration_ticks": 60
},
"on_level_up": {
"title": "&4APEX LEVEL UP",
"subtitle": "&cYou are now a Level {level} Predator.",
"sound": "minecraft:entity.ender_dragon.growl",
"sound_pitch": 0.5,
"particles": "minecraft:crimson_spore",
"particle_count": 100
}
}
}Action (config/proficiency/actions/apex_strike.json):
{
"action_type": "hit",
"target_proficiency": "apex_predator",
"flat_xp_reward": 0.0,
"event_value_multiplier": 12.5,
"conditions": {
"main_hand": ["minecraft:diamond_sword", "minecraft:netherite_sword", "minecraft:mace"],
"off_hand_tag": "forge:shields"
}
}This proficiency rewards the player with immense natural durability. The progression is tied exclusively to smelting high-tier, rare materials. It demonstrates the algebraic XP system: granting a massive flat XP reward simply for completing a smelting action, plus an additional exponential bonus multiplied by the exact number of items successfully smelted in that specific stack.
Proficiency (config/proficiency/proficiencies/artificer.json):
{
"name": "Grandmaster Artificer",
"max_level": 50,
"starting_level": 1,
"xp_curve": [
{ "up_to_level": 25, "base_xp": 5000.0, "xp_multiplier": 250.0 },
{ "up_to_level": 50, "base_xp": 15000.0, "xp_multiplier": 1000.0 }
],
"attribute_modifiers": [
{
"attribute": "minecraft:generic.armor_toughness",
"operation": "add_value",
"amount_per_level": 0.25
},
{
"attribute": "minecraft:generic.armor",
"operation": "add_value",
"amount_per_level": 0.5
}
],
"indicators": {
"on_level_up": {
"chat_message": "&e[System] &aYour Grandmaster Artificer proficiency has ascended to level {level}!",
"sound": "minecraft:block.anvil.use",
"particles": "minecraft:flame",
"particle_count": 50
}
}
}Action (config/proficiency/actions/smelt_ancient_debris.json):
{
"action_type": "smelted",
"target_proficiency": "artificer",
"flat_xp_reward": 500.0,
"event_value_multiplier": 150.0,
"conditions": {
"event_item": ["minecraft:netherite_scrap", "minecraft:gold_nugget"]
}
}This proficiency turns the player into a ghost, scaling their movement speed endlessly. It triggers periodically whenever the player is sneaking, but explicitly requires the player's hands to be completely empty. The experience gained is a fractional calculation based exactly on the distance (in blocks) traversed while in the sneak state.
Proficiency (config/proficiency/proficiencies/phantom.json):
{
"name": "Phantom Footstep",
"max_level": 200,
"starting_level": 1,
"xp_curve": [
{ "up_to_level": 200, "base_xp": 100.0, "xp_multiplier": 10.0 }
],
"attribute_modifiers": [
{
"attribute": "minecraft:generic.movement_speed",
"operation": "add_multiplied_base",
"amount_per_level": 0.005
},
{
"attribute": "minecraft:generic.step_height",
"operation": "add_value",
"amount_per_level": 0.05
}
]
}Action (config/proficiency/actions/unarmed_stealth.json):
{
"action_type": "sneak",
"target_proficiency": "phantom",
"flat_xp_reward": 0.0,
"event_value_multiplier": 0.25,
"conditions": {
"main_hand": "minecraft:air",
"off_hand": "minecraft:air"
}
}