Public addon API

The mod API runs inside Minecraft on Java 21. Use it to add a machine, resource type or integration. The website’s HTTP API only serves documentation and release metadata: it cannot inspect a player’s live network or start a craft.

For an addon, depend on Nebula and compile against dev.nebulastorage.api. Keep optional mod adapters isolated so their classes are not loaded when that mod is absent. API version 1.0.0 is independent of the alpha release number. These addon examples target Nebula Storage alpha.7 and its renamed packages. Files published through alpha.6 still use dev.nexusstorage. Recompile addons when upgrading; Minecraft registry IDs and saved worlds remain unchanged.

Create a public implementation of NebulaExtension and list its fully qualified class name in META-INF/services/dev.nebulastorage.api.NebulaExtension. Put that file in your JAR resources, without a .txt suffix.

The example declares the process identifier example:pressing. That declaration alone does not add a block or recipe. Register a machine adapter that recognizes your actual item, then a recipe source offering exact inputs and outputs for this capability. Registration must not access a world.

package example.nexus

import dev.nebulastorage.api.NebulaExtension
import dev.nebulastorage.api.NebulaRegistrar
import dev.nebulastorage.api.production.ProductionCapabilityId

class ExampleExtension : NebulaExtension {
    override fun register(registrar: NebulaRegistrar) {
        registrar.capability(ProductionCapabilityId("example:pressing"))
    }
}

NebulaRecipeSource.discover receives the available process capabilities. Return only applicable offers, with stable recipe identifiers, guaranteed outputs and the original duration and energy cost. Include secondary outputs; do not substitute average probabilistic yields.

Increment revision when your source changes, including datapack reloads. Inventory fluctuations are availability changes, not a reason to rediscover the entire recipe catalogue. Discovery and template resolution must be pure, bounded and free of resource transfers.

Use NebulaPlatformExtension for a Minecraft block that must run its own processing logic. Resolve only a loaded machine, identify its persistent owner and expose every processing input and output. Energy, pressure and other native requirements stay with the original mod.

Before shipping, test partial insertion, blocked output, cancellation after consumption, chunk unload, save/reload and replacement of the machine block. Resources must remain with exactly one owner at every boundary. A simulated successful insertion is not proof that a later insertion will succeed.

Obtain queries during serverStarted and use forPlayer with the authenticated actor’s UUID. Each read still checks permission. Never accept an arbitrary UUID from a client packet as proof of identity.

Snapshots are observations, not reservations. Revalidate when performing an authorized action; release query references at serverStopped. Observers without an actor only receive public historical information.