[Mod] Node-IO API [node_io] WIP

[Desour]

stackitem and count parameters.

Itemstacks already have count, I don't see a reason to add count as an extra parameter.

Also pipeworks has connected_sides. Maybe rules like the one from mesecons would make sense (think of nodes that span several nodes and co.).

Could you elaborate?

Pipeworks has connected_sides to decide on which sides a tube may connect to the node.
There could be rules in form of vectors that point to a position relative to the node's position. Mesecons does the following: If the node at the position that the rule points to has a rule that points back, then the nodes are connected and signals will be transferred between them. The rules can also be given with a function.

This might contain mistakes. Don't waste your time reading too carefully:
Eg. node A has the rules {{x = 1, y = 0, z = 0}, {x = -1, y = 0, z = 0}} and node B has the rules {{x = 1, y = 0, z = 0}, {x = 0, y = 0, z = 1}}. Now there's an A node at (0,0,0), an A node at (-1,0,1) and a B node at (-1, 0, 0). The node at (0,0,0) is now turned on, so go through the rules: There's no node at (1,0,0) that has rules, but there's one at (-1,0,0), and it has a rule to (0,0,0). Turn that node on: The node at (0,0,0) is already on, there's a node at (-1,0,1) (=(-1,0,0)+(0,0,1)) that has rules. Does it have rules to (-1,0,0)? No. End here.

My idea is to add input_rules and output_rules that are used for connection of tubes and co. and that are checked before calling can_take or can_put and that are numbered so that this number can be given to the callbacks.
This probably might be is a bad idea. >_<

But at least there should be a callback that mods can call to see if there should be a connection to and/or from a side.
Like mod A has a taker and a putter and wants to see if they should visually (and hard) connect to the side of the node from mod B they are placed to.
Just something like can_connect(side) -> bool, bool.

pipeworks uses return_input_invref or decides on its own to choose from what inventory to put. Nodes should choose on their own where to put the item they get to. But if another node takes from a node, the taking node (or any other taker) might want to decide on its own from where to take. There should be a callback to give an invref and a listname to help the taker.

Node-IO was designed to put the inventory node in control, because some inventories don't use an invref. When a transfer node puts an item in a side, it is up to the inventory node where that items goes. Taking anything is the same as putting, you just ask for something from a side and the inventory chooses what you get. But a transfer node with a filter or inventory needs to know what it will get to either filter the take or verify the take will fit in its own inventory. So Node-IO has read-only callbacks to query the contents of fake inventories attached to a given side. The transfer node can then call take_item with a stackitem that filters exactly what it receives.

What about nodes that want to cycle through inventory slots or do other special stuff?

I was thinking about adding named inventories though. A transfer node would query available named inventories and then request a specific inventory to put or take. A smart pipe could be connected to any side of a furnace and the player could configure the pipe to filter fuels to the fuel inventory, ores to the src inventory and take from the dst inventory. These named inventories don't represent invrefs, they can be fake or have different names than the invrefs. And the inventory remains in control, if the furnace only wants to receive fuel from top it will only expose the named fuel inventory on that side. Dumb pipes would operate as they currently do without named inventories.

Is this something I should add?

Perhaps the callbacks should get custom string parameters where mods can add some information that might be handled by the getter or taker. (Think of a fuel putter device that adds "fuel".) Just don't use the 4th or whatever parameter and call it "custom".

I'm not sure what you are asking for.

I think, I was asking for approximately what you described but in a much more generic way. Eg. if a mod calls the put callback with custom = "fuel", the receiving node should put the item into its fuel slot.

The putter is a fake player it's documented. I first thought that was the equivalent to pipeworks' `owner` which is important. What is the putter for? Would it make sense to add a helper to create a fake_player?

Putter and taker is for logging and allow_metadata_whatever callbacks. I don't see the point of pipeworks' owner parameter, it is only for putting but not taking. Hoppers allow putting in locked chests but won't take from them, makes sense if the locked chest isn't protected and you want someone to place a hopper and fill it up. Pipeworks' owner could be used by locked chest to only allow a pipe placed by the chest owner to insert items, but it doesn't pass owner when removing which could have been used to allow an injector to take if both have same owner. I don't think node-io should care who owns what, it doesn't matter for single player, and you should be using protection mods on multiplayer. And multiple players sharing a protection will have issues if one of them places inventories and the other places the pipes. Let me know if this is wrong and there is a valid reason to pass owner.

A utility function to create fake players isn't needed. A mod either has a real player or it passes nil. And any mod that stores owner in nodes probably already has a way to create fake players for its own logging/allow_metadata_whatever.

If putter/taker is used for the allow_metadata stuff, it's a bit like the owner thing.
Does it make sense btw that mods call allow_metadata_…? Isn't this just for the case that a player accessed an invref that he shouldn't have access to? Mods can decide on other ways if a player (with a given name) should be able to manipulate inventories.
Real player or nil is not a fake player. And if the player disconnects, the taker/putter won't exist anymore which is not good. Ergo player names make more sense imo.
Note, that the pipeworks api is all but perfect. The taker would probably be useful, too.
Here is the PR that added owner. There's also a use example linked: wifi chest

I'm not totally against millibuckets and not for liters (and of course not for millicubicmeters or cubicdecimeters). Or what about mn (millinode)?

Most Americans don't know what a liter is or even what milli means.

America is not the world. In this case they are the minority. Nearly all countries in the world use the metric system. Imo this is no valid argument.
If a person doesn't know what "liter" (= 1 (dm)³) or the prefixes "milli", "giga", "femto", "nano" and co. mean, he or she can learn it easily. It will be useful information for their whole life.

All players do know what a bucket is

There are games that have no bucket. There might also be games that have a bucket that doesn't simply store exactly one source of liquid.
The mods that use the api don't have to display their liquid with the same unit as API does. A discussion about "millibucket" is actually not really important in here. Just define clearly what the unit means.

The mB unit name has been around for years in minecraft, and probably the same in minetest, you can't change it now.

Minetest is not minecraft. In minetest there never was a really good liquid transferring via pipe mod that would need units like "millibucket". The mB unit name came mostly from mc afaik. For esthetic reasons and because MTG is not the only game I would prefer another unit name.

What about unit for energy = eu => unit for volume = vu => millivolumeunits (mvu)?

Energy can be registered like a liquid, transfered in liquid pipes and stored in liquid tanks or buckets. Doing so forces it to use mB, because that is what liquid nodes display.

Or node-io could get an energy API identical to its liquid API. The liquid and millibuckets parameters become energy and quantity/count/whatever. The energy name would be something like "buildcraft:MJ" but nodes that display energy would strip off the colon and everything before it, displaying "50 MJ". "buildcraft:MJ" and "industrialcraft:EU" could be transfered over the same energy pipes, just as lava and water can over liquid pipes, but not at the same time. Every mod that creates its own energy gets to name it, so MJ for buildcraft, EU for industrial craft and RF for thermal expansion. I could create a machine and have it optionally depend on multiple energy mods and accept energy from any of them. But MJ might be easier to create than EU, so each operation requires 75MJ or 50EU. Energy is like liquid and food, lots of flavors. Try telling mod authors that only one food type is needed in the game... ;)

I'm sorry for causing misunderstanding. This was not about energy but that from the eu terminology (unit name = what the unit describes .. "unit") that is used eg. in technic. You could do the same for liquid volumes.
I'm against copying minecraft mod things. The minetest community is small and has to focus its modding into a few mods to make these good. Ergo. the minetest community is united and can mainly use one (fictive) metric system. Minetest: quality; minecraft: quantity.

I might have overlooked some points, sorry. >_< This made me tired.

[auouymous]

Itemstacks already have count, I don't see a reason to add count as an extra parameter.

Performance and querying. Say you have queried an itemstack from the inventory but only want one, so you clone the itemstack and set count to one. The count parameter avoids the need to clone the itemstack. You can also use the count to query beyond what an itemstack can hold, or what you can take in a single itemstack.

Also pipeworks has connected_sides. But at least there should be a callback that mods can call to see if there should be a connection to and/or from a side.

Do you understand that node-io's can_put_*(side) and can_take_*(side) let the inventory node specify if a given side can put or take anything? And that my working pipeworks patch calls can_put_item() to determine if a tube should visually connect to an inventory node? Is this not what you are asking for here?

pipeworks uses return_input_invref or decides on its own to choose from what inventory to put.
What about nodes that want to cycle through inventory slots or do other special stuff?

https://github.com/auouymous/test_io/bl ... t.lua#L106

Like that? As I said before, node-io has callbacks that let transfer nodes iterate over stacks inside the inventory node.

Does it make sense btw that mods call allow_metadata_…? Isn't this just for the case that a player accessed an invref that he shouldn't have access to?

allow_metadata_* doesn't make sense at all, its name suggests it returns a boolean if player can perform the action, but it is only used for logging. I provided putter/taker for transfer nodes that have an owner and want to pass it to the inventory node so it can log the action via allow_metadata_* or its own handler.

There's also a use example linked: wifi chest

That is a good example I hadn't thought of! But I feel you solved it the wrong way, pipeworks should not have been modified. The wifi chest should have owner metadata set when placed. The owner is ignored when a player is accessing the chest, but used by the pipeworks or node-io callbacks. This way multiple players could put wifi chests on a tube network.

Just define clearly what the unit means.

I will be adding definitions for all parameters to the API file.

[Desour]

Itemstacks already have count, I don't see a reason to add count as an extra parameter.

Performance and querying. Say you have queried an itemstack from the inventory but only want one, so you clone the itemstack and set count to one. The count parameter avoids the need to clone the itemstack. You can also use the count to query beyond what an itemstack can hold, or what you can take in a single itemstack.

Ok, this makes sense.

Also pipeworks has connected_sides. But at least there should be a callback that mods can call to see if there should be a connection to and/or from a side.

Do you understand that node-io's can_put_*(side) and can_take_*(side) let the inventory node specify if a given side can put or take anything? And that my working pipeworks patch calls can_put_item() to determine if a tube should visually connect to an inventory node? Is this not what you are asking for here?

Sorry, I did not understand.
can_put_item and can_take item are not well documented in "API". (But can_put_item(side) won't work because it needs pos and node before side.)
But you wrote something about it:

The can_put_* callbacks will have optional stackitem and count parameters. When stackitem item is nil, the callback works as it currently does, otherwise it works like room_for_item. This allows a pipe to test if items can be put in the inventory and display a connection, even if the inventory is full.

So, without an itemstack, the callback returns whether you can generally put something at some time from the side.
Now I understand, I think.

pipeworks uses return_input_invref or decides on its own to choose from what inventory to put.
What about nodes that want to cycle through inventory slots or do other special stuff?

https://github.com/auouymous/test_io/bl ... t.lua#L106

Like that? As I said before, node-io has callbacks that let transfer nodes iterate over stacks inside the inventory node.

Oops, I didn't see that.
But shouldn't it be get_inv_size instead of get_item_size? It doesn't give the size of any item.

Does it make sense btw that mods call allow_metadata_…? Isn't this just for the case that a player accessed an invref that he shouldn't have access to?

allow_metadata_* doesn't make sense at all, its name suggests it returns a boolean if player can perform the action, but it is only used for logging. I provided putter/taker for transfer nodes that have an owner and want to pass it to the inventory node so it can log the action via allow_metadata_* or its own handler.

allow_metadata is documented. It should return a number. Detached inventories have allow_ callbacks, too.
Afaik, these callbacks are called when a player has access to an inventory via formspec. However mods that put or take something via a machine don't need to call them. They can simply call def.node_io.can_put_item. The mod adding the node can do there basically the same as in allow_*. But it won't need a putter because it doesn't have to call its allow_* function. And machines won't for sure be bound to a putter and the putter may be not playing currently on the server. Ergo a player_name makes more sense. For logging you need a name, no objectref. It may be hard for mods to give a putter.
I'm sorry if the text was inefficient or if I didn't understand you. >_<

Just define clearly what the unit means.

I will be adding definitions for all parameters to the API file.

I've looked again to the liquid api and saw that the functions have "millibucket" in their name.
accepts_millibuckets should rather be something like accept_small_liquid_portions.
And put_liquid and co. should rather have a parameter name like "liquid_volume" instead of "millibuckets". liquid_volume can then be described that it's given in 1/1000s of the volume that a solid node takes.
You also don't say that amperes come out of the electric socket but that current comes out of the electric socket. (This is not the best example.)



Btw. could you please split the liquid and the item api in the documentation? I think, this would increase readability.

[auouymous]

But can_put_item(side) won't work because it needs pos and node before side.

I was being lazy when I wrote "(side)". The pos and node parameters are always required.

But shouldn't it be get_inv_size instead of get_item_size? It doesn't give the size of any item.

Item API uses "item" and liquid API uses "liquid". But I'll look into renaming those callbacks to avoid that confusion.

The mod adding the node can do there basically the same as in allow_*. But it won't need a putter because it doesn't have to call its allow_* function. And machines won't for sure be bound to a putter and the putter may be not playing currently on the server. Ergo a player_name makes more sense. For logging you need a name, no objectref. It may be hard for mods to give a putter.

Oops, I was saying allow_metadata_* but meant on_metadata_*. I should probably just remove the putter and taker parameters. They are optional, not meant as access control and a player isn't involved in the transfer. So any logging should indicate the transfer happened with a neighbor node instead of a player.

And put_liquid and co. should rather have a parameter name like "liquid_volume" instead of "millibuckets". liquid_volume can then be described that it's given in 1/1000s of the volume that a solid node takes. You also don't say that amperes come out of the electric socket but that current comes out of the electric socket.

If I wrote a function that is passed current as integer milliamps I would name the parameter 'milliamps' or 'current_mA'. Documentation is either not read or is forgotten, and the parameter name serves as a constant reminder. It is even more important when you learn how to use the API from an implementation in some mod instead of reading the API file.

Btw. could you please split the liquid and the item api in the documentation? I think, this would increase readability.

I thought about doing that, but the item and liquid APIs are very similar and share documentation. Separating them requires duplicating documentation and can lead to errors if something is changed in one place but not both. I have been cleaning up the API file to make it a little easier to read.