Skip to main content

Container adapters

Container adapters provide a common public surface for ordinary blocks, helper entities, standalone tanks, and physical link nodes. Use them for manual infrastructure; normal machines can call processIO().

Item containers​

resolveItemContainerAt​

resolveItemContainerAt(dimension: Dimension, location: Vector3): ResolvedItemContainer | undefined

Resolves the item inventory accessible at one world location through DoriosLib's container system.

ParameterTypeDescription
dimensionDimensionDimension containing the endpoint.
locationVector3Block coordinates to resolve.
interface ResolvedItemContainer {
  kind: "block" | "entity" | "raw";
  owner: Block | Entity | Container;
  container: Container;
  block?: Block;
  entity?: Entity;
  via?: "link_node";
}

The return value already accounts for compatible direct containers and generic link-node indirection. It returns undefined when no accessible inventory exists.

Resource targets​

Liquid and gas adapters accept three target shapes:

type FluidContainerTarget = Block | Entity | ResolvedFluidContainer;
type GasContainerTarget = Block | Entity | ResolvedGasContainer;

Resolved endpoints contain:

PropertyTypeDescription
kind`"entity""tank"`
block`Blockundefined`
entity`Entityundefined`
via`"link_node"undefined`

Resolve liquid containers​

resolveFluidContainer(target)​

resolveFluidContainer(target: FluidContainerTarget): ResolvedFluidContainer | undefined resolves a compatible entity, block, existing resolved handle, empty UtilityCraft liquid tank, or liquid link node.

resolveFluidContainerAt(dimension, location)​

resolveFluidContainerAt(dimension: Dimension, location: Vector3): ResolvedFluidContainer | undefined resolves the endpoint at one block location.

Resolve gas containers​

resolveGasContainer(target)​

resolveGasContainer(target: GasContainerTarget): ResolvedGasContainer | undefined is the gas equivalent.

resolveGasContainerAt(dimension, location)​

resolveGasContainerAt(dimension: Dimension, location: Vector3): ResolvedGasContainer | undefined resolves a gas entity, empty gas tank block, or gas link node.

Resolution fails for entities that do not expose the corresponding dorios:fluid_container or dorios:gas_container type family.

Read allowed indices​

getFluidInputIndices / getFluidOutputIndices​

getFluidInputIndices(target: FluidContainerTarget, options?: { face?: DirectionName }): ReadonlyArray<number>
getFluidOutputIndices(target: FluidContainerTarget, options?: { face?: DirectionName }): ReadonlyArray<number>

getGasInputIndices / getGasOutputIndices​

getGasInputIndices(target: GasContainerTarget, options?: { face?: DirectionName }): ReadonlyArray<number>
getGasOutputIndices(target: GasContainerTarget, options?: { face?: DirectionName }): ReadonlyArray<number>

options.face is one of up, down, north, south, east, or west. When omitted, the adapter returns the face-independent fallback.

  • Basic containers expose their real storage indices.
  • Complex containers apply the persisted face policy.
  • Link nodes apply their per-port override, then the controller fallback.
  • Empty standalone tanks accept input index 0 and expose no output.
  • Invalid endpoints return an empty array.

Revisions​

getFluidContainerRevision / getGasContainerRevision​

getFluidContainerRevision(target: FluidContainerTarget): number | string
getGasContainerRevision(target: GasContainerTarget): number | string

Returns a value that changes when the relevant IO document changes. Link-node revisions combine the controller document and per-port override revisions into a string. Cache consumers can compare the value for inequality; do not parse it.

Invalid or unresolved targets return 0.

Transfer from an exact source index​

transferFluid​

transferFluid(source: FluidContainerTarget, options: FluidTransferOptions): number

interface FluidTransferOptions {
  sourceIndex: number;
  target: FluidContainerTarget;
  targetFace?: DirectionName;
  targetIndices?: ReadonlyArray<number>;
  maxAmount?: number;
}

transferGas​

transferGas(source: GasContainerTarget, options: GasTransferOptions): number uses the same properties with gas endpoints.

PropertyRequiredDescription
sourceIndexYesExact nonnegative source index selected by the caller. Invalid values throw TypeError.
targetYesDestination endpoint.
targetFaceNoDestination face used to resolve allowed input indices.
targetIndicesNoExplicit valid indices that override targetFace. Invalid and duplicate entries are ignored.
maxAmountNoMaximum amount moved. Defaults to all available source content. Nonpositive or nonfinite values move nothing.

The source output policy belongs to the caller. The adapter enforces destination input policy unless explicit indices are supplied. It fills compatible target indices in order and returns the total amount moved.

const moved = transferFluid(sourceEntity, {
  sourceIndex: 1,
  target: targetBlock,
  targetFace: "west",
  maxAmount: 1000,
});

Insert an external resource​

insertFluid​

insertFluid(target: FluidContainerTarget, options: FluidInsertOptions): number

interface FluidInsertOptions {
  type: string;
  amount: number;
  face?: DirectionName;
  indices?: ReadonlyArray<number>;
  exact?: boolean;
}

insertGas​

insertGas(target: GasContainerTarget, options: GasInsertOptions): number has the same option meanings.

PropertyRequiredDescription
typeYesNonempty resource type. Missing types throw TypeError; empty inserts nothing.
amountYesPositive finite amount requested.
faceNoFace used to resolve allowed inputs.
indicesNoExplicit target indices overriding face.
exactNoWhen true, inserts nothing unless the entire amount fits across compatible targets.

Empty standalone tank blocks create their resource entity on first valid insertion. Returns the actual inserted amount.

const inserted = insertGas(portBlock, {
  type: "example_hydrogen",
  amount: 250,
  exact: true,
});

Get an indexed storage wrapper​

getFluidStorage​

getFluidStorage(target: FluidContainerTarget, fluidIndex: number): FluidStorage | undefined

getGasStorage​

getGasStorage(target: GasContainerTarget, gasIndex: number): GasStorage | undefined

Both validate the endpoint and requested nonnegative index, initialize its objectives, and return a storage wrapper. Empty tank blocks without an entity return undefined until a resource insertion creates one.

Imports​

import {
  getFluidInputIndices,
  getFluidStorage,
  getGasInputIndices,
  getGasStorage,
  insertFluid,
  insertGas,
  resolveFluidContainerAt,
  resolveGasContainerAt,
  resolveItemContainerAt,
  transferFluid,
  transferGas,
} from "DoriosCore/index.js";

Remarks​

  • Resolved handles can become stale. Passing one back through its resolver refreshes it from the physical block when possible.
  • Link-node endpoints preserve the port block so per-port overrides remain enforceable.
  • Explicit indices are an advanced escape hatch. Validate them against your declared machine contract.