Architecture

Emaki Series uses a shared-infrastructure architecture: CoreLib provides common services, and business modules implement gameplay features.

Layers

graph TB
  Server[Paper / Bukkit 1.21.8+]
  Core[EmakiCoreLib]
  Attribute[EmakiAttribute]
  Item[EmakiItem]
  Forge[EmakiForge]
  Strengthen[EmakiStrengthen]
  Gem[EmakiGem]
  Level[EmakiLevel]
  Skills[EmakiSkills]
  Cooking[EmakiCooking]
  Codex[EmakiCodex]
  Storage[EmakiStorage]
  Protocol[EmakiSkillsProtocol<br/>compile-time only, not a plugin]
  Mythic[MythicMobs]

  Core --> Server
  Attribute --> Core
  Item --> Core
  Forge --> Core
  Strengthen --> Core
  Gem --> Core
  Level --> Core
  Skills --> Core
  Cooking --> Core
  Codex --> Core
  Storage --> Core

  Protocol -. equipment skill PDC contract .-> Core
  Protocol -. equipment skill PDC contract .-> Item
  Protocol -. equipment skill PDC contract .-> Skills

  Level -. exp sources .-> Mythic
  Level -. attribute contributions .-> Attribute
  Skills -. skill execution .-> Mythic
  Codex -. gameplay events .-> Core

EmakiSkillsProtocol in the diagram is a compile-time protocol artifact, not a server plugin. Do not put it into plugins/. It is shaded and relocated into CoreLib, Item, Skills, Forge, Gem, and Strengthen at build time.

CoreLib responsibilities

CoreLib is the shared infrastructure layer. It carries no gameplay rules and no domain protocols. It provides:

• Scheduling and thread ownership: a unified execution dispatcher with thread-ownership rules, backed by Paper and Folia platform adapters.
• Async and file services: async task scheduling, file services, and concurrent data stores.
• YAML configuration: loading, prechecks, and the safe migration base.
• Generic PDC helpers: low-level structured storage on items, entities, and players.
• GUI: menu templates, slots, click handling, and session state.
• Actions: messages, commands, sounds, item grants, costs, delays, probability, and conditional control.
• Script engine: GraalVM JavaScript execution with limit policies.
• Expressions and conditions: numeric formulas, condition groups, and probability rules in YAML.
• Item sources: Vanilla, MMOItems, ItemsAdder, Nexo, Oraxen, EcoItems, CraftEngine, and NeigeItems resolution.
• Economy bridges: Vault and ExcellentEconomy access.
• Weights and randomness: weighted random selection and numeric helpers.
• Shared registries: actions, namespaces, layer codecs, and GUI backends.
• Structured item assembly and presentation coordination: merge module layers into the final name, lore, and attribute display.
• Runtime library preparation: loading runtime dependencies.

Contracts no longer owned by CoreLib

Domain protocols and extension points were moved back to the business modules. Use the current owner:

Contract	Current single source of truth	CoreLib status
Item layer preview SPI (ItemLayerPreviewProvider, ItemLayerPreviewRequest, ...)	EmakiItemApi, package emaki.jiuwu.craft.item.api.preview	Removed; CoreLib no longer offers this extension point
Equipment skill PDC keys and codec	EmakiSkillsProtocol, EquipmentSkillPdcCodec	SkillPdcGateway is only a @Deprecated(forRemoval = true) delegating adapter
Attribute PDC and attribute service contract	EmakiAttributeApi, emaki.jiuwu.craft.attribute.api.PdcAttributeApi with the full PdcAttributePayload	PdcAttributeGateway and the CoreLib PdcAttributeApi mirror are @Deprecated(forRemoval = true); the mirror is lossy

These CoreLib adapters are retained for one synchronized release window only. New code should not depend on them.

Cross-module cooperation

• Business modules declare CoreLib as a required dependency loaded before them.
• Optional modules cooperate through soft dependencies, static API facades, internal bridges, PDC, and events.
• Attribute exposes emaki.jiuwu.craft.attribute.api.PdcAttributeApi (with PdcAttributeApiProvider) for item attribute payloads; player resource and combat state are handled by module bridges and events.
• Forge, Strengthen, Gem, and Item write their own item layers or attribute payloads.
• Level stores player progression, exposes placeholders/API, and can contribute level-based attributes.
• CoreLib Assembly rebuilds final item display from all layers.
• Skills checks cooldowns, resources, and triggers, then calls MythicMobs for actual effects.
• Cooking stores station state by world location.
• Codex registers YAML-defined nodes as vanilla advancements and grants them from commands, CoreLib actions, the public API, or CoreLib shared gameplay events.

Equipment data flow

1. Item creates a stable custom item.
2. Forge writes forge quality or material contributions.
3. Strengthen writes star state.
4. Gem writes sockets and gems.
5. CoreLib rebuilds name and lore.
6. Attribute aggregates final stats.

Level data flow

1. A player triggers a source: kill, gather, craft, fish, tame, or MythicMobs drop.
2. EmakiLevel writes exp into the configured level type.
3. Requirement formulas decide whether auto-upgrade can happen.
4. Level-up costs, rewards, and CoreLib actions are applied.
5. Player PDC, PlaceholderAPI output, cached leaderboard data, and optional EmakiAttribute contributions are refreshed.

Other plugins should use CoreLib actions or the Level API to grant exp instead of editing player data files directly.

Codex data flow

1. advancements/*.yml defines a page, a root node, and child nodes. Node keys look like emakicodex:<page>/<node>.
2. Codex registers the nodes as vanilla advancements.
3. Nodes are granted by commands, CoreLib actions, the public API, or triggers.entries bound to CoreLib shared gameplay events such as kill, craft, furnace extract, fish, brew, tame, and block break.
4. When a node is completed for the first time, actions.complete runs its CoreLib actions.
5. With PacketEvents installed, advancement tree coordinates can additionally be injected into the client.

Design advice

Do not let multiple modules directly overwrite the same Lore block. Store real state in PDC or module layers, and let CoreLib rebuild presentation.