EmakiCoreLib | Script-Powered Modular Plugin Framework

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

Category	Action ID	Description
Messages	sendmessage	Send a chat message to the player (MiniMessage supported)
Messages	sendtitle	Send title and subtitle to the player
Messages	sendactionbar	Send an action bar message
Messages	broadcastmessage	Broadcast a message to all players
Sound & Particles	playsound	Play a sound effect (volume, pitch configurable)
Sound & Particles	spawnparticle	Spawn particles at a location
Economy	givemoney	Give money to the player
Economy	takemoney	Take money from the player
Economy	setmoney	Set the player's balance
Items	createitem	Create an item and place it in the player's inventory
Items	senditem	Send the current context item to the player
Items	clearitem	Remove specified items from the player's inventory
Items	dropitem	Drop an item at a specified location
Blocks	placeblock	Place a block (supports CraftEngine/ItemsAdder/Nexo)
Player State	heal	Restore player health
Player State	damage	Deal damage to the player
Player State	sethealth	Set player health directly
Player State	giveexp	Give experience points
Player State	takeexp	Take experience points
Player State	setexp	Set experience points
Player State	givepotioneffect	Apply a potion effect
Player State	removepotioneffect	Remove a specific potion effect
Player State	clearpotioneffects	Clear all potion effects
Player State	teleport	Teleport the player to coordinates
Commands	runcommandasplayer	Execute a command as the player
Commands	runcommandasop	Execute a command with OP privileges
Commands	runcommandasconsolee	Execute a command as console
Templates	usetemplate	Reference and execute a predefined action template
Integration	castmythicskill	Trigger a MythicMobs skill
Scripting	runjs	Execute a JavaScript script (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

Scripts run in a strictly isolated 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:

scripts/
├── global/        # General-purpose scripts
├── forge/         # Forging-related scripts
├── strengthen/    # Strengthening-related scripts
├── cooking/       # Cooking-related scripts
├── gem/           # Gem-related scripts
├── skills/        # Skill-related scripts
├── item/          # Item-related scripts
├── attribute/     # Attribute-related scripts
├── templates/     # Template scripts
└── examples/      # Example scripts

The emaki Global Object API

Scripts access the server environment through the emaki global object:

API	Description
emaki.player.exists()	Whether a player exists in the current context
emaki.player.name()	Player name
emaki.player.uuid()	Player UUID
emaki.player.world()	Player's current world name
emaki.player.hasPermission(perm)	Check a permission
emaki.player.sendMessage(msg)	Send a message to the player
emaki.context.phase()	Current execution phase
emaki.context.plugin()	Source plugin name
emaki.context.placeholder(key)	Get a placeholder value
emaki.context.placeholders()	Get all placeholders
emaki.context.attribute(key)	Get a context attribute
emaki.context.attributes()	Get all context attributes
emaki.context.arg(key)	Get an action argument
emaki.context.args()	Get all action arguments
emaki.item	Current context item operations
emaki.action.run(actionId, args)	Execute a specific action
emaki.action.runLine(line)	Execute an action line string
emaki.logger.info(msg)	Output an INFO log message
emaki.random	Random number utilities
emaki.state.set(key, value)	Write to shared state
emaki.state.get(key)	Read from shared state
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

Script Example

function main(ctx) {
  emaki.logger.info("Hello from Emaki JavaScript.");
  if (emaki.player.exists()) {
    emaki.player.sendMessage("[EmakiJS] Hello, " + emaki.player.name() + "!");
  }
  emaki.state.set("hello_script_executed", true);
  return { success: true, message: "hello.js executed" };
}

Item Source Resolution

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

Source	Aliases	Description
Vanilla	vanilla, minecraft, v	Standard Minecraft items
CraftEngine	craftengine, ce	CraftEngine custom items
ItemsAdder	itemsadder, ia	ItemsAdder custom items
NeigeItems	neigeitems, ni	NeigeItems custom items
MMOItems	mmoitems, mi	MMOItems custom items
EmakiItem	emakiitem, ei	Emaki series custom items
Nexo	nexo, no	Nexo custom items

Regardless of which item source is referenced in plugin configurations, CoreLib resolves and retrieves them correctly.

Economy Bridging

Three provider selection modes:

Mode	Description
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 for flexible adaptation to different server economies.

Condition System

A flexible condition evaluation framework supporting 5 combination modes:

Type	Description
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:

Strategy	Description
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

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

Commands

Command	Description
/emaki reload	Reload core configuration

Permissions

Permission	Description
emaki.admin	Administrator permission

View Full Wiki Documentation | Join Discord Community | QQ Group