
EmakiCoreLib | Shared Runtime for the Emaki Series
One pipeline syntax, one item-source identity and one pre-check for every Emaki module.
Список изменений
Added
- Vanilla dialog support, built on the server's own dialog capability, so a plugin can show a screen with explanatory text, input fields and buttons. Needs a client on 1.21.6+; older clients are unverified. New
dialogblock:dialog.enabled(defaulttrue) is the master switch,dialog.directory(defaultdialogs) is the definition folder relative toplugins/EmakiCoreLib/, and every.ymlin it is loaded. - A heavily commented sample definition inside the plugin jar,
dialogs/example_notice.yml, covering the three types (noticeone button,confirmationyes/no,multi_actionseveral), body text and inputs, the four button actions (none,command_template,run_command,open_url), and thecan_close_with_escape,pauseandafter_actionswitches. The sample is not written out to your data folder: create your own.ymlfiles in the folder named bydialog.directory(defaultplugins/EmakiCoreLib/dialogs/) and use the one in the jar as a reference. A definition missing a required inputkeyor its buttons is reported and skipped at load time. Plugins can also embed dialogs in their own config files, parsed the same way. - New
displayblock, the shared layer behind floating text and displayed items, used by damage indicators, cooking station text and item displays.display.backend(defaultauto):bukkitspawns real entities visible to everyone nearby with no extra plugin,packetsends virtual entities that stay out of the world save, use no server entities and can be shown to specific players only (needs PacketEvents on 1.19.4+),autouses packets when PacketEvents is present,inheritfollowsgui.backend. An unavailable packet backend always falls back tobukkit.display.view_distance_blocks(default48) anddisplay.refresh_interval_ticks(default20) apply to the packet backend only. - New
gui.click_interval_ms(default100ms), a minimum interval between menu clicks that stops autoclickers and macros from settling the same click twice. Normal clicking never trips it, a blocked click is dropped safely so the menu stays consistent and the player sees no message, and0disables it. Above500is not recommended. Both menu backends honour it. - New
minimessage.default_no_italic(defaulttrue). Vanilla italicises item names and lore, so with this on every Emaki text (menu item names and lore, menu titles, chat messages, dialogs) renders upright unless italics are written out. It is a default, not a lock:<i>and<italic>still work. - New
vanilla_languageblock for server-side vanilla item and block names, needed by anything that localises them server-side such as searching storage by name.vanilla_language.enableddefaults tofalse; turning it on downloads the language file from Mojang's official asset index once, caches it inplugins/EmakiCoreLib/lang-cache/and never goes online again. A failed download does not stop the server.vanilla_language.locale(defaultzh_cn) matches the client language file names. - New
action.pipelineblock, all three limits checked at config load time, with an over-limit config rejected in favour of the last working one rather than quietly lowered:action.pipeline.max_repeat_times(default100) capsevery <interval> times <count>and thetimesargument ofstart_task,action.pipeline.max_sequence_depth(default8) caps nestedruncalls, andaction.pipeline.max_branch_depth(default16) caps nestedif ... [ ... ]. - Item lore can expand across multiple lines: a line holding nothing but one placeholder whose value is a list becomes several lines. Applies to
minecraft:loreonly. - Readable diagnostics for a broken action line, pointing at line and column, naming what is missing and which values are accepted, and reporting how many more problems remain on the same line. Bare internal key names are no longer printed.
Changed
- Every Emaki plugin uses a new action syntax, and you do not have to rewrite anything yourself. Near the end of startup CoreLib rewrites the
.ymlconfigs in everyplugins/folder whose name starts withEmaki, once only, then drops a hidden.action-v2-migratedmarker inplugins/EmakiCoreLib/. Each edited file keeps the original beside it with a.legacy-backupsuffix, written once and never overwritten. Conversion only touches Emaki's own folders and skipslang/directories. - Every converted line is compiled before installation. Lines that pass are rewritten, lines that do not are left exactly as they were, and the console lists the file, line and reason for each. If no line in a file passes, the original is untouched and the result goes into a separate
.v2-failedfile. While any line is rejected or any file could not be read or written, the marker is withheld so the next update retries. The console prints a report of files and lines changed plus every skip and failure; a server already fully converted prints no summary. - Syntax changes, using CoreLib's own
action.templatessample:# old - 'sendmessage text="<green>got %result_item_name%</green>"' - '@delay=10t playsound sound=minecraft:entity.experience_orb.pickup volume=0.8 pitch=1.2' # new - 'self | send_message text="<green>got %var.result_item_name%</green>"' - 'self | after 10t | play_sound sound=minecraft:entity.experience_orb.pickup volume=0.8 pitch=1.2'- Action names gained underscores:
sendmessage→send_message,playsound→play_sound,spawnparticle→spawn_particle,givepotioneffect→give_potion_effect,runcommandasconsole→run_command_as_console. - Each line starts with a segment naming who it acts on:
self,inherited,looking_at,nearby,trigger. Omitted meansself. One per line, and it must come first. Segments are separated by|and run left to right. Akeepsegment hands the selected targets to a later phase, which reads them back withinherited. - Old line prefixes became segments:
@delay=10t→after 10t |,@chance=0.3→chance 0.3 |,@if='cond'→where cond |.@ignore_failureis gone and unnecessary, since continuing past a failed segment is the default. - Real branches use
if <condition> [ ... ], optionally withelse [ ... ]. Automatic conversion never emits brackets: it turns@ifintowhere, because the old syntax had no else arm. - Durations carry a unit suffix, so
ticks=200→duration=200t. Units aret,sandms; a bare number counts as ticks. - Placeholders were renamed:
%player%and%player_name%→%caster.name%,%player_uuid%→%caster.uuid%,%player_world%→%caster.world%,%player_x%%player_y%%player_z%→%caster.x%%caster.y%%caster.z%,%target_name%→%target.name%,%target_uuid%→%target.uuid%,%has_target%→%target.present%. - Your own variables are written
%var.name%; a bare%name%is rejected at load time with a message saying what to write. Aset name=valuesegment writes variables mid-pipeline, and theexpressionfield of a variable definition is nowvalue. - Calling a named sequence changed from
@template=nametorun name key=value.
- Action names gained underscores:
- Four old actions need editing by hand; the converter recognises them and says so in the console:
loopsyncandloopasync→start_task,cancelloop→stop_task,usetemplate→run <sequence>. Loop parameters changed too:mode=replace→on_conflict=replace,stop_if_offline→stop_when_offline.start_taskalso acceptsstop_when_dead,stop_when,stop_on_failure,initial_delayandkey. - What used to be
action.loop.templatesare now named sequences, called withrun nameand optionalkey=valuearguments. A sequence line that does not compile is named in the console, that sequence is unavailable and the rest still work. /corelib action runtakes a whole pipeline line instead ofrun <actionId> key=value ..., for example/corelib action run self | send_message text="hi"./corelib action listshows the currently available segments with their kind and providing plugin./corelib debug loopsnow lists the long-running tasks thatstart_taskcreates, with a new message for a key matching nothing.- Expression and text configs accept exactly one key name per field. Aliases now count as absent:
value(was alsotext,template,expression,formula),condition(was alsowhen,if,expression,formula),true_value/false_value(were alsotrue/then/value/charandfalse/else/fallback/default),fallback(was alsodefault,else,false_value),cases(was alsoconditions),separator(was alsojoiner),count(was alsorolls,times,random_times,amount),allow_duplicates(was alsoallow_duplicate,allow_repeat,allow_repeats,repeat,repeatable,with_replacement),lines(was alsovalues,options,texts,value),chars(was alsocharacters,alphabet,values),weights(was alsoweight). Bundled samples already use the single names; update your own configs if they used an alias. - Config precheck problems are coloured by severity for the whole line: red for errors, yellow for warnings, grey for notes. The failure count only includes problems that block loading.
- Modules try a config before switching to it: a candidate has to pass precheck to take effect, and the previous working config is kept when it does not. Previously the new config was installed first and only then reported, so one typo could reset a module to its defaults.
- Logs about hooking into external item plugins are more specific: when a plugin is installed but its items are not registered yet the reason is spelled out for ItemsAdder, CraftEngine, NeigeItems, Nexo, Oraxen and EcoItems individually, and a plugin whose API does not match is reported instead of silently skipped.
release_default_datastays for compatibility with existing config files, but with the script samples gone there are no bundled sample resources left for it to control.- For developers:
EmakiCoreLibApiProvideris removed; call the static methods onEmakiCoreLibApidirectly.available(),apiVersion(),pluginName()andisReady()are replaced bystatus(), returningApiStatuswithusable(),ready(), version and plugin name.itemDisplayName(String)anditemDisplayName(ItemStack)returnEmakiResult<String>instead ofString, anditemComponentCapability(String)returnsOptional<ItemComponentCapability>instead of a nullable value. New unified result contractEmakiResultwithFailureKindandUnit. - For developers: third parties register actions through
registerActionStage,registerActionSourceandregisterActionGate(all returningCoreStageRegistration), withonStageRegistryRebuilt(Plugin, Runnable)to re-register after a rebuild. The contract types areCoreActionStage/CoreActionSource/CoreActionGate,CoreStageContext,CoreStageParameter,CoreStageParameterType,CoreStageKind,CoreResolvedArguments,CoreActionSubject,CoreActionOutcome,CoreSourceResult,CoreGateResult,CoreGateThread,CoreTargetRequirement,CoreCancellationToken,CoreActionKey,CoreActionKeys,CoreActionFailureKindandPhaseContract. - For developers: new capability registry (
publishCapabilities,revokeCapabilities,hasCapability,capabilities(),capabilitiesOf(String)) and cross-module readiness contract (whenReady,isModuleReady(String),addModuleListener, withReadinessRegistration,ModuleReadinessPhase,ModuleReadinessListener). Modules publish loading / ready / absent around reloads and shutdown, andstatus().ready()now means the data is loaded rather than components being non-null. Do not re-register inside awhenReadycallback, which hits the already-ready branch and recurses; useaddModuleListenerto rebuild caches on each reload. - For developers:
dialogs()returnsCoreLibDialogs(withDialogDefinitionand the public dialog parsing entry point) andscheduling()returnsEmakiScheduling(withTaskToken); both return no-op implementations when the plugin is absent instead of throwing. The item source system became a public contract (ItemSourceProvider,ItemSourceRef,ItemSourceKind,ItemSourceRegistration,ItemSourceProbeResult,ItemSourceProbeState,LifecycleState,LifecycleStatus) so third parties can register their own source types; the oldItemSourceTypewas a final enum nothing outside could extend. - For developers: shared infrastructure moved into
corelib-apifor direct use, includingTexts,MiniMessages,ConsoleOutputs,ConfigNodes,Numbers,Jsons,SafePaths,SlotParser,EquipmentSlotMatcher,ItemTextBridge,ConditionContext,CommandTabHelper,AsyncFailures,SignatureUtil,Anchors,EntityPhysicsSupport,ConfigPrecheckSeverity, plus the YAML access layerYamlSection,YamlFiles,MapYamlSection,BoostedYamlSection,BoostedYamlSupport,VersionedYamlFileandYamlLoadException. A newMythicMobBridgeconsolidates Mythic metadata lookups.EmakiCoreLibApi.Bridgeremains an internal entry point third-party plugins should not implement.
Fixed
- Random
NoSuchMethodErrorcrashes and text rendering failures on some servers. The runtime libraries CoreLib downloads were on mismatched versions: part of the Adventure family was pinned to4.21.0and the rest to4.26.1, and mixing them makes some calls disappear at runtime, while the gson being fetched was2.8.0, older than the one Paper ships, pushing the server's own copy behind it. The Adventure family is now on a single version and gson matches Paper's2.11.0. - Lore piling up after editing an item definition. Triggering an update kept the old lore lines as external content and appended them after the new ones, adding a round of history each time. The freshly built item is now the only baseline and stale records are cleared.
- Missing precheck message keys in several modules and inconsistent colours on a number of console lines, so raw key names are no longer printed.
Removed
- JS scripting, entirely. Your own
.jsscripts stop working and there is no automatic conversion, so the same logic has to be rebuilt with config actions. - The whole
script:block fromconfig.yml:script.enabled,script.engine(type: graaljs, the timeouts and theallow_*switches),script.paths(root: scriptsand the directories it created),script.action(therunjsid),script.context,script.securityincludingdenied_actions_from_script,script.server_api, andscript.debugwithlog_script_loadandlog_script_execute. Leaving the block in your own file causes no error. - The
runjsaction, the/corelib script [list|inspect|reload]subcommand, and the bundled samplesscripts/examples/hello.js,js_broadcast_action.js,js_event_examples.jsandjs_placeholders.js. Allscript_*andjs_*language keys are gone, so custom language files carrying them hold unused entries. - For developers: the script API surface
EmakiScriptApi,ScriptActionApi,ScriptContextApi,ScriptItemApiandScriptLoggerApi. AlsoCompatibilityReportandcompatibilityReport(),EmakiAttributeBridge,PdcAttributeApiandPdcAttributePayloadSnapshot, and the old action surfaceregisterAction,unregisterAction,unregisterActions,unregisterActionsBySource,actionRegistered,action(String),actions(),actionsByOwner,actionsBySourcewithCoreAction,CoreActionContext,CoreActionDescriptor,CoreActionErrorType,CoreActionExecutionMode,CoreActionParameter,CoreActionParameterType,CoreActionPlanningContext,CoreActionRegistrationandCoreActionResult.FoliaSchedulerAdapterandcorelib.async.TaskHandleare deprecated for removal; move toEmakiScheduling.
Notes
- Back up your whole
plugins/EmakiCoreLib/folder before upgrading, and because this release rewrites other Emaki plugins' configs, back up their folders underplugins/as well. Update CoreLib first, then the plugins that depend on it. - Most action lines are rewritten for you. Four things need doing by hand: converting
loopsync,loopasync,cancelloopandusetemplatetostart_task,stop_taskandrun; rebuilding.jsscript logic as config actions; replacing alias key names in expression and text configs; and deleting thescript:block if you want it gone. - Turn on
vanilla_language.enabledyourself for server-side vanilla item names; it is off by default and goes online the first time. For floating text and damage indicators over the packet backend, install PacketEvents on a server running 1.19.4+, otherwise real entities are used. - Server requirements are unchanged: Paper or a Paper fork on 1.21.8+,
folia-supported: true, Java target 25. No commands or permissions were added or removed;emakicorelib.adminandemakicorelib.reloadare still the only ones. - After upgrading, check the action conversion report in the console for rejected lines, click through a few menus to confirm the click interval does not get in the way, and run
/corelib checkto read the precheck report.
Emaki CoreLib v4.6.0
MineBBS 更新日志
移除内容与破坏性变更
- 内置 Web Console 已整体移除:相关前端页面、
web-console.yml资源文件,以及配置中整个web_console:配置块(监听地址、端口、账号密码、会话超时、安全模式、请求体上限、允许模块、配置浏览限制、历史与快照设置)都不再存在。 - 移除命令
/corelib web(别名webconsole、url、link)与/corelib webdebug [frontend|backend|all]。 - 移除权限
emakicorelib.web,同时移除它在emakicorelib.admin下的子权限项;如果权限插件里有显式授权,请自行删除。 - 移除语言文件中的
web_console:与web_debug:两个段落及其键;自定义语言文件如仍保留这些内容,它们将成为无效条目。 - 不再支持纯 Spigot 服务端,必须使用 Paper 或 Paper 系分支。
默认值变更
script.enabled默认值由true改为false,JavaScript 功能改为按需开启;原先依赖默认开启的服务器需要手动写入script.enabled: true。script.server_api.enabled默认值由true改为false;脚本中调用服务器 API 的用法需要显式重新开启。
新增内置动作与命令
- 新增 15 个内置动作,可在任意动作列表中使用:
giveitem、takeitem、setitem、damageitem、repairitem、setblock、breakblock、explosion、ignite、extinguish、feed、killentity、spawnentity、bossbarshow、bossbarhide。 - 新增
/corelib action子命令:action list查看已注册动作,action run <actionId> [key=value ...]直接触发动作,便于配置调试。 - 新增
/corelib debug all on|off|status运行期全局调试开关,对应新配置键debug.global_all(默认false)。
统一游戏事件通道
- CoreLib 现在只注册一份共享监听器,并把击杀、破坏方块、放置方块、合成、钓鱼、驯服、酿造、熔炉取出以及 MythicMobs 击杀等行为统一转发给依赖它的 Emaki 插件。
- 新增配置块
gameplay_events:enabled(默认true)、last_damager_expire_ticks(200)、brew_attribution_expire_ticks(6000)。
物品与配置能力
- 面向配置作者与 API 使用者开放 configured-item / 物品组件流程,并随插件附带组件目录资源
item-components.yml,其中说明每个minecraft:*组件 id、起始版本与可接受的写法。 - 新增 EcoItems 作为物品来源,按可选软依赖声明。
- 新增配置键
release_default_data(默认true);设为false后不再释放随包的scripts、examples示例文件。 - 新增共享聊天输入服务,插件可以在 GUI 之外请求玩家在聊天栏输入内容。
GUI 点击类型与运行时
- GUI 点击类型从 3 种扩展到 11 种:原先只有
CLICK、LEFTCLICK、RIGHTCLICK,现新增SHIFT_LEFTCLICK、SHIFT_RIGHTCLICK、MIDDLECLICK、DOUBLECLICK、NUMBER_KEY、SWAP_OFFHAND、DROP、CONTROL_DROP,GUI 配置可以区分 Shift、中键、双击、丢弃与快捷栏点击。 - 数据包 GUI 后端现在显式解析点击类型,两种后端在完整点击类型集合上的表现一致。
- 运行库加载改为使用 Paper 官方 plugin-loader classpath 接口,不再在启用阶段注入 jar。
- bStats 改为打包进插件内部,不再作为独立的运行库 jar 分发;相关配置键没有变化。
- 消息前缀更换为新的品牌渐变样式,所有消息都会体现。
修复
- 配置预检信息此前为硬编码英文且忽略
language设置,现已走语言键,en_US.yml与zh_CN.yml都提供了对应文本。
升级说明
- 先升级 CoreLib,再升级依赖它的其它 Emaki 插件。
- 请删除配置中已失效的
web_console:配置块与web-console.yml文件,并移除emakicorelib.web授权。 - 如果之前在使用脚本功能,请手动补回
script.enabled: true与script.server_api.enabled: true。 - 确认服务端为 Paper 系 1.21.8 及以上:插件描述文件已从
plugin.yml迁移到paper-plugin.yml并带 loader 条目,软依赖改为结构化服务器依赖,api-version由1.21提升到1.21.8,低于 1.21.8 的服务端不在支持范围内。Java 目标仍为 25,folia-supported: true与此前一致。 - 命令不再在描述文件中声明,主命令与别名
corelib/emakicore改为运行期注册,服主侧用法不变。 EmakiCoreLibApi为纯新增:已发布的方法全部保留,新增兼容性报告、configured-item 创建与应用、物品组件能力,以及完整的第三方动作注册接口。- 建议正式服升级前备份
plugins/EmakiCoreLib/目录,并在升级后实际验证一次 GUI 点击、动作触发与/corelib debug all status。
SpigotMC Update Log
CENTER[B]◆ Emaki CoreLib v4.6.0 Release ◆/B[/CENTER]
[CENTER]Web Console removed, scripting now opt-in, 15 new built-in actions, a shared gameplay-event layer, and an 11-type GUI click vocabulary.[/CENTER]
CENTER━━━━━━━━━━━━━━━━━━━━/B
[LIST]
[]Removed: the built-in Web Console is gone entirely, including its frontend, the web-console.yml resource, and the whole web_console: configuration block (host, port, auth, session timeout, security mode, request body limit, allowed modules, config-browser limits, history and snapshot settings).
[]Removed: the commands /corelib web (aliases webconsole, url, link) and /corelib webdebug [frontend|backend|all].
[]Removed: the permission emakicorelib.web, including its child entry under emakicorelib.admin. Drop explicit grants from your permission plugin.
[]Removed: the web_console: and web_debug: language sections and their keys; custom language files still carrying them now hold dead entries.
[]Removed: plain Spigot is no longer a supported target. Paper or a Paper fork is required.
[]Default change: script.enabled now defaults to false. Set script.enabled: true if you relied on JavaScript being on by default.
[]Default change: script.server_api.enabled now defaults to false. Re-enable it explicitly for scripts that call the server API.
[]Added 15 built-in actions usable in any action list: giveitem, takeitem, setitem, damageitem, repairitem, setblock, breakblock, explosion, ignite, extinguish, feed, killentity, spawnentity, bossbarshow, bossbarhide.
[]Added /corelib action with action list and action run
Modrinth Changelog
Added
- 15 built-in actions usable in any action list:
giveitem,takeitem,setitem,damageitem,repairitem,setblock,breakblock,explosion,ignite,extinguish,feed,killentity,spawnentity,bossbarshow,bossbarhide. /corelib actionwithaction listandaction run <actionId> [key=value ...]to inspect and directly fire registered actions./corelib debug all on|off|statusruntime global debug toggle, backed by the new config keydebug.global_all(defaultfalse).- Unified gameplay event layer: one shared listener republishes kill / block break / block place / craft / fish / tame / brew / furnace-extract / MythicMobs-kill events to dependent Emaki plugins, configured through the new
gameplay_eventsblock (enableddefaulttrue,last_damager_expire_ticks200,brew_attribution_expire_ticks6000). - Configured-item / item-component pipeline for config authors and API consumers, plus a shipped
item-components.ymlcatalog documenting eachminecraft:*component id, itssinceversion, and accepted format. - EcoItems as an item source, declared as an optional soft dependency.
- Config key
release_default_data(defaulttrue); setfalseto stop writing the bundledscripts/examplessample files. - Shared chat-input service so plugins can ask a player to type a value in chat outside a GUI.
- Localizable config precheck output instead of hardcoded English.
- Additive
EmakiCoreLibApisurface: compatibility report, configured-item create/apply, item component capabilities, and third-party action registration. All previously released methods still exist.
Changed
- GUI click vocabulary expanded from 3 to 11 types:
CLICK,LEFTCLICK,RIGHTCLICKplusSHIFT_LEFTCLICK,SHIFT_RIGHTCLICK,MIDDLECLICK,DOUBLECLICK,NUMBER_KEY,SWAP_OFFHAND,DROP,CONTROL_DROP. - The packet GUI backend resolves click types explicitly, so its click types match the Bukkit backend across the full vocabulary.
script.enableddefault flippedtrue->false; JavaScript is now opt-in.script.server_api.enableddefault flippedtrue->false; scripts calling the server API need it re-enabled explicitly.- Runtime library loading now uses Paper's official plugin-loader classpath API instead of injecting jars at enable time.
- bStats is shaded into the plugin instead of shipping as a separate bundled runtime-library jar. No config key change.
- Message prefix switched to a new brand gradient.
- Descriptor migrated from
plugin.ymltopaper-plugin.ymlwith a loader entry; soft-depends became structured server dependencies.api-versionraised1.21->1.21.8. Java target unchanged at 25. - Commands are no longer declared in the descriptor; the root command plus the
corelib/emakicorealiases register at runtime. Owner-facing usage is unchanged.
Fixed
- Config precheck messages were hardcoded English and ignored the
languagesetting; they now route through language keys present in bothen_US.ymlandzh_CN.yml.
Removed
- The built-in Web Console, including its bundled frontend, the
web-console.ymlresource, and the wholeweb_console:config block (host, port, auth username/password, session timeout, security mode, request body limit, allowed modules, config-browser limits, history/snapshot settings). - The commands
/corelib web(aliaseswebconsole,url,link) and/corelib webdebug [frontend|backend|all]. - The permission
emakicorelib.web, including its child entry underemakicorelib.admin. - The language sections
web_console:andweb_debug:and their keys; custom language files carrying them now have dead entries. - Support for plain Spigot. Paper or a Paper fork is required.
Notes
- Update CoreLib before the other Emaki plugins that depend on it.
- Upgrade actions: delete the stale
web_console:block andweb-console.yml, removeemakicorelib.webgrants, re-addscript.enabled: trueandscript.server_api.enabled: trueif scripting was in use, and confirm the server is Paper 1.21.8+. - Servers below 1.21.8 are out of contract.
folia-supported: truewas already declared before this release. - Back up
plugins/EmakiCoreLib/before updating production, then verify GUI clicks, action triggers, and/corelib debug all status.
