Meritum Engine — Changelog v1.1 → v1.2

Target version: Minecraft 1.26.30+ | Script API 2.7.0 (was 1.21.100 / API 2.1.0 on v1.1)

🏗️ Project structure

• Full script reorganization: engine.js, command.js, and utils.js were moved into a core/ folder, signaling they're the "core" and shouldn't be touched.
• main.js got slimmed down (92 → 53 lines): it now only handles the external registration listener (meritum_engine:register_achievement).
• New achievements.js: the internal example achievements (first_join, play_1_hour, play_5_hours, play_10_hours) were moved out of main.js into this file — meant to be the one file devs should edit, without touching the core.
• New ui.js: all menu/interface logic (previously inside engine.js) was extracted here, including the new Settings screen.
• manifest.json (Beh and Res): version 1.1.0 → 1.2.0, min_engine_version 1.21.100 → 1.26.30, Script API 2.1.0 → 2.7.0, and the CurseForge URL was added to the Beh Pack manifest.

⚙️ Engine changes (engine.js, 435 → 825 lines)

Category indexing (performance)

• New indexAchievement / unindexAchievement: each achievement is now indexed by category (eventual, mining, etc.) in a Set, so detection loops only iterate the achievements relevant to that category — previously the loop went through every registered achievement on every tick/event, even ones from other categories.
• New unregisterAchievement(id, options).

New achievement categories

• Interaction (interacting with a block or entity) — didn't exist in v1.1.
• Breeding (offspring born from bred parents, with playerRadius to credit nearby players) — also new.

logic system ("and"/"or")

• v1.1 had no such concept — each category was checked independently and unlocked on its own.
• v1.2 introduces logic: "and" | "or" to control whether all of an achievement's categories must be satisfied, or just one.

Mining / Combat / Interaction — durability

• v1.1: durability comparison was exact-match only (currentDurability != target.itemStack.durability → a bug, practically never matched).
• v1.2: supports a range ({ min, max }) or a comparison with operator ({ value, operator }, <, <=, >, >=, ==, !=).
• Mining and Interaction also gained the exception field (a list of substrings to exclude variants, e.g. ignoring stripped_ logs).

Combat — more granularity

• New fields: projectile and projectileSource (enables achievements like "kill the ghast with its own reflected fireball").
• origin is more robust now: if omitted, it credits the attacker and falls back to the victim (e.g. fall damage with no clear attacker).

Obtaining — reworked

• item now accepts a list of { id, min } entries (with id itself able to be an array of alternatives) — simpler before.
• armor gained logic: "and"/"or" per slot.
• New accumulate: instead of checking a minimum count, it permanently tracks which items in the list the player has ever held (even briefly), for achievements like "collect every type of ore."
• Checks now run against an incremental inventory cache (updated via change events instead of a full rescan on every check) — another performance improvement that didn't exist in v1.1.

Eventual — the category that grew the most

In v1.1, eventual only supported beforeTime, dimension, and nextEntity. v1.2 adds:

• layer (Y-height range)
• weather (reserved, but disabled — depends on the beta API dimension.getWeather())
• biome (as a filter, or as a tracking flag when combined with accumulate)
• riding (any mount, or a specific one)
• timeOfDay
• effects (multiple simultaneous potion effects)
• volume (fixed cuboid region)
• nextBlock (nearby block within a radius, for POIs with no fixed location)
• distanceTraveled (cumulative odometer-style distance, persisted across sessions)
• accumulate (persistent "collect every X" set, with a built-in universe: all_biomes, overworld_biomes, nether_biomes, end_biomes, or a custom array, and require: "all" or a specific number)

Storage and flushing

• New dedicated flushPlayer and getAchievementCollectionProgress (progress like "5/64 biomes visited," meant for UI/commands).
• Brand-new distance-traveled cache (clearDistanceStateForPlayer, loadDistanceState, trackDistanceTraveled).

🧰 utils.js (105 → 561 lines)

Almost all of the content is new:

• Per-slot inventory cache (readSlotData, getOrCreateSlotCache, rescanInventory, ensureInitialized, updateInventorySlot, clearInventoryCache, getInventorySlotData) — backs the new incremental Obtaining system.
• Per-player UID system (generateUUID, createUID, getUID, setUID, playerFromUID, cachePlayerUID, ensureUID) — persistence across sessions for data like distance traveled.
• matchAdaptiveNumber (reusable min/max/operator comparisons) and matchBiome.
• formatNameId now accepts a second nameSpaces parameter (namespace-prefix-to-lang-key mapping) — tied to the new nameSpaces block in config.js.
• The entire accumulate system (resolveUniverse, clearAccumulateCache, loadAccumulateSet, saveAccumulateSet, recordAccumulateAndGetProgress, recordAccumulate, evaluateCollectionProgress, getCollectionProgress).

🖥️ Interface (ui.js — new file, extracted from engine.js)

• New per-player Settings screen: sort by default/rarity/status/name, reverse order, and show-only-unlocked toggle.
• Preferences are kept per player in memory (reset on leave/game close — a deliberate design choice, not a bug).
• Rarity sort weight (rarityWeight) is automatically derived from the key order in config.rarity, so it doesn't need manual updates when a new rarity tier is added.

🕹️ command.js

• The showAchievements import moved from engine.js to ../ui.js (reflects the UI extraction).
• All .replace(...) calls became .replaceAll(...) — fixes placeholders that appeared more than once in the same string and weren't all being substituted.
• Fixed a bug in /achsearch: a reference to Text.errors.listSearch (the Text variable didn't exist) → TextCMD.errors.listSearch.
• Fixed /achgive: it used TextCMD.success.give, which didn't exist in v1.1's config.js (the command had neither the config entry nor the lang key for its success message) — now it exists (success.give in config + MeritumEngine.cmd.success.give in lang).

🔧 config.js

• New nameSpaces block (item-prefix-to-lang-key mapping, including eternitys_reforged:, more:, theUltimate:).
• New colors block (color code aliases: bold, reset, italic, gray, gold, red, white, yellow).
• New textUiSettings block for the Settings screen (title, sort labels, etc.), with a sortOptions getter that derives the dropdown list directly from sortLabels.
• Added success.give to textCmd (missing in v1.1).
• Added settings to textUi.

🌍 Localization — key cleanup

• Removed the custom key MeritumEngine.message.achievements ("Achievement Unlocked:" message) — replaced with the vanilla key %achievement.get.
• Added new keys for the Settings screen (MeritumEngine.ui.settings.* — sortBy, reverseOrder, onlyUnlocked, and the 4 sort labels) across all 10 of the addon's languages.
• Added MeritumEngine.cmd.success.give across all languages.

🎁 Example achievements (achievements.js)

• MeritumEngine.first_join: the welcome reward (5x oak_log) was removed — the achievement now grants no reward at all (rewards: {}).
• The other three (play_1_hour, play_5_hours, play_10_hours) remain unchanged.

📋 Quick summary