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

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:

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.

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

Economy Bridging

Three provider selection modes:

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:

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:

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

Commands

Permissions

View Full Wiki Documentation | Join Discord Community | QQ Group