Commands and Permissions

Every EmakiLevel command, the permission each one needs, and the common failure reasons are listed below

Main command: /emakilevel; aliases: /elv, /elevel. Examples below use /elv

Remember one rule first: every subcommand checks emakilevel.use. Administrative commands therefore require both emakilevel.use and their specific admin permission

Player commands

Command	Permission	Description
/elv	emakilevel.use	View all loaded level types for yourself. Player-only
/elv info [type]	emakilevel.use	View one level type. Without type, behaves like /elv
/elv gui [type]	emakilevel.use	Open the level GUI. Without type, uses config.yml > primary_type. Alias: /elv open [type]
/elv levelup [type]	emakilevel.levelup	Manually level up one type. Without type, uses config.yml > primary_type, default main. Alias: /elv up [type]
/elv top [type]	emakilevel.top	View top 10 cached leaderboard entries for one type. Without type, uses the primary type
/elv topgui [type]	emakilevel.top	Open the leaderboard GUI. Without type, uses the primary type. Alias: /elv topopen [type]. Player-only

Examples:

/elv
/elv info combat
/elv gui main
/elv levelup mining
/elv up main
/elv top combat
/elv topgui combat

Manual level-up is controlled by types/<type>.yml:

upgrade:
  enabled: true
  manual_upgrade: true
  cost:
    enabled: false

If a type should only level up automatically from exp gain, keep auto_upgrade: true and set manual_upgrade: false

Admin commands

These commands require emakilevel.admin. Command targets must be online because the command implementation resolves exact online player names

Command	Permission	Description
/elv giveexp <player> <type> <amount>	emakilevel.admin	Add exp to an online player. Alias: addexp. Auto-upgrade follows the type config
/elv takeexp <player> <type> <amount>	emakilevel.admin	Remove current-level exp down to 0. Does not downgrade. Alias: removeexp
/elv setexp <player> <type> <amount>	emakilevel.admin	Set current-level exp. Does not directly change level
/elv addlevel <player> <type> <amount>	emakilevel.admin	Add levels, clamped between start_level and max_level. Alias: givelevel
/elv takelevel <player> <type> <amount>	emakilevel.admin	Remove levels, not below start_level. Alias: removelevel
/elv setlevel <player> <type> <level>	emakilevel.admin	Set level, clamped to the type range
/elv reset <player> <type>	emakilevel.admin	Reset the type: level back to start_level, exp and total_exp to zero

Examples:

/elv giveexp Steve combat 250
/elv takeexp Steve mining 30
/elv setexp Steve main 0
/elv addlevel Steve main 5
/elv takelevel Steve combat 1
/elv setlevel Steve fishing 20
/elv reset Steve mining

Operation differences:

Operation	Changes level	Changes current exp	Changes total exp	Notes
giveexp	possibly	increases, then consumes requirement exp on level-up	increases	Auto-upgrade depends on type config
takeexp	no	decreases to minimum 0	unchanged	Does not downgrade
setexp	no	sets to value	unchanged	Useful for correcting current-level exp
addlevel	yes	resets to 0	unchanged	Direct admin edit, no level-up rewards
takelevel	yes	resets to 0	unchanged	Direct admin edit, no reward rollback
setlevel	yes	resets to 0	unchanged	Direct admin edit
reset	yes	resets to 0	resets to 0	Returns to the type's initial state

Reload and debug commands

Command	Permission	Description
/elv reload	emakilevel.reload or emakilevel.admin	Save cached data, reload config, types, requirements, sources, language, PDC, and the attribute bridge, then sync online players
/elv convert-legacy [confirm]	emakilevel.admin	Rename the legacy result_item_sources key under sources/*.yml (sources.<id>.rules[]) to item_sources. Without an argument it only previews; confirm (or --apply) rewrites the files and leaves a .bak backup
/elv debug requirement <type> <level>	emakilevel.debug or emakilevel.admin	Show required exp and the source used for a target level
/elv debug pdc <player>	emakilevel.debug or emakilevel.admin	Resync online player PDC. The implementation resyncs every online player
/elv debug	emakilevel.debug or emakilevel.admin	Print the CoreLib debug status overview
/elv debug status / on / off	emakilevel.debug or emakilevel.admin	Shared CoreLib debug switches: show status, enable all, disable all
/elv debug player <player>	emakilevel.debug or emakilevel.admin	Toggle debug output for one online player
/elv debug module <module>	emakilevel.debug or emakilevel.admin	Toggle a debug submodule. EmakiLevel contributes common; the shared CoreLib submodules action, item_operation, variables, placeholder, gui, and chat_input are also available

Examples:

/elv reload
/elv debug requirement main 10
/elv debug requirement combat 35
/elv debug pdc Steve
/elv debug module common

debug requirement source values:

Source	Meaning
type.values	Exact target-level value in types/<type>.yml > requirement.values
type.formula	Type-specific formula in types/<type>.yml > requirement.formula
groups.<group>.values	Exact value in requirements.yml > groups.<group>.values
groups.<group>.formula	Formula in requirements.yml > groups.<group>.formula
global.values	Exact value in requirements.yml > global.values
global.formula	Formula in requirements.yml > global.formula

Permissions

Permission	Default	Scope
emakilevel.use	true	Main command and basic queries; also the registration permission of the root command. Checked before every subcommand
emakilevel.levelup	true	/elv levelup / /elv up
emakilevel.top	true	/elv top and /elv topgui / /elv topopen
emakilevel.reload	op	/elv reload
emakilevel.debug	op	/elv debug requirement and /elv debug pdc
emakilevel.admin	op	Exp/level management commands; also accepted for reload/debug

LuckPerms examples:

/lp group default permission set emakilevel.use true
/lp group default permission set emakilevel.levelup true
/lp group default permission set emakilevel.top true
/lp group admin permission set emakilevel.admin true
/lp group admin permission set emakilevel.reload true
/lp group admin permission set emakilevel.debug true

Common failure reasons

Match your error against this table first:

Reason ID	Common case
player_not_found	Target player is offline/not found, or an API call lacks a valid UUID
player_data_unavailable	Player level data is not loaded yet, or was already unloaded
type_not_found	The type does not exist
type_disabled	The type exists but enabled: false
invalid_amount	Amount is invalid
daily_cap_reached	The type's daily exp budget is exhausted; see config.yml > daily_caps
event_cancelled	A listener cancelled PlayerExpGainEvent or PlayerPreLevelUpEvent, so the gain/level-up was abandoned
upgrade_disabled	upgrade.enabled: false
manual_upgrade_disabled	Player tried /elv levelup, but manual upgrade is disabled
max_level	Already at max_level
not_enough_exp	Current-level exp is insufficient
not_enough_money	Economy cost is not affordable
not_enough_material	Material cost is not available
cost_compensation_failed	An upgrade cost was consumed, a later step failed, and refunding the cost also failed
invalid_requirement	Requirement formula/config resolves to 0 or less

Asynchronous public-API writes may additionally return api_unavailable, not_entity_owner, player_offline, owner_schedule_retired, and owner_schedule_rejected. These come from thread-ownership scheduling, not from configuration