EmakiLevel | Parallel Progression Lines

Added

- extensions().registerExpSource(Plugin, ExpSourceProvider), so a third-party plugin can grant exp of its own by returning ExpSourceGrant at these gameplay triggers: entity_kill, mythic_mob_kill, block_place, block_break, crop_harvest, craft_item, furnace_extract, player_fish, entity_tame and brew_complete. Providers are keyed by owner and provider id, dropped automatically when the owner is disabled, and the returned ExpSourceRegistration handle can be closed more than once. - Cancellable PlayerPreLevelUpEvent, fired after every check passes and before charging or writing begins. Cancelling prevents the level-up with nothing charged, no level change, no rewards and no actions, and the runtime reports event_cancelled. It is the only supported way to veto an upgrade. It fires only for an online, thread-owned player and not when an earlier check already failed, so treat a missing event as "no committed upgrade to veto" and listen to PlayerLevelUpEvent to confirm a completed upgrade. - Leaderboard queries catalog().top(typeId, limit) and catalog().topCount(typeId), exp adjustment preview catalog().previewAdjustment(), and operations().syncPlayer(), operations().openGui() and operations().openTopGui(). - Config precheck lines are coloured by severity: red for fatal and error, yellow for warning, the original grey for info.

Changed

- Actions use a new syntax, and most of it is rewritten for you. On first startup CoreLib rewrites the config files of every Emaki plugin under plugins/, once only. Each edited file keeps the original beside it with a .legacy-backup suffix. A line that cannot be converted leaves your config untouched and goes into a separate .v2-failed file, with the file and line listed in the console. Common actions such as sendmessage in types/*.yml and @chance=5 sendactionbar in sources/*.yml are covered. - Level's own eight actions need renaming by hand; automatic rewriting does not cover them, and the rewriter does not even recognise the old names, so they stay in your config untouched and the console reports an unknown line on load: - emakileveladdexp → level_add_exp - emakilevelsetexp → level_set_exp - emakilevelremoveexp → level_remove_exp - emakileveladdlevel → level_add_level - emakilevelsetlevel → level_set_level - emakilevelremovelevel → level_remove_level - emakilevelreset → level_reset - emakilevellevelup → level_up - The target=playerName argument on those eight actions is replaced by a source segment in front of the action: emakileveladdexp type=main amount=10 target=Steve becomes player_by_name Steve | level_add_exp type=main amount=10. With no source segment the action applies to the player who triggered it, as leaving target empty used to. - auto_upgrade and silent are only accepted by level_add_exp. On any other level action they are treated as an unknown argument. - Placeholders reading level data inside action lines need a var. prefix. This only concerns you if you have edited your level types or exp sources: the bundled types/ and sources/ files already use the new form. If your own config writes %old_level%, %new_level%, %amount% or %failure_reason% under actions.success, actions.failure or actions.gain, change them to %var.old_level%, %var.new_level%, %var.amount% and %var.failure_reason%, or messages will show %new_level% instead of the number. The full list available in action lines is type, type_display_name, level, old_level, new_level, exp, old_exp, new_exp, total_exp, required_exp, progress, progress_percent, amount, reason and failure_reason. - Placeholders in formulas are unchanged and must stay bare. Only action lines, the ones under actions:, take the prefix. %result_amount% and %mythic_level% in exp_formula, and %level% in the attributes formulas, go through a separate arithmetic path; prefixing them stops them evaluating. PlaceholderAPI %emakilevel_...% placeholders are unaffected. - For developers: EmakiLevelApiProvider is removed; call the static methods on EmakiLevelApi directly. The static methods that used to sit on the facade (available(), type(), types(), getPlayerData(), getLevel(), getExp(), getTotalExp(), getRequiredExp(), addExp()/removeExp()/setExp(), addLevel()/removeLevel()/setLevel(), levelUp() and the matching *Async() variants) are replaced by status(), catalog(), operations() and extensions(). available() becomes status(), returning ApiStatus with usable(), ready() and the version and plugin-name fields, where ready() means the data is loaded rather than the components exist. Apart from catalog().types() and catalog().type(), these methods return EmakiResult<T> and report unavailability instead of throwing. EmakiLevelApi.Bridge is now @ApiStatus.NonExtendable. - For developers: a cancelled PlayerExpGainEvent now reports event_cancelled instead of invalid_amount. The event classes document their threading: all are synchronous, fire only while the runtime owns the player, and listeners must return quickly without blocking on other threads.

Fixed

- The daily exp cap being charged even when another plugin blocked the gain, on servers running a plugin that listens to level events. The gain was counted towards the daily total before other plugins were notified, so a cancelled or reduced gain had already been counted and players saw their allowance shrink without receiving exp. Counting now happens after the other plugins have had their say, using only the amount that lands. - Compensation records being lost as a batch when a level-up went wrong midway. One corrupt pending record made the plugin abandon the whole batch, leaving every waiting player without a refund. A corrupt record is now moved aside into data/operation-journal/quarantine/ and the rest recover as usual, with the pending operations listed in the console. - Writing that pending record stalling players and breaking the level-up. The write happened on the player's own thread, so a slow disk slowed level-ups and a failed write aborted the level-up. It now happens in the background, and a failed write only logs and leaves the record for the next recovery pass. - Some players' level data not refreshing after /emakilevel reload, on Folia servers. The rewrite ran entirely on the command thread, so players not owned by that thread were skipped with an error. They are now handed back to their own thread.

Removed

- JS experience rules and level-up hooks, with no automatic conversion. Scripts adjusting exp through level.registerExpRule or hooking level-ups through level.onLevelUp no longer run. Use multipliers in config.yml for rates and actions.success on the level type for level-up effects. The bundled scripts/examples/level_exp_rule.js and scripts/examples/level_status.js samples are gone as well. - Seven config options that never did anything: storage.type, storage.save_on_quit, storage.save_on_shutdown, pdc.sync_on_join, pdc.sync_on_exp_change, pdc.sync_on_level_change and pdc.sync_on_reload. They sat in the config file but were never read, so no value ever had an effect. Delete them from your own config whenever you like. pdc.enabled and pdc.namespace are unchanged.

Notes

- Update EmakiCoreLib to 4.7.0 first. - Back up your whole plugins/EmakiLevel/ folder before upgrading. - Three things need doing by hand: renaming the eight level actions, replacing target with a player_by_name source segment, and dropping auto_upgrade and silent from anything other than level_add_exp. Everything else in the action syntax is rewritten for you. If you have edited your level types or exp sources, also check that the placeholders in your action lines carry the var. prefix; the ones in formulas stay as the

Added

- Asynchronous mutation entry points for exp and level changes in the public API, each returning a future with an operation result and reporting unavailability cleanly when the API is not installed. - Transactional level-up cost charging: if currency or material deduction partially fails, the already-deducted part is rolled back, with a dedicated failure reason for compensation failure. - Player data readiness protection: a new failure reason and message reject writes while data is loading or read-only, instead of writing corrupt data. - New placeholders exposed through the CoreLib placeholder system: level, exp, total/totalexp/total_exp, required/requiredexp/required_exp, progress, progresspercent/progress_percent. - Config precheck messages at file and directory level: missing required file, path not a file, unreadable file, missing required directory, path not a directory, unreadable directory.

Changed

- Descriptor migrated to paper-plugin.yml with structured dependencies (EmakiCoreLib required; MythicMobs / EmakiAttribute / EmakiCooking / EmakiForge / PlaceholderAPI optional). Permission keys and defaults are unchanged; /emakilevel (aliases elv, elevel) registers in code with aliases preserved. - Default GUI files (gui/level_gui.yml, gui/top_gui.yml) use the nested item.source + item.components form. Slot layout and all placeholders are unchanged and the old form is still parsed. - Leaderboard rebuilds are now asynchronous, so player join/quit no longer triggers a full main-thread table scan. - Player data loading moved to a generation-aware asynchronous session model. - Message prefix switched to a new brand gradient. - api-version raised from 1.21 to 1.21.8 and the build base moved from spigot-api to paper-api; folia-supported: true and the Java 25 target are unchanged.

Fixed

- Level-up cost charging could consume resources without granting the level: currency and material deductions were applied without checking their results and without rollback, so a player could lose currency when materials were insufficient, or the reverse. Charging is now transactional with rollback.

Removed

- PlaceholderAPI placeholder resolution is now cache-only. An uncached player's placeholder previously loaded synchronously and returned a value; it now returns an empty string. Online players are cached on join, but any display that relies on placeholders for offline or not-yet-cached players must be re-checked. - The browser-based Web Console layer, including web-console.yml, the config and CSS web extensions, and the web-console/ frontend project with its level curve preview. - The internal level curve preview service is removed with it. It only served that browser preview and had no config key or command, so there is no equivalent owner-facing loss; curves are still driven by level type configuration.

Notes

- Requires EmakiCoreLib 4.6.0. - config.yml has no key additions or removals, so existing config works as-is, and the player level data file structure is unchanged, so no migration is required. After upgrading, re-check any placeholder-driven display, especially for offline players, and confirm you have a replacement for anything previously done through the Web Console.

Added

- Level exp sources now use CoreLib's shared gameplay-event channel. - Native CoreLib Level placeholders for other plugin condition expressions. - Improved Level action-chain integration. - Manifest v2 Web Console integration. - Command suggestions after /emakilevel or /elv .

Improved

- Reduced duplicated source listener logic through a unified subscriber. - Improved level messages and Web curve preview styling. - Aligned with the Paper API / paper-plugin.yml 1.21.8+ baseline.

Notes

- Update with the matching CoreLib release. - Breaking: Action aliases were removed; use canonical action IDs. - If other plugins use Level placeholders, ensure EmakiLevel is enabled and the referenced level type exists.

Added

- Experience multipliers (global / per type / per source), defaulting to 1.0. - Per-type daily experience caps (unlimited by default; in-memory, reset on restart). - Public Bukkit events: PlayerExpGainEvent, PlayerLevelUpEvent, PlayerLevelChangeEvent, PlayerMaxLevelReachedEvent. - Completed public EmakiLevelApi. - JavaScript extensions for experience rules and level-up hooks via emaki.module("level"). - Config precheck on startup and reload.

Fixed

- Fixed level panel and ranking GUI titles showing raw page placeholders on first open.

Improved

- Better default level types, sources, grouping, and language content.

Notes

- Multipliers and daily caps default to no change; enable as needed. - Daily cap counters are in-memory only and reset on restart.

Added

- Level panel and ranking views. - Web Console level curve previews. - Clearer default level types, experience sources, and group resources.

Fixed

- Fixed unclear default requirement group naming. - Fixed unclear experience source, anti-abuse, and progression rule wording. - Fixed unclear cross-plugin growth source descriptions.

Refactored

- Default level type and experience source resources. - Requirement group naming. - Curve and ranking preview data.

Improved

- Better experience source configuration and type definitions. - Better level panel, ranking display, and default language content. - Better Web Console level editing with curve previews.

Notes

- Review custom level types, sources, requirement groups, and curves after updating. - Back up level-related data before production updates.