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]
  Accessory[EmakiAccessory]
  Station[EmakiStation]
  Cooking[EmakiCooking]
  Codex[EmakiCodex]
  Storage[EmakiStorage]
  Mobs[EmakiMobs]
  Mythic[MythicMobs]
  PAPI[PlaceholderAPI]
  Economy[Vault / ExcellentEconomy]
  Craft[CraftEngine / ItemsAdder / Nexo]

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

  Forge -. attribute writes .-> Attribute
  Strengthen -. attribute writes .-> Attribute
  Gem -. attribute writes .-> Attribute
  Item -. attributes / skills .-> Attribute
  Skills -. resource / attribute checks .-> Attribute
  Level -. exp sources .-> Mythic
  Level -. attribute contributions .-> Attribute
  Accessory -. contribution provider .-> Attribute
  Accessory -. skill source .-> Skills
  Station -. material supply / delivery .-> Storage
  Mobs -. mob attributes .-> Attribute
  Mobs -. mob skills .-> Skills
  Mobs -. loot items .-> Item
  Skills -. skill execution .-> Mythic
  Core -. placeholders .-> PAPI
  Core -. economy .-> Economy
  Cooking -. block / item sources .-> Craft
  Codex -. gameplay events .-> Core

NOTE

The equipment skill PDC codec contract is owned by the emaki.jiuwu.craft.skills.api.pdc package in EmakiSkillsApi. Item, Forge, Gem, and Strengthen shade only that package and relocate it to their own runtime package names at build time, so equipment skill PDC still reads and writes correctly when EmakiSkills is absent.

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.
• 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	EmakiSkillsApi, emaki.jiuwu.craft.skills.api.pdc.EquipmentSkillPdcCodec	Removed; CoreLib no longer ships SkillPdcGateway
Attribute PDC and attribute service contract	EmakiAttributeApi, emaki.jiuwu.craft.attribute.api.PdcAttributeAccess with the full PdcAttributePayload	Removed; CoreLib no longer ships PdcAttributeGateway or the mirror types

IMPORTANT

These CoreLib compatibility adapters were removed in CoreLib 4.6.7. New code must use the authoritative contracts above directly.

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.PdcAttributeAccess for item attribute payloads, reached through EmakiAttributeApi.extensions().pdc() (there is no PdcAttributeApiProvider helper); 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.