Common transport API

[burli]

Item transport in Minetest is hacky. Hoppers for example use the inventory of nodes like chests or furnace, but this only works if the inventories have specific names. You need to add support for each new node in the hopper.

A while ago I made a hopper mod with additional nodes like ducts and a sorter. Each node needs to care about it's source and target inventory. In case of a chest it is relatively easy, but nodes can have multiple inputs like the furnace or multiple outputs like my sorter.

How about some kind of transport API? I'm not sure how this could work, but I think it would be useful to have a standard for this where mods can build on.

How could this be implemented?

[Byakuren]

Pipeworks already has callbacks for handling item insertion into nodes. Just make another callback for when a filter tries to pull from a node, instead of hard coding the use of inventories (though it could be the default)

[burli]

Ok, this gives me a hint.

As addition this transport API should be generic. Not only for items, but also for liquids, energy and so on.

I think it would be enough to define callbacks for get_item and put_item. As parameter a type could be used that the node knows what type should be transported. The node is responsible itself what it should do with the item

Any other suggestions to this topic?

[Byakuren]

I don't think a generic solution is ideal between items, liquids, and energy, because they are transferred in different ways and would benefit from different kinds of optimization.

For the following thing I am assuming that energy travels instantaneously instead of like a liquid (some Minecraft mods introduce an energy liquid).

Items:
- Discrete packets (itemstacks) which are expected to remain mostly intact while traveling through some system.
- System should track individual stacks as they flow through the nodes.

Liquids:
- Deformable liquid that flows through nodes.
- Each pipe has a certain amount of each liquid. Pipes could have a maximum capacity.
- Liquid amounts are not bundled up into stacks. For example, 500 water emitted into a pipe could spread out into into 100 tanks as 5 water units each.
- Processing would probably be done by keeping track of liquid levels in Lua and simulating flow between adjacent flowable nodes.

Energy:
- Power that transfers near-instantaneously between connected machines on an electric grid.
- Could be done by keeping track in Lua a connected forest of electric components and simulating on this network. (Approach taken by that new energy thing???).
- Could also be done by having generators pulse electricity to everything it's connected to by traversing cables (IC2 from Minecraft).
- Could also be done by traversing the connected network to find all machines, then allocate energy found provided by generators to consumers (Technic).
- In all of these, there is nothing being put / gotten from the wire nodes.

The only place you could have common get_item / put_item would be for the endpoints (connected machines). But there is no point in "unifying" items, liquids, and energy since it would just clutter the function with a bunch of if-else statements. It's cleaner to just have three different callbacks.

[Wuzzy]

If we had an official API to move an item from inventory A to inventory B, this would already solve a ton of difficulties.

Moving items between inventories is surprisingly difficult.
As long you just move from chest to chest (or chest-like), there are no problems.
But as soon as any of the inventories rejects some items in their slots, you run into problems.

The biggest challenge is that all the inventory move callbacks (e.g. you are not allowed to place cobblestone into the furnace fuel slot) are just bypassed if you just take one item out of inventory 1 (take_item) and put it into inventory 2.
So currently, you are pretty much forced to re-implement the inventory restrictions by hand again only to make sure that moving an item between inventories doesn't violate any rules.
Another problem is that these callbacks always expect a player argument. It is not possible to safely call these callbacks.

Anyway, I managed to find a solution in MineClone 2.
My approach in MCL2 is this:
I added a group “container”.
This is for all nodes with inventories. Each container type is well-defined and must obey certain names for the inventory lists.
And the group rating is for the container type.
container=2 is for containers with a single inventory list called “main”. There are no restrictions of taking/moving/adding. This is for chests, but also hoppers.
container=3 is like the above, except it is forbidden to place shulker boxes inside
container=4 is for furnaces with fuel, src and dst inventory lists.
container=5 is for double chest (left part).
container=6 is for double chest (right part).
container=1 is for other container types.

Then I just grouped all container nodes and now chests, double chests, ender chests, hoppers, dispensers and droppers are working properly.

But I needed a ton of additional helper functions to make this work. I would not recommend adoption outside of MCL2 at this stage. Most of these helper functions contain redundant code. The API is too complex for my taste. It is not extensible either. Adding a chest of different color would be easy, but if your node uses any inventory list not listed above, you're screwed.

That's why I said initially adding an official function to move an item from inventory A to inventory B while respecting ALL restrictions would help a lot.

[Wuzzy]

GitHub issue:
https://github.com/minetest/minetest/issues/6877

[burli]

I would make it even more generic. One callback for insert, one for take. The node has to deal itself what to do with the incoming.

For example the furnace. The node gets an insert callback for an item, e.g. cobblestone. The furnace itself needs to decide what to do with it. Next insert callback wants to add coal.

The API doesn't know anything about inventories.

Maybe interesting are informational like the type and position of the source node, which calls the callback. And maybe some timing information