Skip to content

Refined Storage

Jump to bottom
Gavin Lambert edited this page Feb 9, 2021 · 1 revision

The Refined Storage API is available from version 1.0.0 of the mod, provided that Refined Storage is also installed. (Starting from 1.2.2, it is only an optional dependency of this mod.)

Getting Started

Craft a "Refined Storage Peripheral" block and place it either directly next to a computer or turtle, or connected via a Wired Modem to one. Also connect this block to your Refined Storage network, either via cable or by placing it next to an existing block.

Note that due to the flexibility and power of lua coding, each peripheral block and each computer connected to it will draw a hefty chunk of extra RF/t energy on your storage system. (If you want to rebalance this, there are settings available in the server config file.)

Within your lua program, simply call APIs from refinedstorage directly — this API automatically becomes available once you reboot a computer that has an RS peripheral connected. (If you break/replace the peripheral, reboot the computer again.)

You do not need to explicitly peripheral.wrap the peripheral when there’s only one attached to the computer. If you have more than one attached (e.g. for subnetworks) then you should explicitly wrap all of them to ensure that you’re accessing the right ones — the global refinedstorage could be either of them, and it could change over time.

(Note that this only applies to 1.1.0+; if you’re still using 1.0.0 then you do have to explicitly wrap.)

API common notes

Almost all API methods will return either a single value on success (or partial success); on failure they return two values — the first is nil and the second is a string with a human-readable error message. You can ignore the second return value if you wish, but it may be useful to log it to help track down problems.

A few APIs may return nil (also with a nil error string) to indicate that no match was found (e.g. no crafting pattern exists for the specified item). Others may return an empty table in this case.

The most common error message is "not connected", which most methods will return if the peripheral block is not connected to an active Refined Storage network, or the network is out of power.

The descriptions of the APIs below will not explicitly call out that they can also return a nil error. Just remember that it’s always possible.

In addition, some APIs may throw an error if you attempt to call them with an item or fluid name that doesn’t exist in Minecraft at all (perhaps from a typo or due to a mod not being installed).

Table structures

Item descriptions

The bare minimum when supplying an item description as a parameter is the minecraft item id:

{name="minecraft:stone"}

In some cases you may need to also specify NBT values, e.g:

{name="computercraft:disk",nbt="543569198bcc713dabcbc4f9b5bf0715"}

It’s never necessary to provide any other values as a parameter, but more information is provided when receiving an item as a return value (either from a pattern or from storage). This can include the count of the item as well as decoding some properties from the NBT, such as damage and enchantments. It’s best to go look at specific items in your own storage system to figure out what values are returned.

Note that the NBT values are hashes of the actual data, and cannot be used to reconstruct the contents, to avoid breaking the progression systems of other mods that may rely on the actual values not being directly available to the player. These are the same values provided by ComputerCraft for regular inventories, so you can use them for comparison.

However on items with complex tags it’s possible for what is actually the same item with the same data to produce multiple different NBT hashes, so it can’t always be relied on. But then, Refined Storage can also have trouble dealing with items with these complex tags as well.

Some server config options are available that allow providing more reversible encodings of the data, which can sometimes help with these issues. But they have a higher risk of breaking mod progression and it’s not recommended to enable them. They might even be removed in a future mod version.

Fluid descriptions

Fluid descriptions are essentially the same as item descriptions, except that instead of a count of items they have an amount of fluid (measured in milli-Buckets or mB as usual). It’s also a lot rarer for NBT values to be required, although not impossible.

Crafting patterns

A crafting pattern will tell you if it is a processing pattern or not.

Processing patterns may have inputs, fluidInputs, outputs, and fluidOutputs.

Non-processing patterns may have inputs, outputs, and byproducts (e.g. returning empty buckets).

Crafting tasks

The stack contains the item (and count) or fluid (and amount) that was requested to craft.

The pattern contains the crafting pattern being used.

Direction values

For the APIs that accept a direction parameter, the following values are supported:

  • string: one of "down"/"up"/"north"/"south"/"west"/"east"

  • number: 0-5, where 0 is "down"

If the direction is not specified, then "down" is the default.

(Note that the relative-to-computer/turtle directions left/right/front/back/top/bottom are not supported, since the peripheral block doesn’t face any particular direction.)

Available API methods

Informational

refinedstorage.isConnected()

Whether the RS network is currently connected. This is the only API that will not return nil if the network is disconnected.

  • Returns: boolean true if the network is connected; false otherwise.

  • Since: 1.0.0

refinedstorage.getEnergyUsage()

Gets the energy usage of this network.

  • Returns: number The RF/t energy usage of this network.

  • Since: 1.0.0

refinedstorage.getStorages()

Gets the storage capacity and usage of this network.

  • Returns: table A table consisting of:

    • total: the total item and fluid storage capacity and usage of the network.

    • devices: an array of each individual storage device’s type, capacity, and usage.

  • Since: 1.0.0

refinedstorage.getItems([item])

Gets information about all items stored in the network, or all items matching a specific item name.

item

Optional

table

The item description of an item (only the name is used).

  • Returns: table An array of item descriptions.

  • Since: 1.0.0; 1.1.0 adds item parameter

refinedstorage.getFluids([fluid])

Gets information about all fluids stored in the network, or all fluids matching a specific fluid name.

fluid

Optional

table

The fluid description of a fluid (only the name is used).

  • Returns: table An array of fluid descriptions.

  • Since: 1.0.0; 1.1.0 adds fluid parameter

refinedstorage.getItem(item[, compareNBT[, evenIfZero]])

Gets information about a particular item stored in the network.

item

Required

table

The item description of the item.

compareNBT

Optional

boolean

If false, tries to find any matching item regardless of NBT; if true or omitted, won’t find items with different NBT

evenIfZero

Optional

boolean

If true, returns item information (with zero count) when there is no such item instead

  • Returns: table The item description of the first matching item found, or an empty table if there was no such item.

  • Since: 1.0.0; 1.1.0 adds evenIfZero parameter

refinedstorage.getFluid(fluid[, compareNBT[, evenIfZero]])

Gets information about a particular fluid stored in the network.

fluid

Required

table

The fluid description of the fluid.

compareNBT

Optional

boolean

If false, tries to find any matching fluid regardless of NBT; if true or omitted, won’t find fluids with different NBT

evenIfZero

Optional

boolean

If true, returns fluid information (with zero amount) when there is no such fluid instead

  • Returns: table The fluid description of the first matching fluid found, or an empty table if there was no such fluid.

  • Since: 1.0.0; 1.1.0 adds evenIfZero parameter

Auto-Crafting

refinedstorage.getPatterns([item])

Gets all known item crafting patterns, or all patterns with the specified output item.

item

Optional

table

The item description of an item (only the name is used).

  • Returns: table An array of item crafting patterns.

  • Since: 1.0.0; 1.1.0 adds item parameter

refinedstorage.getFluidPatterns([fluid])

Gets all known fluid crafting patterns, or all patterns with the specified output fluid.

fluid

Optional

table

The fluid description of a fluid (only the name is used).

  • Returns: table An array of fluid crafting patterns.

  • Since: 1.0.0; 1.1.0 adds fluid parameter

refinedstorage.hasPattern(item)

Checks whether the system knows how to craft the specified item.

item

Required

table

The item description of the output item.

  • Returns: boolean True if a pattern exists; false if it does not.

  • Since: 1.0.0

refinedstorage.hasFluidPattern(fluid)

Checks whether the system knows how to craft the specified fluid.

fluid

Required

table

The fluid description of the output fluid.

  • Returns: boolean True if a pattern exists; false if it does not.

  • Since: 1.0.0

refinedstorage.getPattern(item)

Gets information about a particular item crafting pattern.

item

Required

table

The item description of the output item.

  • Returns: table The crafting pattern for that item, or nil if no such pattern could be found.

  • Since: 1.0.0

refinedstorage.getFluidPattern(fluid)

Gets information about a particular fluid crafting pattern.

fluid

Required

table

The fluid description of the output fluid.

  • Returns: table The crafting pattern for that fluid, or nil if no such pattern could be found.

  • Since: 1.0.0

refinedstorage.getTasks()

Gets the current crafting tasks of this network.

  • Returns: table The list of crafting tasks (if any).

  • Since: 1.0.0

refinedstorage.scheduleTask(item[, count[, canSchedule]])

Schedules an item crafting task.

item

Required

table

The item description of the output item.

count

Optional

number

The number of items to craft. If omitted, it will use the count in item; if that is omitted too, it will make 1.

canSchedule

Optional

boolean

If false, it will report the crafting task but not actually start it; if true or omitted, it will be started.

  • Returns: table The crafting task (even if not scheduled), or nil if crafting is not possible (e.g. some inputs are missing)

  • Since: 1.0.0

refinedstorage.scheduleFluidTask(fluid[, amount[, canSchedule]])

Schedules a fluid crafting task.

fluid

Required

table

The fluid description of the output fluid.

amount

Optional

number

The amount (in mB) to craft. If omitted, it will use the amount in fluid; if that is omitted too, it will make 1000 mB (one bucket).

canSchedule

Optional

boolean

If false, it will report the crafting task but not actually start it; if true or omitted, it will be started.

  • Returns: table The crafting task (even if not scheduled), or nil if crafting is not possible (e.g. some inputs are missing)

  • Since: 1.0.0

refinedstorage.cancelTask(item)

Cancels an item crafting task. Note that this doesn’t automatically cancel sub-tasks.

item

Required

table

The item description of the output item.

  • Returns: number The number of pending crafting tasks successfully cancelled.

  • Since: 1.0.0

refinedstorage.cancelFluidTask(fluid)

Cancels a fluid crafting task. Note that this doesn’t automatically cancel sub-tasks.

fluid

Required

table

The fluid description of the output fluid.

  • Returns: number The number of pending crafting tasks successfully cancelled.

  • Since: 1.0.0

Transfer

refinedstorage.extractItem(item[, count[, direction]])

Extracts items from the storage network and inserts them into an inventory adjacent to the RS Peripheral block.

Note that it may extract fewer items than requested if the network is getting empty or the target inventory is getting full.

item

Required

table

The item description of item to be extracted.

count

Optional

number

The number of items to transfer. If omitted, the count in item will be used; if that is omitted, it will transfer 1 item.

direction

Optional

direction

The direction of the target inventory from the peripheral.

  • Returns: number The number of items successfully transferred (or 0 if no items could be transferred).

  • Since: 1.0.0

refinedstorage.extractFluid(fluid[, amount[, direction]])

Extracts fluid from the storage network and inserts it into a tank adjacent to the RS Peripheral block.

Note that it may extract a smaller amount than requested if the network is getting empty or the target tank is getting full.

fluid

Required

table

The fluid description of fluid to be extracted.

amount

Optional

number

The amount of fluid to transfer (in mB). If omitted, the amount in fluid will be used; if that is omitted, it will transfer 1000 mB (one bucket).

direction

Optional

direction

The direction of the target tank from the peripheral.

  • Returns: number The amount of fluid successfully transferred (or 0 if no fluid could be transferred).

  • Since: 1.0.0

Clone this wiki locally