Skip to content

For Mod Developers

CaptainGummiball edited this page Nov 14, 2026 · 3 revisions

For Mod Developers

Most mods need nothing from this page. QNet uses the standard interfaces of the loaders: energy (1 E = 1 FE = 1 Team Reborn Energy), items, fluids and gases move through the Fabric Transfer API and the NeoForge capabilities. Cables, pipes, machines and storage of other mods connect to QNet without any code.

For everything beyond that there is a small public API, and many things work with a data pack alone.

Data packs (no code)

  • Machine recipes: JSON files under data/<namespace>/qnet/recipe/. Example, a Crusher recipe:

    {
      "type": "qnet:pulverizing",
      "items": [ { "item": "example:glimmer_dust", "count": 2 } ],
      "results": [ { "item": "minecraft:glowstone_dust", "count": 1 } ],
      "energy": 20,
      "duration": 60
    }
  • Materials: QNet reads the common c: tags (c:ingots/tin, c:dusts/tin, c:ores/tin, ...). A metal of your mod with these tags gets crushing, smelting, pressing and recycling recipes in QNet's machines without anything else.

  • Assembler: crafting recipes the Assembler must not automate go into lists under data/<namespace>/qnet/not_automatable/ as {"recipes": ["mod:recipe_id"]}.

Every recipe type, material form and the values of the machines are in the Codex.

The Java API

  • API version 1, package dev.cptgummiball.qnet.api, mod id qnet.
  • Get qnet-api-1.jar and its javadoc jar from the GitHub releases and add it as a compile-only dependency. The API is Minecraft-free.
  • Do not ship the API or any QNet files in your mod. If QNet is optional for your mod, check that the mod qnet is loaded before you touch its classes.
  • Everything runs on the server thread; returned records are read-only copies. Registrars are used during mod initialisation; registering after the server started throws.
Package What it offers
api QNetApi (registrars, lookup ids), BlockRef (dimension and packed position)
api.material, api.recipe material families and machine recipes
api.process, api.event process conditions with world context; process, formation and collapse events
api.machine MachineQuery (qnet:machine_query), MachineControl (qnet:machine_control); since 1.1.0 your machines in QNet's machine frame (QNetApi.machines())
api.multiblock StructureQuery (qnet:structure_query) on a plant's controller or ports; since 1.1.0 your own multiblocks (QNetApi.structures())
api.ui since 1.1.0: machine windows drawn by QNet (QNetApi.screens())
api.claim since 1.1.0: claim protection for machines that act on the world (QNetApi.claims())
api.fuel since 1.1.0: your fuel gases in QNet's gas burners (QNetApi.fuels())
api.storage, api.automation storage views and transactions; foreign machines for the Factory Controller
api.energy HeatPort: process heat between mods
api.resource ResourceRef: item, fluid or gas with a long amount
api.rift RiftQuery: a player's Rift atlas, research and surveyed deposits (read-only)

Lookups are Fabric BlockApiLookup and NeoForge BlockCapability with the ids above.

A few examples

  • Pause a QNet machine (MachineControl): a pause is a lease of at most 1200 ticks that you renew while you want it, so a removed caller never leaves a machine stopped. The actor is the player on whose behalf you act; a block with an owner asks its team rules and answers DENIED to strangers.

  • Plants (StructureQuery): structure id, whether it is formed, the controller position, the size and, when it does not form, the reason as a translation key.

  • Process heat (HeatPort): QNet heat sources push heat into a HeatPort in front of their HEAT ports, and QNet's HEAT ports accept heat from yours. One heat unit is about one E on the steam path.

  • Your machines in the Factory Controller (api.automation): tell QNet what your machines make, and the Factory Controller plans with them like with its own; a Machine Interface in front of the machine fills and empties it through its standard inventories.

    QNetApi.automation().register(blockId -> blockId.equals("example:press")
        ? List.of(new ProductionCapability("example:iron_plate",
              List.of(ProductionStack.item("#c:ingots/iron", 1)),
              List.of(ProductionStack.item("example:iron_plate", 1)), 100))
        : List.of());

Your own plants, windows and codex pages (since 1.1.0)

  • Multiblocks (QNetApi.structures()): register your roles (blocks come from your tag <ns>:multiblock/<role>) and a fixed plan, layer by layer, with QNet's casing, glass and ports next to your blocks. Your controller links to QNet's validation (link(...), then tick() every server tick) and gets energy, items, fluids, gases and heat through QNet's ports. Bad plans (port places on two outer faces, overlapping places, unknown roles) are refused when you register them. The Build Projector and the codex build view show your plans.

    QNetApi.structures().role("example:vat_frame");
    QNetApi.structures().plan("example:vat")
        .controller("example:vat_controller")
        .key('F', "example:vat_frame").key('C', "qnet:casing").key('_', "qnet:air")
        .portKey('P', Set.of("qnet:casing"), PortKind.ENERGY_INPUT, PortKind.FLUID_OUTPUT)
        .layer(0, "F@F", "CCC", "FCF")
        .layer(1, "CPC", "P_P", "CPC")
        .layer(2, "FCF", "CPC", "FCF")
        .ports(PortKind.ENERGY_INPUT, 1, 2)
        .register();
  • Machine windows (QNetApi.screens()): describe the window (bars, values, progress, switches, buttons, slots) and QNet draws it with the player inventory, real slots and its telemetry tab. Labels are your translation keys; a bar colour of 0 takes QNet's colour for the unit.

  • Machine frame (QNetApi.machines()): register your block and QNet's tools, the Factory Controller and the Jade tooltips see it like a QNet machine; QNet's upgrade items with QNet's rules (upgradeEffect); the telemetry tab with your own stop reasons; for a single-block machine ports(...) offers energy input, items, fluids and gases on every side to cables, pipes and hoppers of both loaders, without loader code of your own.

  • Fuel gases (QNetApi.fuels()): give your Pipster gas a heating value (1 to 16 HU/mB) and QNet's Gas Turbine, Piston Engine and Gas Flare burn it; the Gas Compressor compresses it.

  • Claims (QNetApi.claims()): ask the claim mods QNet is connected to (Open Parties and Claims, FTB Chunks) before your machine acts on a place.

  • Codex pages: ship pages as resources in your namespace (assets/<ns>/qnet_guide/<lang>/); they appear in QNet's codex with a badge, can link to QNet's pages and show the 3D build view of your structures. Format and generator: codex format 1.

Stability

The API version changes only with an incompatible change, and then the jar gets a new name. Additions keep the version. Deprecated members stay at least two minor releases or six months. Each release is checked against the frozen list of API version 1.

ComputerCraft

With CC: Tweaked installed, every QNet machine and plant controller is a peripheral of type qnet, and the Factory Controller also of type qnet_factory (plans, orders and stock targets). The methods are listed on the codex page ComputerCraft.

License

The license allows compiling against the API and publishing mods that use it. See License and Permissions.

Clone this wiki locally