Developer documentation

Minecraft addon API

dev.nebulastorage.api · Java 21 · Kotlin · NeoForge 1.21.1

A simulation never owns a resource. A physical adapter must preserve inputs, outputs and its receipt in the same durable owner.

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.

Registration example

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"))
    }
}

META-INF/services/dev.nebulastorage.api.NebulaExtension

example.nexus.ExampleExtension

Website API

OpenAPI 3 · JSON · GET

Read-only endpoints on https://ns-api.vyxs.fr. No account or API key is required. The website uses the same data through its server.

GET /v1/catalogue?locale=en&q=server
GET /v1/entries/controller?locale=fr
GET /v1/releases?locale=en
GET /v1/downloads/0.1.0-alpha.5

/v1/catalogue

A light index of entries. Filter with locale, q (up to 120 characters) and category; use a slug to fetch the full article.

/v1/entries/{slug}

The full article, recipe slots and diagrams. Locale supports en, fr, de, es, it and ja; an unknown slug returns 404.

/v1/releases

Verified published versions, including the filename, byte size and SHA-256. Localized notes follow locale. New releases appear after the next polling and cache refresh.

/v1/downloads/{version}

Streams the JAR for a published version. Check its SHA-256 against the release metadata. Unknown versions return 404; an unavailable or unverified file returns 503.

Invalid parameters return 400. A rate limit returns 429 with Retry-After. Cache successful reads; wait before retrying a temporary failure. No endpoint can mutate a Minecraft network.

Integration scope

JEI and EMI show recipes; Ponder provides tutorials in game. Supported machines include Vanilla, Mekanism and several other mods. See the integration list for the supported processes and exclusions.