EmakiLevel

EmakiLevel is the Emaki Series level and multi-experience-type plugin. It stores long-term player progression separately from vanilla experience and can manage multiple level tracks such as main, combat, mining, fishing, crafting, brewing, smelting, and taming.

It integrates level types, experience sources, requirements, rewards, attribute contributions, PlaceholderAPI, CoreLib actions, and MythicMobs drops into one runtime plugin.

Module facts

Item	Value
Module version	1.4.0
Runtime plugin jar	EmakiLevel-1.4.0.jar
Developer API jar	emaki-level-api-1.4.0.jar
Main class	emaki.jiuwu.craft.level.EmakiLevelPlugin
Main command	/emakilevel
Aliases	/elv, /elevel
Hard dependency	EmakiCoreLib
Soft dependencies	MythicMobs, EmakiAttribute, EmakiCooking, EmakiForge, PlaceholderAPI
Main permissions	emakilevel.use (default true), emakilevel.levelup (true), emakilevel.top (true), emakilevel.reload (op), emakilevel.debug (op), emakilevel.admin (op)
Data storage	plugins/EmakiLevel/data/<uuid>.yml
Java / platform	Java 25 project baseline, api-version: 1.21.8, folia-supported: true

Installation

Install only runtime plugin jars on the server:

plugins/
├─ EmakiCoreLib-*.jar
└─ EmakiLevel-1.4.0.jar

Do not put emaki-level-api-*.jar into the server plugins/ directory. The API jar is only for third-party developers as a Maven provided or Gradle compileOnly dependency. The runtime plugin jar shades its own API.

Optional plugins enable additional features:

Optional plugin	Enabled capability
PlaceholderAPI	Registers %emakilevel_*% placeholders.
MythicMobs	Enables MythicMob kill sources and emakilevel_exp / elv_exp intangible drops.
EmakiAttribute	Converts attributes.values from level types into attribute contributions.
EmakiCooking / EmakiForge	Can grant level experience through CoreLib actions from recipes or processes.

Features

• Multiple level types: each types/*.yml file defines one level type. Defaults include main, combat, mining, fishing, crafting, brewing, smelting, and taming.
• Per-player YAML data: one file per player storing level, exp, total_exp, and update time for every level type.
• Layered requirements: required experience resolves from type overrides, then requirement groups, then global defaults. Exact values and formulas are both supported.
• Automatic and manual level-up: each type can control auto-upgrade, manual /elv levelup, economy costs, material costs, item rewards, and action phases.
• Experience listeners: vanilla kills, MythicMobs kills, block breaking, mature crop harvest, fishing, crafting, brewing, furnace extraction, and taming.
• Anti-abuse helpers: tracks player-placed blocks and recent damagers.
• CoreLib actions: other Emaki plugins, scripts, or third-party integrations can add/remove exp or levels.
• PDC sync: online players receive PDC values for level, exp, total exp, required exp, and progress.
• Attribute bridge: when EmakiAttribute is installed, level formulas can contribute attributes.

Runtime folder

On first startup, default resources are released by the CoreLib Bootstrap flow:

plugins/EmakiLevel/
├─ config.yml
├─ requirements.yml
├─ types/
│  ├─ main.yml
│  ├─ combat.yml
│  ├─ mining.yml
│  └─ ...
├─ sources/
│  ├─ combat.yml
│  ├─ block_actions.yml
│  ├─ mythicmobs.yml
│  └─ ...
├─ gui/
│  ├─ level_gui.yml
│  └─ top_gui.yml
├─ lang/
│  ├─ zh_CN.yml
│  └─ en_US.yml
└─ data/
   └─ <uuid>.yml

config.yml > release_default_data: true controls whether missing bundled data files such as requirements.yml, types/, sources/, and gui/ should be released. Customized existing files are not overwritten by normal restarts.

Default level types

Type ID	Purpose	Max level	Requirement group	Default upgrade mode	Default attributes
main	Main progression	100	main	auto + manual	attribute_power = %level% * 0.5
combat	Vanilla and MythicMobs combat	80	combat	auto + manual	physical_attack, physical_crit_rate
mining	Mining	60	mining	manual, auto disabled by default	mining_power = %level% * 0.2
logging	Log chopping	60	logging	auto + manual	disabled
gathering	Plant gathering	60	gathering	auto + manual	disabled
farming	Mature crop harvest	60	farming	auto + manual	disabled
fishing	Fishing	60	fishing	auto + manual	disabled
taming	Entity taming	60	taming	auto + manual	disabled
crafting	Crafting	60	crafting	auto + manual	disabled
brewing	Brewing stand completion	60	brewing	auto + manual	disabled
smelting	Furnace extraction	60	smelting	auto + manual	disabled
cooking	Reserved for cooking gameplay	60	cooking	auto + manual	disabled
forging	Reserved for forging gameplay	60	forging	auto + manual	disabled

Default types are templates. You may add, remove, disable, or rename types/*.yml entries, but commands, placeholders, source rules, and actions must reference the same type ID.

Basic workflow

1. Install and start EmakiCoreLib and EmakiLevel.
2. Review plugins/EmakiLevel/types/ and keep only the level types you need.
3. Configure requirement curves in requirements.yml.
4. Configure experience sources in sources/*.yml.
5. If manual level-up should cost money or materials, edit types/<type>.yml > upgrade.cost.
6. If EmakiAttribute is installed, configure types/<type>.yml > attributes.values.
7. Run /elv reload.
8. Verify with /elv info, /elv debug requirement <type> <level>, and PlaceholderAPI.

Player data overview

schema_version: 1
uuid: "00000000-0000-0000-0000-000000000000"
name: "PlayerName"
levels:
  main:
    level: 1
    exp: 0.0
    total_exp: 0.0
    updated_at: 1730000000000

Level-up flow:

1. Resolve the level type and ensure it is enabled.
2. Add current-level exp and total_exp.
3. Execute upgrade.actions.gain.
4. If auto-upgrade is allowed, try level-ups up to level.max_auto_upgrade_steps.
5. Check requirement exp, max level, manual/auto switches, money costs, and material costs.
6. On success, consume requirement exp, increase level, grant rewards, and execute upgrade.actions.success.
7. On failure, execute upgrade.actions.failure with failure_reason.
8. Sync PDC and refresh EmakiAttribute contributions when available.

Documentation pages

• Commands: player/admin commands, permissions, and examples.
• Placeholders: all %emakilevel_*% placeholders and leaderboard placeholders.
• Configuration: main config, level types, requirements, costs, rewards, PDC, and attributes.
• Experience Sources: sources/*.yml triggers, match fields, formula variables, and anti-abuse behavior.
• MythicMobs Integration: MythicMob kill exp and custom drops.
• CoreLib Actions: actions EmakiLevel registers in the CoreLib action registry.
• API: developer API, CoreLib actions, static facade, and provider helper usage.
• Events: Bukkit events in emaki.jiuwu.craft.level.api.event and their cancellability.
• JavaScript: the emaki.module("level") facade, exp rules, and level-up hooks.