Developer Integration - mess1re/axiomata GitHub Wiki

Dependency

repositories {
    maven("https://jitpack.io")
    maven("https://maven.architectury.dev/")
}

dependencies {
    implementation("com.github.mess1re.axiomata:${minecraftVersion}-${loader}:${axiomataVersion}")
}

minecraftVersion and loader select the matching build; axiomataVersion is the release tag. ForgeGradle projects should pass the coordinate through fg.deobf(...).

Declare both axiomata and Architectury API in the loader metadata.

Add a drawable blueprint

A complete drawable blueprint needs:

data/<namespace>/blueprints/<id>.json
data/<namespace>/blueprint_outlines/<id>.json
assets/<namespace>/textures/blueprint/<id>.png

See Blueprint Data and Drawing Outlines. Registration code and a blueprint index are not required.

Implement staged construction

The deployed entity implements UnderConstruction and owns one persistent BuildProgress.

private final BuildProgress buildProgress = BuildProgress.finished();

@Override
public BuildProgress buildProgress() {
    return buildProgress;
}

Save and load BuildProgress with the entity NBT. Override these hooks only where needed:

Hook Purpose
orientForPlacement(yaw) Apply the same authored orientation to preview and result
onDeployed(yaw) Initialize the placed result
onBuildProgressChanged() Synchronize render or gameplay state
acceptsBlowOnStage(player, section) Validate which model section was hit

While isFullyBuilt() is false, the consuming entity should block its finished gameplay and render only completed/current construction sections.

Construction markup

Each model has one markup file, loaded with the data packs and sent to clients by the server:

data/<namespace>/construction/<model>.json

{
  "boneCubes": { "frame": 4, "wheels": 8 },
  "sections": [
    {
      "name": "frame",
      "bones": { "frame": [0, 1, 2, 3] },
      "box": [-16, 0, -16, 16, 24, 16],
      "parts": [
        { "center": [0, 0.75, 0], "halfExtent": [1, 0.75, 1], "rotation": [1, 0, 0, 0, 1, 0, 0, 0, 1] }
      ]
    }
  ]
}
  • boneCubes: cube count of every bone with cubes. If the loaded model differs, the client draws it finished instead of highlighting the wrong cubes.
  • bones: which cubes of which bones belong to the section, by their index in the bone. The client draws the section from these.
  • parts: the same cubes as placed in the model, in entity-local blocks (centre, half size, 3×3 rotation by rows). A hammer blow counts only when it lands on one of them.
  • box: the section's envelope in model pixels, used for hits when parts is missing.

Section names must match the blueprint stages. Read the markup through BlueprintConstructionVisuals.sections and bounds.

The Blockbench Tool stores the section assignments in the model. Writing this file from the model remains the integrating mod's responsibility.

Public blueprint API

API Use
BlueprintDefinitions Read the synchronized definition catalog
BlueprintStacks Identify or create blueprint/result stacks
BlueprintPermissions Run recipe-use permission checks
ConstructionDeployer Place a blueprint result programmatically
ConstructionWork Apply or undo one unit of work from any Container
BlueprintConstructionVisuals Read construction markup and translated stage names

axiomata:construction_hammers controls which main-hand items can open a blueprint. Field-construction interaction currently uses Axiomata's construction hammer item; adding an unrelated item to the tag alone does not implement hammer strikes.

Events

Events use Architectury's loader-neutral event API.

Event Timing Can deny
BlueprintEvents.CREATION_CHECK Before a traced blueprint is taken yes, deny()
BlueprintEvents.CREATED After a traced blueprint is taken no
BlueprintEvents.RECIPE_CHECK Before a blueprint is used yes, deny()
BlueprintEvents.USED After direct crafting or successful placement no 
BlueprintEvents.RECIPE_CHECK.register(event -> {
    if (event.recipeId.startsWith("example:restricted/")) {
        event.deny();
    }
});

USED reports successful blueprint use, not completion of later construction stages.

BlueprintUsedEvent.placed() returns the entity placed by field construction. It is null for a result given to the player's inventory. Use it when an integration needs the new construction site, for example to assign its owner.

⚠️ **GitHub.com Fallback** ⚠️