EmakiCoreLib is the shared foundation for all Emaki series plugins. It does not provide gameplay features directly — instead, it offers unified service registration, an action execution engine, GUI framework, economy bridging, and item source resolution for all upper-layer plugins. If you use any Emaki plugin, this is a required dependency.

Core Features

Action Engine — 28 Built-in Action Types

The action engine is the driving force behind the entire Emaki ecosystem. All upper-layer plugins (skills, forging, strengthening, cooking, etc.) execute their effects through this engine. Actions are described as single-line text in the format actionId param1=value1 param2=value2, with support for @delay=10t delay prefixes and @template=name template references.

Complete Action Type List

• Messages: sendmessage, sendtitle, sendactionbar, broadcastmessage
• Sound & Particles: playsound, spawnparticle
• Economy: givemoney, takemoney, setmoney
• Items: createitem, senditem, clearitem, dropitem
• Blocks: placeblock (supports CraftEngine/ItemsAdder/Nexo)
• Player State: heal, damage, sethealth, giveexp, takeexp, setexp, givepotioneffect, removepotioneffect, clearpotioneffects, teleport
• Commands: runcommandasplayer, runcommandasop, runcommandasconsolee
• Templates: usetemplate
• Integration: castmythicskill
• Scripting: runjs (aliases: runscript, javascript)

Action templates let you define reusable action sequences in config.yml under action.templates, then reference them anywhere via @template=templateName.

JavaScript Script Engine

A secure scripting environment powered by GraalJS. When built-in actions aren't enough, write JavaScript to implement custom logic.

Security Sandbox

• No file system access (allow_io: false)
• No thread creation (allow_threads: false)
• No native code access (allow_native_access: false)
• No environment variable access (allow_environment_access: false)
• No host class lookup (allow_host_class_lookup: false)
• Path security filtering: rejects paths containing .., :, or \
• Recursive script calls blocked (runjs/runscript/javascript denied from within scripts)
• Max action dispatch depth limit (default: 3)

Timeout Protection

• Default timeout: 1000ms
• Max configurable timeout: 5000ms
• Scripts forcibly terminated on timeout to prevent server freezes

Script Caching

• Compiled scripts are cached for improved performance
• Optional recompilation on reload (recompile_on_reload: true)

Directory Structure

Scripts are stored under plugins/EmakiCoreLib/scripts/ with auto-created subdirectories: global, forge, strengthen, cooking, gem, skills, item, attribute, templates, examples.

The emaki Global Object API

• emaki.player — Player info: exists(), name(), uuid(), world(), hasPermission(), sendMessage()
• emaki.context — Execution context: phase(), plugin(), placeholder(), placeholders(), attribute(), attributes(), arg(), args()
• emaki.item — Current context item operations
• emaki.action — Dispatch actions: run(actionId, args), runLine(line)
• emaki.logger — Logging: info(msg)
• emaki.random — Random number utilities
• emaki.state — Shared state: set(key, value), get(key)
• emaki.text — Text processing utilities
• emaki.runSync(task) — Execute a task on the main server thread
• emaki.runSyncAndWait(task) — Execute on main thread and await completion (returns CompletableFuture)

Item Source Resolution

A unified item retrieval interface supporting 7 sources. Use source:itemId format in any configuration that requires an item reference.

• Vanilla (aliases: vanilla, minecraft, v) — standard Minecraft items
• CraftEngine (aliases: craftengine, ce) — CraftEngine custom items
• ItemsAdder (aliases: itemsadder, ia) — ItemsAdder custom items
• NeigeItems (aliases: neigeitems, ni) — NeigeItems custom items
• MMOItems (aliases: mmoitems, mi) — MMOItems custom items
• EmakiItem (aliases: emakiitem, ei) — Emaki series custom items
• Nexo (aliases: nexo, no) — Nexo custom items

Economy Bridging

Three provider selection modes:

• auto — Automatically selects ExcellentEconomy when a currency ID is specified, otherwise falls back to Vault
• vault — Forces Vault (compatible with most economy plugins)
• excellenteconomy — Forces ExcellentEconomy (requires currency ID, supports multi-currency)

Economy actions ( givemoney/ takemoney/ setmoney) all support provider and currency parameters.

Condition System

A flexible condition evaluation framework supporting 5 combination modes:

• all_of — All conditions must pass (default)
• any_of — Any single condition passing is sufficient
• none_of — All conditions must fail
• at_least — At least N conditions must pass (requires required_count)
• exactly — Exactly N conditions must pass (requires required_count)

Conditions support nested grouping and are used for action triggers, equipment restrictions, skill casting, and more.

GUI Framework

A template-driven chest interface builder. Define layouts, item slots, and click actions via YAML templates — upper-layer plugins can create interactive GUIs without writing Java code. Supports item source resolution, placeholder substitution, and action binding.

Item Operation Ledger

A reversible item name/lore modification tracking system. When multiple plugins (forging, strengthening, gems, etc.) modify the same item's display, the ledger records each change and supports precise rollback of individual operations without affecting others.

Config Sync

Cross-plugin hot-reload infrastructure with three file synchronization strategies:

• versionedFiles — Automatically merges new config entries on plugin update while preserving user modifications
• staticFiles — Only extracted when the file doesn't exist; never overwritten afterward
• defaultDataFiles — Sample data extracted only on first install; subsequent updates won't overwrite

Async Infrastructure

• Async File Service — Non-blocking config I/O to avoid main thread stalls
• PDC Data Service — PersistentDataContainer read/write utilities
• Action Dispatcher — Supports delayed execution, async execution, and Future callbacks

Requirements

• Server: Spigot 1.21+
• Java: 21+
• Hard Dependencies: None
• Soft Dependencies: Vault, ExcellentEconomy, PlaceholderAPI, CraftEngine, ItemsAdder, NeigeItems, MMOItems, Nexo

Commands

• /emaki reload — Reload core configuration

Permissions

• emaki.admin — Administrator permission