Public API

Compile-time dependency

<repositories><repository><id>jiuwu-releases</id><url>https://repo.crypticlib.com/repository/maven-public/</url></repository></repositories>
<dependency><groupId>emaki.jiuwu.craft</groupId><artifactId>emaki-gem-api</artifactId><version>2.8.8</version><scope>provided</scope></dependency>

repositories { maven("https://repo.crypticlib.com/repository/maven-public/") }
dependencies { compileOnly("emaki.jiuwu.craft:emaki-gem-api:2.8.8") }

Compile only — never install, shade, or relocate this jar

EmakiGem embeds the un-relocated API. A bundled copy breaks Bukkit event and bridge identity

Check EmakiGemApi.status().usable() before use. The facade exposes exactly two non-null layers, catalog() and operations(); there is no extensions(). install, uninstall, and Bridge are runtime-internal conventions and form no public contract

catalog() reads gem definitions, item identity, opener matching, socketed-gem state, aggregated attributes/skills, resonance, and inlay/extract relationship checks. Thread contract: definition tables are readable from any thread; live ItemStacks must be read on the holder's owner thread. A successful GemRelationshipCheck with allowed()==false must not be used to express a business rejection

Reroll exposes a single read-only entry: catalog().rerollSession(operatorId) returns Optional<GemRerollSessionView>, empty when there is no session, the runtime is unavailable, or operatorId is null. The view carries operationType, originalAffixes, candidateAffixes, stage, version, createdAt, expiryAt, and terminalState, plus open() to test whether it is still in the open terminal state. operations() has no reroll method — candidates can only be generated and confirmed through commands or the GUI — and there are no reroll events

Player operations require the actor owner thread. inlay and extract return committed GemInlayOutcome/GemExtractOutcome; callers write updatedEquipment back and consume/deliver returned items as the outcome specifies. Their operationId matches the pre-event and eventual completed event. Completed events fire only after configured success actions and persistent journal completion, not merely after commit starts. openSocket returns the updated equipment and decrements the supplied opener stack in place on success. createGemItem builds a detached item and is any-thread; clearGems, GUI methods, and live stacks obey ownership

Use Success, Partial, Failure, and optionalValue(). Failure kinds: UNAVAILABLE, NOT_FOUND, INVALID_INPUT, REJECTED, CANCELLED, TARGET_OFFLINE, WRONG_THREAD, INTERNAL_ERROR