A P I

MythicCrucible ships a stable integration API (MythicCrucibleAPI), a set of Bukkit events, and, because every Crucible item is also a MythicMobs item, access to the MythicMobs API for item and skill work. Everything below lives in the MythicCrucible-API artifact, which is the only Crucible artifact you should depend on.

Repositories

The API is published to the same Lumine repository as MythicMobs. Its Paper API dependency comes from the PaperMC repository.

Maven

<repository>
    <id>nexus</id>
    <name>Lumine Releases</name>
    <url>https://mvn.lumine.io/repository/maven-public/</url>
</repository>
<repository>
    <id>papermc</id>
    <url>https://repo.papermc.io/repository/maven-public/</url>
</repository>

Gradle (Groovy)

repositories {
    // ...
    mavenCentral()
    maven { url = 'https://mvn.lumine.io/repository/maven-public/' }
    maven { url = 'https://repo.papermc.io/repository/maven-public/' }
}

Gradle (Kotlin)

repositories {
    // ...
    mavenCentral()
    maven(url = "https://mvn.lumine.io/repository/maven-public/")
    maven(url = "https://repo.papermc.io/repository/maven-public/")
}

Dependencies

MythicCrucible-API is the only artifact you need, and the only one you should ever depend on. It ships a sources jar, so your IDE will show the API's documentation inline.

Maven

<dependency>
    <groupId>io.lumine</groupId>
    <artifactId>MythicCrucible-API</artifactId>
    <version>5.13.1-SNAPSHOT</version>
    <scope>provided</scope>
</dependency>

Gradle (Groovy)

dependencies {
    // ...
    compileOnly 'io.lumine:MythicCrucible-API:5.13.1-SNAPSHOT'
}

Gradle (Kotlin)

dependencies {
    // ...
    compileOnly("io.lumine:MythicCrucible-API:5.13.1-SNAPSHOT")
}

Do not depend on MythicCrucible-Dist or any other Crucible artifact. Those are the complete paid plugin, they are not supported integration targets, and no new versions of them are published. MythicCrucible-API is the supported surface.

The API's MythicMobs (Mythic-Dist 5.13.0) and Paper API (1.21.4) dependencies come through transitively as compile-only dependencies, so you do not declare them yourself unless you need newer versions. isFurnitureItem, furnitureFits, getFurnitureFootprint, placeFurniture, placeFurnitureResult without a BlockFace, isFurniture(Block), getFurnitureItemId and removeFurniture shipped in 5.13.0; everything else on this page, including getFurniture, isFurniture(Entity) and the BlockFace overload of placeFurnitureResult, needs MythicCrucible 5.13.1 or newer on the server, and older versions fail at runtime with NoSuchMethodError or NoClassDefFoundError. Documentation for the Mythic types used alongside this API (MythicItem, MythicConfig, SkillCaster, and so on) lives in the Mythic JavaDocs.

plugin.yml

Add MythicCrucible (and MythicMobs) to your depend so your plugin loads after them:

depend: [MythicMobs, MythicCrucible]

Getting the API

import io.lumine.mythiccrucible.api.MythicCrucibleAPI;
import io.lumine.mythiccrucible.api.MythicCrucibleProvider;

MythicCrucibleAPI crucible = MythicCrucibleProvider.get();

MythicCrucibleProvider.get() throws IllegalStateException until Crucible has enabled. With MythicCrucible in your plugin.yml depend, call it from your own onEnable(). Do not wait for MythicCrucibleLoadedEvent instead: it fires once, during Crucible's own enable, so a plugin that depends on Crucible registers its listeners too late to receive it. Methods that take a block or an entity, and all placement and removal methods, read or change the world, so call them on the main thread.

Everything the API hands you is an interface from io.lumine.mythiccrucible.api.*, never one of Crucible's implementation classes, so your code keeps compiling as Crucible's internals change. The furniture placement helpers are expressed in stable terms (String item ids, Bukkit Block/Player, primitives and Optionals) and degrade gracefully, returning empty or false when an id is unknown, a block holds no furniture, or the plugin is not ready. The richer lookups return API interfaces such as CrucibleItem, Furniture, FurnitureItemContext, CustomBlockItemContext and Profile.

These interfaces are implemented by Crucible only. Do not implement them yourself; passing your own implementation back into the API is rejected. The one exception is io.lumine.mythiccrucible.items.SkillHolder, which you implement to run your own skills on a player (see Running your own skills on a player).

Looking things up

import io.lumine.mythiccrucible.api.items.CrucibleItem;
import io.lumine.mythiccrucible.api.furniture.Furniture;

// items, by id or from a live stack
Optional<CrucibleItem> byId = crucible.getItem("MyChair");
Optional<CrucibleItem> byStack = crucible.getItem(itemStack);
Collection<String> everyItemId = crucible.getItemNames();

// custom blocks
crucible.getCustomBlock(block).ifPresent(cb -> {
    String id = cb.getCrucibleItem().getInternalName();
});

// furniture, from a block or from any of its entities (frame, hitbox or seat)
Optional<Furniture> f1 = crucible.getFurniture(block);
Optional<Furniture> f2 = crucible.getFurniture(entity);

A Furniture is a handle bound to one frame entity. Tracked furniture (furniture with timer or random-tick skills, or with Tracked: true, which defaults on when Variables or KeepVariablesOnDrop is set) always returns the same handle, and rotation re-points it at the respawned frame. A GlowingFrame state change also respawns the frame and re-points the handle the same way. Other furniture returns a new handle per lookup, and a handle obtained before a rotation keeps pointing at the removed frame. A skill that sets a variable on untracked furniture tracks it until it is removed or its chunk unloads. A Crucible reload replaces every handle; a handle from before a reload still acts on the live piece, but with the pre-reload definition. Removing furniture through a handle whose frame is gone (removed, rotated, respawned or unloaded) does nothing and returns false; re-resolve the furniture after a removal, rotation or reload rather than caching it.

Examples

Check for furniture at a block

MythicCrucibleAPI crucible = MythicCrucibleProvider.get();
Block block = ...;

if (crucible.isFurniture(block)) {
    crucible.getFurnitureItemId(block).ifPresent(id -> {
        // id is the Crucible item id of the furniture at this block
    });
}

Place furniture

boolean placed = crucible.placeFurniture("MyChair", block, 90f);

For feedback on why placement failed, use the result variant:

import io.lumine.mythiccrucible.api.FurniturePlacementResult;

FurniturePlacementResult result = crucible.placeFurnitureResult("MyChair", block, 90f);
switch (result) {
    case SUCCESS -> player.sendMessage("Placed!");
    case OBSTRUCTED -> player.sendMessage("Not enough room.");
    case NO_SUPPORTING_BLOCK -> player.sendMessage("Needs a solid surface to rest on.");
    case UNSUPPORTED_PLACEMENT -> player.sendMessage("Can't place that here.");
    case SPAWN_CANCELLED -> player.sendMessage("Another plugin blocked the placement.");
    case UNKNOWN_ITEM, NOT_FURNITURE -> player.sendMessage("That isn't a furniture item.");
    default -> player.sendMessage("Could not place that.");
}

SPAWN_CANCELLED means another plugin cancelled the spawn of the furniture's entity, so nothing was placed. The API runs no protection checks of its own, but it cannot place past a cancelled spawn. These methods place on the floor, or at the furniture's default placement when it cannot go on the floor (ceiling-only furniture goes on the ceiling). Wall-only furniture needs the face overload, which takes the face a player would click: BlockFace.UP for the floor, BlockFace.DOWN for a ceiling, or NORTH/SOUTH/EAST/WEST for a wall (NORTH hangs the furniture on the block south of block). It returns UNSUPPORTED_PLACEMENT when the furniture cannot attach to that face, instead of falling back to another one:

FurniturePlacementResult result = crucible.placeFurnitureResult("MyPainting", block, BlockFace.NORTH, 0f, player);

Placement does not return the placed piece. To get its handle, look it up at the same block afterwards:

if (crucible.placeFurnitureResult("MyChair", block, 90f).isSuccess()) {
    Furniture placed = crucible.getFurniture(block).orElseThrow();
}

Clear terrain before placing large furniture

getFurnitureFootprint returns exactly the blocks placeFurniture checks (the base block plus rotated Barriers/Lights offsets), so you can clear them first, then place:

List<Block> footprint = crucible.getFurnitureFootprint("BigStatue", block, 0f);
for (Block b : footprint) {
    b.setType(Material.AIR);
}
crucible.placeFurniture("BigStatue", block, 0f);

Remove furniture

// remove, running break skills + drop table, and dropping the stored inventory
crucible.removeFurniture(block, player, true, true);

FurnitureItemContext#remove throws IllegalArgumentException when the Furniture belongs to a different item than that context.

Change the model of one placed piece

setCustomModelDataFloats overrides the custom model data floats of one placed piece, so a single furniture definition can show a different model per piece, for example through a custom_model_data range dispatch in its item model:

Furniture flag = crucible.getFurniture(block).orElseThrow();
flag.setCustomModelDataFloats(List.of(12f));
List<Float> floats = flag.getCustomModelDataFloats();
flag.setCustomModelDataFloats(null);

getCustomModelDataFloats returns the override, or null when the piece has none. Passing null removes the override, and the piece goes back to the floats of its current state.

Only the floats change: the strings, flags and colors still come from the piece's current state, and its dye color stays. The override is stored on the furniture's frame entity and works for display, item frame and armor stand furniture. It survives restarts, chunk reloads, rotation, state changes (GlowingFrame states included, which respawn the frame) and recoloring. Players who can see the piece get the change right away, and players who come into range later get it as well. Display furniture holds no item on the server, so Crucible puts the floats into the model it sends to each player; do not write an item onto the display entity yourself. An empty list removes the floats but keeps the state's strings, flags and colors. Crucible keeps its own copy of the list you pass.

The override does not go onto the item a broken piece drops, so a piece placed from that item starts without one. ModelEngine furniture draws its model through ModelEngine, so there the override only reaches the item worn by the base armor stand. The method needs Minecraft 1.21.4 or newer and throws UnsupportedOperationException on older servers. It can be called from any thread: off the main thread it returns at once and the change is applied on the main thread shortly after, so a getCustomModelDataFloats call right after it can still return the old value.

Generate a Crucible item as an ItemStack

Every Crucible item wraps a MythicMobs item, which you reach through the API rather than through Crucible's internals:

import io.lumine.mythic.bukkit.BukkitAdapter;

crucible.getItem("MyCrucibleItem").ifPresent(item -> {
    ItemStack stack = BukkitAdapter.adapt(item.getMythicItem().generateItemStack(1));
    player.getInventory().addItem(stack);
});

Running your own skills on a player

Implement io.lumine.mythiccrucible.items.SkillHolder and register it on the player's profile; Crucible then runs its timer skills and triggers alongside the player's own items:

import io.lumine.mythiccrucible.items.SkillHolder;

crucible.getProfile(player).ifPresent(profile -> profile.registerExternalHolder(myHolder));

// when it no longer applies
crucible.getProfile(player).ifPresent(profile -> profile.unregisterExternalHolder(myHolder));
  • getProfile is empty until the player has joined (for example during PlayerLoginEvent) and once they disconnect. Profiles live for one session and are dropped shortly after the player quits, so register again when the player joins.
  • A profile loads asynchronously after join. You can register a holder right away: it does not run until the profile has loaded. Use whenLoaded only for your own actions that must wait for the load; it runs the action immediately if the profile has loaded, otherwise later on the main thread. The action never runs if the player disconnects before their profile finishes loading.
  • Return true from runSkills(caster, cause, ...) only to cancel the event that triggered it: returning true for a death, sneak or arm-swing trigger cancels that player event.
  • runTimerSkills is called from Crucible's asynchronous clock, not the main thread. Its timer argument is the number of clock runs since Crucible enabled. The clock runs once per server tick, so timer % 20 == 0 is about once a second.
  • ~onUse reaches your holder on every right-click with an item in the main hand, whether or not it is a Crucible item, including when the held item's ammo system stops its own ~onUse skills. ~onUsePrimary reaches it on each of those right-clicks that is not incidental (eating, placing a block, opening a container and the like).
  • Triggers that Crucible fires on one particular stack rather than on the player, such as ~onConsume, ~onBlock, ~onPickup, ~onItemBreak, ~onDragDrop and the projectile, inventory and drop triggers, run only that stack's skills and are not passed to your holder.
  • An exception or linkage error thrown by your holder is logged and skipped; it does not stop other holders or players.

profile.getEquippedItems() returns the stacks Crucible currently treats as equipped, keyed by slot: HAND, OFFHAND, HEAD, CHEST, LEGS, FEET, and the name of each custom equippable slot. A stack is listed only while it passes its item's slot, level and EquipConditions checks, so a player who fails one loses your skills for that stack along with the item's own. Only Crucible items are listed, and the map is empty until the profile has loaded. The map is an unmodifiable snapshot and the stacks are the ones Crucible holds, not copies; fetch it again for each trigger instead of keeping it.

To give your skills the item context Crucible gives an item's own skills, call applyItemContext(meta) on their metadata. It sets the stack that <item.*> placeholders and item mechanics act on, <item.slot> (the hotbar slot for HAND, -1 for every other slot) and <item.equip.slot> (the map key). For a holder that keeps its player's profile:

import io.lumine.mythiccrucible.api.profile.EquippedItem;

@Override
public boolean runSkills(SkillCaster caster, SkillTrigger cause, AbstractLocation origin, AbstractEntity trigger, Consumer<SkillMetadata> transformer) {
    boolean cancel = false;
    for (EquippedItem equipped : profile.getEquippedItems().values()) {
        Collection<SkillMechanic> skills = mySkills(equipped.getItemStack(), cause);
        if (skills.isEmpty()) {
            continue;
        }
        TriggeredSkill ts = new TriggeredSkill(cause, caster, origin, trigger, skills, true, meta -> {
            equipped.applyItemContext(meta);
            if (transformer != null) {
                transformer.accept(meta);
            }
        });
        cancel |= ts.getCancelled();
    }
    return cancel;
}

Events

Bukkit events fired by MythicCrucible. A checkmark in the Cancellable column means the event implements Cancellable.

Furniture

Event Description Cancellable
MythicFurniturePlaceEvent Fired when a player places a furniture item, and when the placeFurnitureAt mechanic is cast by a player (the caster is the player). Exposes the player, block, block face, yaw and color (the item's configured color when it carries none). The block face is the direction of the supporting block (DOWN for the floor), the opposite of the clicked face. It is not fired for API placement, other skills, world generation or WorldEdit pastes. It fires before the furniture's entity spawns, so a plugin that cancels that spawn still stops the placement. yes
MythicFurnitureRemoveEvent Fired when Crucible removes a furniture: a player breaks it, a remove skill runs, the API removes it, or an item-frame furniture is worn down by block explosions or, when solid, by losing its support (the breaker is null for those two). Rotating a furniture does not fire it, and neither does its entity being removed by other means (/kill, WorldEdit, other plugins). Exposes the breaker and the furniture. When break skills run, an ~onBlockBreak skill can still cancel the removal after this event. yes
MythicFurnitureRotateEvent Fired when a player rotates a furniture. Exposes the player and the furniture. yes
MythicFurnitureTrackEvent Fired on the main thread when Crucible starts tracking a furniture: a tracked furniture (see Looking things up) is placed, rotated, respawned by a GlowingFrame state change, its chunk loads or Crucible reloads, or a skill sets a variable on an untracked one.
MythicFurnitureUntrackEvent Fired when Crucible stops tracking a furniture: it is removed or rotated, its entity leaves the world, or Crucible reloads its items. Rotating a tracked furniture, or a GlowingFrame state change that respawns its frame, fires Untrack for the old frame, then Track for the same handle on the new frame. After a reload only furniture with timer or random-tick skills or Tracked: true is tracked again, with new handles.

Lifecycle

Event Description Cancellable
MythicCrucibleLoadedEvent Fired once, during MythicCrucible's enable. Plugins that depend on Crucible enable later and never receive it. Exposes the Bukkit Plugin instance.
MythicCrucibleReloadedEvent Fired after MythicCrucible has reloaded its items: after /mm reload, after /crucible reload, and when Nexo (re)loads its items, which happens once shortly after startup and on /nexo reload. CrucibleItem objects from before the reload are stale; look them up again. Exposes the Bukkit Plugin instance.
MythicCrucibleGeneratePackEvent Fired after MythicCrucible finishes generating a resource pack, once the zip (and PackSquash, if enabled) has been fully written. Exposes the generated zip file, or the pack output folder when ZipPack is disabled.

Crafting

Event Description Cancellable
MythicCraftItemEvent Fired for a craft in Crucible's custom crafting system, immediately before the result is applied. Exposes the recipe key, the craft count, the result item(s) and the triggering InventoryClickEvent. yes
MythicCraftItemCompleteEvent Fired after a craft in Crucible's custom crafting system has happened. getTimes() is the number of crafts performed. Exposes the same recipe key, result item(s) and triggering event.
@EventHandler
public void onCraft(MythicCraftItemEvent event) {
    NamespacedKey recipe = event.getRecipeKey();
    int times = event.getTimes();
    ItemStack result = event.getResult();
}

getTimes() is the planned count, clamped to 1 for a non-shift click; a shift-click with room for fewer crafts still reports the planned figure, because the achievable count is computed after this event. A craft that is not cancelled can still fail afterwards (the cursor cannot stack the result, or the inventory has no room), so count crafts with MythicCraftItemCompleteEvent, whose getTimes() is the achieved count. getResult() is the station's display stack, so treat it as identifying what is being crafted rather than as the stack the player receives: its amount is not meaningful. Compare recipes with getRecipeKey(), using NamespacedKey#equals rather than parsing the key string.

Migrating from MythicCrucible-Dist

Plugins compiled against the old MythicCrucible-Dist jar must be rebuilt against MythicCrucible-API. The furniture event getters now return the API interfaces (io.lumine.mythiccrucible.api.furniture.Furniture and FurnitureItemContext), MythicCrucibleLoadedEvent#getPlugin returns a Bukkit Plugin, and MythicCraftItemEvent no longer has getResultInventory, getOtherInventories, getCache, getMapping or setMapping. Old builds throw NoSuchMethodError inside those listeners. In most cases the source change is only swapping imports to the io.lumine.mythiccrucible.api packages.

Custom Mechanics, Conditions, Placeholders & Triggers

Crucible's own item mechanics, conditions, targeters, placeholders and triggers are built with the exact same annotation-based system MythicMobs uses (@MythicMechanic, @MythicCondition, @MythicTargeter, @MythicPlaceholder, and SkillTrigger). There is nothing Crucible-specific about registering them, so to add your own follow the MythicMobs API guide (its "Registering Custom Components" section). Custom triggers are dispatched through the same Mythic event bus.

Updated Oct 30, 2026